adobe / adobe/spectrum-design-data

SPEC-027: design-owner sign-off needed for 3 remaining dangling tokenBindings (button corner-radius)

Open
#1,269 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
153
Forks
35
Avg merge
7h 54m
Merged PRs (30d)
111

Description

## Summary

During SPEC-027 triage (bead `spectrum-design-data-vpk`, PR #1267) we cleared 84 of 134 dangling `tokenBindings[].token` references (confident typo/word-order renames or garbage removals). The remaining **50 bindings could not be confidently resolved automatically** — each needs a design-owner call: pick a target, define a new token, or confirm removal.

Tracked in bead `spectrum-design-data-vpk.1`.

## A. Pick among existing candidate tokens (ambiguous mapping) — 13 bindings

| Component | Binding | Candidates | Decision needed |
|---|---|---|---|
| alert-dialog | `alert-dialog-top-to-alert-icon` | `alert-banner-top-to-alert-icon`, `field-top-to-alert-icon-{size}` | Should alert-dialog reuse alert-banner's spacing value? |
| button | `corner-radius-button-{small,large,extra-large}` | `corner-radius-{small,medium,large,extra-large}-default` | Which rounding family maps to which button size? A 4th slot already binds `corner-radius-extra-large-default` in the same context — mapping is unclear. |
| combo-box | `in-field-progress-circle` | `in-field-progress-circle-size-{75,100,200,300}` | No size suffix given — which size? |
| cards | `card-header-to-footer` | `card-description-to-footer`, `card-header-to-description` | Context says "text to visual", matches neither candidate. |
| cards | `card-title-to-description` | `card-header-to-description` | Is "header" the same concept as "title" here? |
| date-picker | `range-border-dash-{length,gap,thickness}` | `drop-zone-border-dash-{length,gap}` vs `drop-target-dash-{length,gap}` | Two competing families — which one? `-thickness` has no family at all either way. |
| drop-zone | `component-top` | `component-top-to-text-{50,75,100,200,300}`, `component-top-to-workflow-icon-*` | Value is truncated (missing `-to-X` suffix) — which target? |
| drop-zone | `text-300` | 7+ candidates share the `text-300` suffix | Truncated/ambiguous prefix, no way to pick without design input. |
| drop-zone | `accent-content-color` | `accent-content-color-{default,down,hover,key-focus,selected}` | Only state-suffixed variants exist — which state was intended? |
| list-view | `component-edge-to-text` | sibling pattern `stack-item-edge-to-{control,visual}` | `stack-item-edge-to-text` doesn't exist — no exact match. |
| table | `table-selected-row-background-{color,opacity}-highlight(-hover)` | family only has bare + `-non-emphasized` | Does "highlight" mean the default/bare value, or is it a genuinely missing third variant? |
| tree-view | `title-content-color` | full neutral/subdued/disabled family exists | Doesn't fit any existing state — which one, if any? |

## B. Likely genuine gaps — new token may need to be created — 14 bindings

| Component | Binding | Why it looks real (not garbage) |
|---|---|---|
| avatar | `gradient-angle` | No "angle" token exists anywhere — a real, unbuilt concept (gradient rotation angle). |
| combo-box, number-field, text-area, text-field | `component-top-to-workflow-icon-400` | Family caps at `-300` (50/75/100/200/300); **4 different components** want a `-400` step — strong signal this is a missing scale step, not a typo. |
| date-picker | `current-day-indicator-size-100` | "current day" / "today" indicator concept isn't built at all. |
| date-picker | `strikethrough-day-{thickness,orientation}` | No "strikethrough" token exists anywhere. |
| date-picker | `date-picker-text-to-in-field-button` | Closest analog (`number-field-visual-to-in-field-stepper-{size}`) is a different component/semantics. |
| menu | `popover-submenu-to-menu-item-position` | No "submenu" token exists anywhere. |
| menu | `menu-item-to-items` | No item-to-item spacing token exists for menu. |
| radio-button | `neutral-content-color-selected-{default,hover,key-focus}` | Existing `neutral-subdued-content-color-selected` is singular (no per-state variants) — shape mismatch (subdued vs not, 1 vs 3 states). |
| tabs | `tab-selection-indicator-thickness` | Zero backing family (only unrelated `side-navigation-indicator-thickness` exists). |
| title | `font-family`, `font-weight`, `font-size`, `line-height`, `font-style` (context "Title-XXXL") | Bare, unqualified property names — picking the correct scale step/weight for an XXXL title style is a typography design decision. |

## C. Likely invalid/duplicate — probably REMOVE, but flagged for sign-off — 9 bindings

| Component | Binding | Why it's probably garbage |
|---|---|---|
| cards *(owned by #5d7-tracked work — needs owner sign-off per project rule)* | `card-edge-to-content-{compact,default,spacious}-extra-medium` (3) | "extra-medium" isn't a real scale step (family is extra-small/small/medium/large/extra-large). |
| cards | `card-selection-background-corner-radius-{small,medium,large,extra-large}` (4) | `card-selection` only has background-size/-color tokens — no corner-radius family at all. |
| cards | `card-thumbnail-to-title` | Zero backing family, no plausible candidate. |
| cards | `horizontal-card-edge-to-content-regular` | Valid siblings are only compact/default/spacious — "regular" looks like a stray duplicate of `-default`. |
| tabs | `tab-item-to-tab-item-compact-horizontal-medium` | No "compact" variant exists for this spacing family (only `horizontal-{size}`/`vertical-{size}`). |

## What we need from design

1. **Category A (13 bindings)** — pick the correct existing target token for each ambiguous mapping.
2. **Category B (14 bindings)** — confirm whether a new token should be created (and what value), especially the `component-top-to-workflow-icon-400` gap since 4 components independently want it.
3. **Category C (9 bindings)** — confirm these are safe to remove (dead/duplicate bindings with no real backing concept).

**Totals**: 50 bindings across 17 component files — 11 of them (all in `cards.json`) require sign-off from whoever owns the cards component work.

Once resolved, the fixes land as a follow-up to bead `spectrum-design-data-vpk.1`, and — if the SPEC-027 dangling-binding count reaches 0 — `--components-report-only` can be removed from `packages/design-data/moon.yml`'s `validate` task, making SPEC-027 a hard CI gate.

Contributor guide

Open the contributing guide

Research direction

Review the 17 component JSON files tracked by bead spectrum-design-data-vpk.1 and compare the listed dangling bindings with their candidate token families. The work is done when design owners decide the mappings, new tokens, or removals for all 50 bindings, the follow-up reaches zero dangling references, and packages/design-data/moon.yml can enforce the validation gate.

Written by the indexing model from the issue text.

Assessment

Domain
build-system, design
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.