@adobe/spectrum-design-data

Spectrum design tokens in cascade format — the canonical source of truth for @adobe/spectrum-tokens.

What is the cascade format?

Each .tokens.json file in tokens/ is a JSON array of spec-compliant token objects. Each token carries a structured name object with taxonomy fields (component, property, state, colorFamily, scaleIndex, etc.) instead of a flat kebab-case string. The format is defined in packages/design-data-spec.

// tokens/color-palette.tokens.json (excerpt)
[
  {
    "name": { "property": "color", "colorFamily": "blue", "scaleIndex": 100 },
    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
    "value": "#E9F4FF",
    "uuid": "…"
  }
]

Relationship to @adobe/spectrum-tokens

packages/tokens/src/ (the legacy flat-object format consumed by Style Dictionary and downstream tooling) is generated from this package. Do not edit packages/tokens/src/ directly — changes will be overwritten.

To regenerate the legacy package after editing tokens here:

moon run design-data:legacy-output

Token corpus

8 files, 4 166 cascade tokens (from 2 460 legacy entries):

| File | Description | | ----------------------------- | ----------------------------------- | | color-palette.json | Global color scale (blues, reds, …) | | color-component.json | Component-scoped color tokens | | color-aliases.json | Semantic color aliases | | semantic-color-palette.json | Semantic/contextual palette | | typography.json | Font sizes, weights, families | | layout.json | Global spacing and sizing | | layout-component.json | Component-scoped layout tokens | | icons.json | Icon sizing tokens |

Name-object quality

95% of tokens carry structured name objects:

• 23% enriched from sidecar name metadata (colorFamily, scaleIndex, variant, …)
• 71% decomposed from the legacy key (component + property + state)
• 6% thin (full legacy key stored in property) — tracked as SPEC-017 tech debt

moon tasks

| Task | Command | Purpose | | ------------------------ | --------------------------------------------- | ----------------------------------------------------- | | validate | moon run design-data:validate | Validate cascade files against spec rules | | legacy-output | moon run design-data:legacy-output | Regenerate packages/tokens/src/ | | roundtrip-verify | moon run design-data:roundtrip-verify | CI guard: fail if cascade and legacy diverge | | regenerate-from-legacy | moon run design-data:regenerate-from-legacy | Re-sync cascade from legacy (one-time / escape hatch) |

Consuming the cascade format

import colorPalette from "@adobe/spectrum-design-data/tokens/color-palette";
// colorPalette is an array of cascade token objects