feat: token-to-spec gap analysis, registry expansion, scaleIndex field, and spec proposals

.changeset/proposal-009-typography-scale-composite.md

@@ -0,0 +1,8 @@
+---
+"@adobe/spectrum-tokens": minor
+---
+
+Implement Proposal 009: introduce `typography-scale` composite tokens that
+bundle font-size and line-height for each typographic tier. Deprecates 18
+separate `line-height-font-size-*` tokens with `renamed` pointers to the
+new composite names.

.changeset/proposal-010-composite-token-support.md

@@ -0,0 +1,9 @@
+---
+"@adobe/design-data-spec": minor
+---
+
+Add composite token support (Proposal 010). Introduces a `$valueType` field for
+declaring a token's value-type schema. Defines three composite value-type schemas
+(`typography`, `drop-shadow`, `typography-scale`) under `schemas/value-types/`.
+Adds inline alias reference rules and three new validation rules (SPEC-014,
+SPEC-015, SPEC-016). No breaking changes — `$valueType` is optional.

.changeset/registry-anatomy-variants-expansion.md

@@ -0,0 +1,8 @@
+---
+"@adobe/design-system-registry": minor
+---
+
+Add 8 anatomy terms (field, fill, value, container, chevron, loupe, dot,
+and related) and 5 semantic dialog variants (confirmation, destructive,
+warning, error, information) to close vocabulary gaps identified during
+token spec gap analysis.

.gitignore

@@ -131,3 +131,7 @@ temp-*
 
 # auto-generated token files (copied by prepare scripts)
 docs/s2-tokens-viewer/tokens/
+
+# Graph tool output (ferrograph, graphify)
+.ferrograph
+graphify-out/

docs/proposals/001-typography-taxonomy.md

@@ -0,0 +1,80 @@
+# Proposal 001: Typography Taxonomy
+
+**Status:** Draft\
+**Affects:** 221 active tokens in `typography.json`\
+**Spec reference:** taxonomy.md line 76 — "Additional categories do and will exist for other token types (e.g. color, typography)."
+
+## Problem
+
+Typography tokens encode three concepts that have no field in the current 13-field semantic/layout taxonomy:
+
+| Concept              | Term examples                            | Token count | Example token                             |
+| -------------------- | ---------------------------------------- | ----------- | ----------------------------------------- |
+| Writing system       | `cjk`                                    | 99          | `body-cjk-font-weight`                    |
+| Font family          | `sans-serif`, `serif`                    | 135         | `title-sans-serif-emphasized-font-weight` |
+| Typographic emphasis | `emphasized`, `strong`, `heavy`, `light` | 186         | `heading-cjk-heavy-emphasized-font-style` |
+
+These terms are currently classified as "known gap" segments by the token-mapping-analyzer. They decompose but cannot roundtrip because there is no field to serialize them from.
+
+## Proposal
+
+Add three typography-scoped name object fields to the taxonomy spec.
+
+### `script`
+
+Writing system variant. Determines which character set and rendering rules apply.
+
+| Value | Description                      |
+| ----- | -------------------------------- |
+| `cjk` | Chinese, Japanese, Korean script |
+
+Registry: `packages/design-system-registry/registry/scripts.json` (new file)
+
+### `family`
+
+Font family category. Determines the typeface classification.
+
+| Value        | Description         |
+| ------------ | ------------------- |
+| `sans-serif` | Sans-serif typeface |
+| `serif`      | Serif typeface      |
+
+Registry: `packages/design-system-registry/registry/families.json` (new file)
+
+### `emphasis`
+
+Typographic weight or emphasis level. Shared with component property axes (see Proposal 002), but with extended vocabulary for typography.
+
+| Value            | Context    | Description                                               |
+| ---------------- | ---------- | --------------------------------------------------------- |
+| `emphasized`     | Both       | Standard emphasis                                         |
+| `strong`         | Typography | Strong emphasis (heavier than emphasized)                 |
+| `heavy`          | Typography | Heaviest emphasis                                         |
+| `light`          | Typography | Lighter than default                                      |
+| `non-emphasized` | Components | Explicitly not emphasized (maps to `isEmphasized: false`) |
+
+Registry: `packages/design-system-registry/registry/emphasis.json` (new file)
+
+### Serialization order
+
+Typography tokens use the standard semantic/layout order, with typography fields inserted after `component`:
+
+```
+{variant}-{component}-{script}-{family}-{emphasis}-{structure}-{substructure}-{anatomy}-{object}-{property}-{orientation}-{position}-{size}-{density}-{shape}-{state}
+```
+
+### Examples
+
+| Current token name                        | Proposed name object                                                                            |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `body-cjk-emphasized-font-weight`         | `{ component: "body", script: "cjk", emphasis: "emphasized", property: "font-weight" }`         |
+| `title-sans-serif-emphasized-font-style`  | `{ component: "title", family: "sans-serif", emphasis: "emphasized", property: "font-style" }`  |
+| `heading-cjk-heavy-emphasized-font-style` | `{ component: "heading", script: "cjk", emphasis: "heavy-emphasized", property: "font-style" }` |
+
+Note: `heavy-emphasized` is a compound emphasis value (heavy + emphasized). This follows the same pattern as compound states in Proposal 005.
+
+## Impact
+
+* 221 active tokens move from MEDIUM to HIGH confidence
+* Three new registry files created
+* Taxonomy spec updated with typography scope section

docs/proposals/002-component-property-axes.md

@@ -0,0 +1,110 @@
+# Proposal 002: Component Property Axes — `style`, `staticColor`, `emphasis`
+
+**Status:** Draft\
+**Affects:** 234 active tokens across `color-aliases.json`, `color-component.json`, `icons.json`, `semantic-color-palette.json`\
+**Spec reference:** taxonomy.md — name object field definitions
+
+## Problem
+
+Component schemas define four independent variant-like axes, but the token taxonomy has only a single `variant` field. Tokens encoding multiple axes cannot be decomposed:
+
+| Schema property       | Type                   | Components                            | Token pattern                      |
+| --------------------- | ---------------------- | ------------------------------------- | ---------------------------------- |
+| `variant` (enum)      | Primary color/semantic | 16 components                         | Already handled                    |
+| `style` (enum)        | Visual treatment       | badge, button, in-line-alert, etc.    | `subtle`, `subdued`, `primary`     |
+| `staticColor` (enum)  | Theme-override color   | button, action-button, link, etc.     | `static-black-*`, `static-white-*` |
+| `isEmphasized` (bool) | Emphasis toggle        | action-button, checkbox, switch, etc. | `emphasized`, `non-emphasized`     |
+
+These are **non-mutually-exclusive**. A Badge can be `variant: "blue"` AND `style: "subtle"` simultaneously. A Button can be `variant: "primary"` AND `staticColor: "white"` at the same time.
+
+### Why not array variant?
+
+The component schemas model these as **separate named properties**, not as multiple values on one axis. Flattening them into `variant: ["blue", "primary"]` loses the distinction between which axis each value belongs to and creates ambiguity (is `"primary"` a color variant or a style?).
+
+## Proposal
+
+Add three name object fields that directly mirror component schema properties.
+
+### `style`
+
+Visual treatment or presentation style of a component. Maps to component schema `style` enum.
+
+| Value       | Description                                              | Used by              |
+| ----------- | -------------------------------------------------------- | -------------------- |
+| `subtle`    | Reduced visual emphasis                                  | badge, in-line-alert |
+| `subdued`   | Quieter than subtle                                      | neutral tokens       |
+| `bold`      | Strong visual emphasis                                   | badge, in-line-alert |
+| `outline`   | Outline-only treatment                                   | badge, button        |
+| `primary`   | Primary emphasis (when used as style, not color variant) | icon tokens          |
+| `secondary` | Secondary emphasis                                       | icon tokens          |
+
+Registry: Add to `packages/design-system-registry/registry/styles.json` (new file)
+
+### `staticColor`
+
+Theme-override color modifier. Maps to component schema `staticColor` enum. Indicates the token does not change with theme — it always uses the specified color context.
+
+| Value   | Description                |
+| ------- | -------------------------- |
+| `black` | Black static color context |
+| `white` | White static color context |
+
+Registry: Add to `packages/design-system-registry/registry/static-colors.json` (new file)
+
+### `emphasis`
+
+Emphasis level. Maps to component schema `isEmphasized` boolean. Shared with typography taxonomy (see Proposal 001) which extends the vocabulary.
+
+| Value            | Description               |
+| ---------------- | ------------------------- |
+| `emphasized`     | Emphasized presentation   |
+| `non-emphasized` | Explicitly not emphasized |
+
+Registry: Shared with Proposal 001's `packages/design-system-registry/registry/emphasis.json`
+
+### Serialization order
+
+These three fields are inserted after `shape`, before `state`:
+
+```
+{variant}-{component}-{structure}-{substructure}-{anatomy}-{object}-{property}-{orientation}-{position}-{size}-{density}-{shape}-{style}-{emphasis}-{staticColor}-{state}
+```
+
+### Examples
+
+| Current token name                                   | Proposed name object                                                                                                               |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `accent-subtle-background-color-default`             | `{ variant: "accent", style: "subtle", object: "background", property: "color", state: "default" }`                                |
+| `icon-color-blue-primary-default`                    | `{ component: "icon", variant: "blue", style: "primary", property: "color", state: "default" }`                                    |
+| `neutral-subdued-background-color-hover`             | `{ variant: "neutral", style: "subdued", object: "background", property: "color", state: "hover" }`                                |
+| `static-black-text-color`                            | `{ variant: "static", staticColor: "black", anatomy: "text", property: "color" }`                                                  |
+| `disabled-static-white-background-color`             | `{ variant: "static", staticColor: "white", object: "background", property: "color", state: "disabled" }`                          |
+| `stack-item-selected-background-color-emphasized`    | `{ component: "stack", substructure: "item", state: "selected", object: "background", property: "color", emphasis: "emphasized" }` |
+| `table-selected-row-background-color-non-emphasized` | `{ component: "table", state: "selected", anatomy: "row", object: "background", property: "color", emphasis: "non-emphasized" }`   |
+
+### Impact by field
+
+| Field            | Tokens resolved | Primary source files                                        |
+| ---------------- | --------------- | ----------------------------------------------------------- |
+| `style`          | 88              | semantic-color-palette.json, color-aliases.json, icons.json |
+| `staticColor`    | 12              | color-aliases.json                                          |
+| `emphasis`       | 36              | color-component.json, color-aliases.json                    |
+| **Total unique** | **\~234**       |                                                             |
+
+### Interaction with existing `variant` field
+
+With these new fields, the existing `variant` field should be narrowed to its original purpose: the primary color or semantic variant of a component. Values like `subtle`, `subdued`, `static` should be **removed from `variants.json`** (added in Phase 1) and instead live in their proper registries (`styles.json`, `static-colors.json`).
+
+The `variant` registry categories (emphasis, semantic, color, context) map cleanly:
+
+* **color** → stays in `variant` (`blue`, `red`, `accent`, etc.)
+* **semantic** → stays in `variant` (`negative`, `positive`, `informative`, etc.)
+* **emphasis** → moves to `style` (`subtle`, `subdued`, `primary`, `secondary`)
+* **context** → `static` stays in `variant`, `black`/`white` move to `staticColor`
+
+## Impact
+
+* 234 active tokens move from MEDIUM to HIGH confidence
+* Two new registry files, one shared with Proposal 001
+* Serialization order updated in taxonomy spec
+* Aligns token naming with component schema architecture

docs/proposals/003-numeric-scale-index.md

@@ -0,0 +1,52 @@
+# Proposal 003: Numeric Scale Index
+
+**Status:** Implemented\
+**Affects:** 280 active tokens across all source files\
+**Spec reference:** taxonomy.md — name object field definitions
+
+## Problem
+
+Foundational scale tokens use numeric indices (e.g., `spacing-100`, `accent-color-900`, `font-size-200`) that have no field in the 13-field taxonomy. These are the backbone of the design system — spacing, color palette scales, font sizes, border widths, corner radii, and drop-shadow values all use this pattern.
+
+| Pattern                    | Count | Examples                                                     |
+| -------------------------- | ----- | ------------------------------------------------------------ |
+| `{property}-{number}`      | \~120 | `spacing-100`, `border-width-200`                            |
+| `{variant}-color-{number}` | \~80  | `accent-color-900`, `negative-color-400`                     |
+| `{compound}-{number}`      | \~80  | `font-size-200`, `corner-radius-400`, `drop-shadow-blur-100` |
+
+The analyzer currently flags these as `numeric-scale-index` gaps. They decompose correctly except for the numeric segment, which has no field to land in.
+
+## Proposal
+
+Add `scaleIndex` as a numeric field on the name object.
+
+### Definition
+
+* **Type:** Integer (non-negative)
+* **Values:** Any non-negative integer, typically from the set: 0, 25, 50, 75, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600
+* **Validation:** Advisory (warn if not in the known scale set)
+* **Cascade:** Does not participate in cascade resolution
+
+### Serialization
+
+Appended at the end of the serialized name, after all other fields:
+
+```
+{variant}-{component}-...-{state}-{scaleIndex}
+```
+
+### Examples
+
+| Current token name         | Proposed name object                                               |
+| -------------------------- | ------------------------------------------------------------------ |
+| `spacing-100`              | `{ property: "spacing", scaleIndex: 100 }`                         |
+| `accent-color-900`         | `{ variant: "accent", property: "color", scaleIndex: 900 }`        |
+| `font-size-200`            | `{ property: "font-size", scaleIndex: 200 }`                       |
+| `corner-radius-400`        | `{ property: "corner-radius", scaleIndex: 400 }`                   |
+| `background-layer-1-color` | `{ object: "background", property: "layer-color", scaleIndex: 1 }` |
+
+## Impact
+
+* 280 active tokens gain a proper field for their numeric index
+* All scale tokens can roundtrip correctly
+* No breaking change to existing tokens — additive field only

docs/proposals/004-drop-shadow-classification.md

@@ -0,0 +1,73 @@
+# Proposal 004: Drop-Shadow Classification
+
+**Status:** Draft\
+**Affects:** 31 active tokens in `color-aliases.json`, `layout.json`, `layout-component.json`\
+**Spec reference:** taxonomy.md — structures registry
+
+## Problem
+
+`drop-shadow` appears across color and layout tokens as both a grouping concept and a compound property. It has sub-properties (`blur`, `x`, `y`, `color`) and modifiers (`emphasized`, `ambient`, `dragged`, `elevated`, `transition`, `key`).
+
+Current tokens have no consistent decomposition because `drop-shadow` doesn't fit cleanly into any existing field:
+
+* Not a `component` — it's a visual effect, not a UI component
+* Not a `property` — it groups multiple properties (blur, x, y, color)
+* Not an `object` — it's not a styling surface like background/border
+
+## Proposal
+
+Classify `drop-shadow` as a **structure** in the design system registry.
+
+### Rationale
+
+Structures are defined as "individual objects or object categories that have shared styling... structures and visual patterns that can or do occur across many varieties of components." Drop-shadow is a visual pattern that occurs across many components and has shared styling properties.
+
+### Registry change
+
+Add to `packages/design-system-registry/registry/structures.json`:
+
+```json
+{
+  "id": "drop-shadow",
+  "label": "Drop Shadow",
+  "description": "Elevated shadow effect applied to components and containers"
+}
+```
+
+### Sub-properties as `property` values
+
+| Sub-property | Description        |
+| ------------ | ------------------ |
+| `blur`       | Shadow blur radius |
+| `x`          | Horizontal offset  |
+| `y`          | Vertical offset    |
+| `color`      | Shadow color       |
+
+### Context modifiers
+
+The terms `ambient`, `dragged`, `elevated`, `transition`, `key` describe drop-shadow contexts. These should be treated as **variants**:
+
+| Modifier     | Description                          |
+| ------------ | ------------------------------------ |
+| `ambient`    | Ambient/diffuse shadow               |
+| `dragged`    | Shadow during drag interaction       |
+| `elevated`   | Elevated surface shadow              |
+| `transition` | Shadow during transition             |
+| `key`        | Key light shadow                     |
+| `emphasized` | Emphasized shadow (see Proposal 002) |
+
+### Examples
+
+| Current token name                   | Proposed name object                                                                      |
+| ------------------------------------ | ----------------------------------------------------------------------------------------- |
+| `drop-shadow-blur-100`               | `{ structure: "drop-shadow", property: "blur", scaleIndex: 100 }`                         |
+| `drop-shadow-color-100`              | `{ structure: "drop-shadow", property: "color", scaleIndex: 100 }`                        |
+| `drop-shadow-dragged-x`              | `{ structure: "drop-shadow", variant: "dragged", property: "x" }`                         |
+| `drop-shadow-emphasized-hover-color` | `{ structure: "drop-shadow", emphasis: "emphasized", property: "color", state: "hover" }` |
+| `drop-shadow-elevated-key-color`     | `{ structure: "drop-shadow", variant: "elevated-key", property: "color" }`                |
+
+## Impact
+
+* 31 active tokens gain a proper structural classification
+* Leverages existing `structure` field — no schema change needed
+* Drop-shadow sub-properties and context modifiers cleanly decompose