@adobe/design-data-spec 1.5.0 → 2.0.0

package/spec/registry.md

@@ -6,15 +6,13 @@ This document defines the **design system registry**: the set of named value col
 
 ## What a registry is
 
-A **registry** is a JSON file in `@adobe/design-system-registry` that declares an ordered list of named values. Each value has at minimum an `id` (the canonical string used in token names and component files) and a `label` (a human-readable display name). Values **MAY** carry additional fields such as `description`, `aliases`, `deprecated`, and `usedIn`.
+A **registry** is a JSON file in `@adobe/spectrum-design-data` (under `registry/`) that declares an ordered list of named values. Each value has at minimum an `id` (the canonical string used in token names and component files) and a `label` (a human-readable display name). Values **MAY** carry additional fields such as `description`, `aliases`, `deprecated`, and `usedIn`.
 
 Registries are the authoritative source of truth for vocabulary validation. A validator SHOULD flag token field values that are not present in the corresponding registry (typically as a warning, not an error — see field declarations in the field catalog).
 
 ## Packaging strategy
 
-All registries ship as a **single package**: `@adobe/design-system-registry`. The three semantically distinct registries described below are separate JSON files within that package. Independent sub-package splits are explicitly deferred.
-
-**Rationale:** No external consumers currently require independent semver versioning of individual registries. A single package is cheaper to maintain, simpler to consume, and avoids the proliferation of tiny packages with coordinated versioning overhead. If independent versioning needs emerge in a future release, the split can be done with a standard deprecation window per [Evolution](evolution.md).
+All registries ship within **`@adobe/spectrum-design-data`** under the `registry/` directory. The three semantically distinct registries described below are separate JSON files in that directory.
 
 ## Registries
 
@@ -32,7 +30,7 @@ Anatomy terms fall into three tiers:
 | Composite          | Another component used as a named part | `checkbox`, `close-button`, `popover`, `avatar`        |
 | Component-specific | Unique to one component                | `loupe`, `gripper`, `hold-icon`                        |
 
-**File:** `packages/design-system-registry/registry/anatomy-terms.json`\
+**File:** `packages/design-data/registry/anatomy-terms.json`\
 **Validated by:** SPEC-020, SPEC-023, SPEC-024, SPEC-025, SPEC-035 (advisory — anatomy part `name` values SHOULD match the anatomy-terms registry)\
 **See also:** [Taxonomy — Component anatomy vs. token objects](taxonomy.md#component-anatomy-vs-token-objects), [Anatomy format](anatomy-format.md)
 
@@ -50,7 +48,7 @@ Validates the `object` field on token name objects.
 | `visual`     | Visible graphic element area (may be inset from edge) |
 | `content`    | Main content area                                     |
 
-**File:** `packages/design-system-registry/registry/token-objects.json`\
+**File:** `packages/design-data/registry/token-objects.json`\
 **Validated by:** SPEC-009 (advisory — `name.object` field values SHOULD match the token-objects registry)\
 **See also:** [Taxonomy — Token objects (styling surfaces)](taxonomy.md#token-objects-styling-surfaces)
 
@@ -60,7 +58,7 @@ Validates the `category` field on component declarations.
 
 **What it contains:** Top-level categories for organizing components by purpose and interaction type. Used for documentation navigation and tooling filters.
 
-**File:** `packages/design-system-registry/registry/categories.json`\
+**File:** `packages/design-data/registry/categories.json`\
 **Validated by:** SPEC-034 (advisory — `meta.category` field values SHOULD match the categories registry)\
 **See also:** [Component format](component-format.md)
 
@@ -72,7 +70,7 @@ Registry IDs are scoped to their registry. The same ID **MAY** appear in multipl
 
 ## Other registries in the package
 
-The following registries exist in `@adobe/design-system-registry` but are not part of the three-registry boundary defined above. They validate other token name fields and component metadata fields:
+The following registries exist in `@adobe/spectrum-design-data` (under `registry/`) but are not part of the three-registry boundary defined above. They validate other token name fields and component metadata fields:
 
 | Registry          | File                     | Validates                            |
 | ----------------- | ------------------------ | ------------------------------------ |

package/spec/taxonomy.md

@@ -60,19 +60,19 @@ The following concept categories are defined in Spectrum's foundation field cata
 
 **NORMATIVE:** Each category listed below corresponds to a field on the token [name object](token-format.md). Tokens **MAY** use any subset of these fields. Exception: `property` is REQUIRED on every name object — see [token-format.md](token-format.md#name-object).
 
-| Category      | Name object field | Answers   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ------------- | ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Structure     | `structure`       | What?     | Individual objects or object categories that have shared styling. Distinctly different from "components" in that they represent structures and visual patterns that can or do occur across many varieties of components.                                                                                                                                                                                                                                                                                  |
-| Sub-structure | `substructure`    | What?     | A structure within an element that should only exist within the context of its parent structure.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| Component     | `component`       | What?     | Component scope when the token is component-scoped.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| Anatomy       | `anatomy`         | What?     | A visible, named part of a component as defined by designers.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| Object        | `object`          | Where?    | The styling surface to which a visual property is applied (e.g. background, border, edge).                                                                                                                                                                                                                                                                                                                                                                                                                |
-| Property      | `property`        | Where?    | The CSS/styling attribute or design-system abstraction being defined (e.g. color, width, padding, gap). REQUIRED — see exception in preamble. Values SHOULD come from [`property-terms.json`](../../packages/design-system-registry/registry/property-terms.json). Anatomy parts and styling surfaces do NOT belong here — they belong in `anatomy` and `object` respectively. See [token-format.md — Name-object migration policy](token-format.md#name-object-migration-policy) for migration guidance. |
-| Orientation   | `orientation`     | When/Why? | The direction or order of structures and elements within a component or pattern.                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| Position      | `position`        | When/Why? | The location of an object relative to another, with or without respect to directional order.                                                                                                                                                                                                                                                                                                                                                                                                              |
-| Size          | `size`            | When/Why? | Relative terms used to create relationships and patterns of usage across multiple tokens and token types.                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Density       | `density`         | When/Why? | Options that create more or less space within or around the parts of a component.                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Shape         | `shape`           | When/Why? | Relative to the overall shape of a component (e.g. "uniform" creates a 1:1 padding ratio between horizontal and vertical padding).                                                                                                                                                                                                                                                                                                                                                                        |
+| Category      | Name object field | Answers   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Structure     | `structure`       | What?     | Individual objects or object categories that have shared styling. Distinctly different from "components" in that they represent structures and visual patterns that can or do occur across many varieties of components.                                                                                                                                                                                                                                                                       |
+| Sub-structure | `substructure`    | What?     | A structure within an element that should only exist within the context of its parent structure.                                                                                                                                                                                                                                                                                                                                                                                               |
+| Component     | `component`       | What?     | Component scope when the token is component-scoped.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Anatomy       | `anatomy`         | What?     | A visible, named part of a component as defined by designers.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Object        | `object`          | Where?    | The styling surface to which a visual property is applied (e.g. background, border, edge).                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Property      | `property`        | Where?    | The CSS/styling attribute or design-system abstraction being defined (e.g. color, width, padding, gap). REQUIRED — see exception in preamble. Values SHOULD come from [`property-terms.json`](../../packages/design-data/registry/property-terms.json). Anatomy parts and styling surfaces do NOT belong here — they belong in `anatomy` and `object` respectively. See [token-format.md — Name-object migration policy](token-format.md#name-object-migration-policy) for migration guidance. |
+| Orientation   | `orientation`     | When/Why? | The direction or order of structures and elements within a component or pattern.                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Position      | `position`        | When/Why? | The location of an object relative to another, with or without respect to directional order.                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Size          | `size`            | When/Why? | Relative terms used to create relationships and patterns of usage across multiple tokens and token types.                                                                                                                                                                                                                                                                                                                                                                                      |
+| Density       | `density`         | When/Why? | Options that create more or less space within or around the parts of a component.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Shape         | `shape`           | When/Why? | Relative to the overall shape of a component (e.g. "uniform" creates a 1:1 padding ratio between horizontal and vertical padding).                                                                                                                                                                                                                                                                                                                                                             |
 
 Additional categories for variant and state are inherited from the existing name object:
 
@@ -87,10 +87,10 @@ Color tokens describe palette entries and semantic color assignments. Their name
 
 **NORMATIVE:** Color tokens SHOULD include `colorFamily`, `scaleIndex`, or both to allow tooling to group and sort palette entries. Tokens missing both are flagged by rule SPEC-043 (`domain-required-fields`, warning).
 
-| Category     | Name object field | Answers | Description                                                                                                                                                                                 |
-| ------------ | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Color Family | `colorFamily`     | What?   | Hue family of the color (e.g. `blue`, `gray`, `celery`, `transparent-black`). Values come from [`color-families.json`](../../packages/design-system-registry/registry/color-families.json). |
-| Ramp Index   | `scaleIndex`      | Which?  | Numeric perceptual ramp step (e.g. `100`, `400`, `900`, `1600`). Shared with layout tokens; see [scaleIndex field declaration](../fields/scaleIndex.json). Not scope-restricted.            |
+| Category     | Name object field | Answers | Description                                                                                                                                                                      |
+| ------------ | ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Color Family | `colorFamily`     | What?   | Hue family of the color (e.g. `blue`, `gray`, `celery`, `transparent-black`). Values come from [`color-families.json`](../../packages/design-data/registry/color-families.json). |
+| Ramp Index   | `scaleIndex`      | Which?  | Numeric perceptual ramp step (e.g. `100`, `400`, `900`, `1600`). Shared with layout tokens; see [scaleIndex field declaration](../fields/scaleIndex.json). Not scope-restricted. |
 
 **Default serialization order for color tokens:**
 
@@ -106,13 +106,13 @@ Typography tokens describe typeface attributes: family, weight, style, and numer
 
 **NORMATIVE:** Typography tokens SHOULD include at least one of `family`, `weight`, or `style`. Tokens missing all three are flagged by rule SPEC-043 (`domain-required-fields`, warning).
 
-| Category  | Name object field | Answers | Description                                                                                                                                                                                                                                                    |
-| --------- | ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Family    | `family`          | What?   | Type family of the token (e.g. `sans-serif`, `serif`, `cjk`, `code`). Values come from [`typography-families.json`](../../packages/design-system-registry/registry/typography-families.json).                                                                  |
-| Weight    | `weight`          | How?    | Typographic weight (e.g. `regular`, `bold`, `light`, `black`). Values come from [`typography-weights.json`](../../packages/design-system-registry/registry/typography-weights.json).                                                                           |
-| Style     | `style`           | How?    | Typographic style (e.g. `italic`, `oblique`, `normal`). Include `normal` when the token explicitly declares a normal style (e.g. a reset). Values come from [`typography-styles.json`](../../packages/design-system-registry/registry/typography-styles.json). |
-| Alignment | `alignment`       | How?    | Horizontal text-alignment direction (e.g. `start`, `center`, `end`). Corresponds to the CSS `text-align` axis. Values come from [`alignments.json`](../../packages/design-system-registry/registry/alignments.json).                                           |
-| Scale     | `scaleIndex`      | Which?  | Numeric size scale step (e.g. `75`, `100`, `200`). Shared with other token types; not scope-restricted.                                                                                                                                                        |
+| Category  | Name object field | Answers | Description                                                                                                                                                                                                                                         |
+| --------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Family    | `family`          | What?   | Type family of the token (e.g. `sans-serif`, `serif`, `cjk`, `code`). Values come from [`typography-families.json`](../../packages/design-data/registry/typography-families.json).                                                                  |
+| Weight    | `weight`          | How?    | Typographic weight (e.g. `regular`, `bold`, `light`, `black`). Values come from [`typography-weights.json`](../../packages/design-data/registry/typography-weights.json).                                                                           |
+| Style     | `style`           | How?    | Typographic style (e.g. `italic`, `oblique`, `normal`). Include `normal` when the token explicitly declares a normal style (e.g. a reset). Values come from [`typography-styles.json`](../../packages/design-data/registry/typography-styles.json). |
+| Alignment | `alignment`       | How?    | Horizontal text-alignment direction (e.g. `start`, `center`, `end`). Corresponds to the CSS `text-align` axis. Values come from [`alignments.json`](../../packages/design-data/registry/alignments.json).                                           |
+| Scale     | `scaleIndex`      | Which?  | Numeric size scale step (e.g. `75`, `100`, `200`). Shared with other token types; not scope-restricted.                                                                                                                                             |
 
 **Default serialization order for typography tokens:**
 
@@ -130,11 +130,11 @@ Motion tokens describe timing, easing, and animation role for UI animation. Thei
 
 **NORMATIVE:** Motion tokens SHOULD include `motionRole` or `easing`. Tokens missing both are flagged by rule SPEC-043 (`domain-required-fields`, warning).
 
-| Category    | Name object field | Answers | Description                                                                                                                                                                                |
-| ----------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Motion Role | `motionRole`      | What?   | Semantic role of the animation (e.g. `enter`, `exit`, `transition`, `emphasis`). Values come from [`motion-roles.json`](../../packages/design-system-registry/registry/motion-roles.json). |
-| Easing      | `easing`          | How?    | Easing curve identifier (e.g. `ease-in`, `ease-out`, `standard`). Values come from [`easing-curves.json`](../../packages/design-system-registry/registry/easing-curves.json).              |
-| Duration    | `scaleIndex`      | Which?  | Numeric duration bucket index (e.g. `100` for 100ms, `200` for 200ms). Shared with other token types; not scope-restricted.                                                                |
+| Category    | Name object field | Answers | Description                                                                                                                                                                     |
+| ----------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Motion Role | `motionRole`      | What?   | Semantic role of the animation (e.g. `enter`, `exit`, `transition`, `emphasis`). Values come from [`motion-roles.json`](../../packages/design-data/registry/motion-roles.json). |
+| Easing      | `easing`          | How?    | Easing curve identifier (e.g. `ease-in`, `ease-out`, `standard`). Values come from [`easing-curves.json`](../../packages/design-data/registry/easing-curves.json).              |
+| Duration    | `scaleIndex`      | Which?  | Numeric duration bucket index (e.g. `100` for 100ms, `200` for 200ms). Shared with other token types; not scope-restricted.                                                     |
 
 **Default serialization order for motion tokens:**
 
@@ -229,7 +229,7 @@ Semantic fields describe identity, structure, and intent. They are used for quer
 
 **NORMATIVE:** Semantic field values are validated against their declared vocabulary registry with the severity specified in the field declaration (typically **advisory** — warning, not error). Values not in the registry are permitted but flagged.
 
-Semantic fields are those declared with `kind: "semantic"` in the field catalog. In Spectrum's foundation catalog, these are: `structure`, `substructure`, `component`, `anatomy`, `object`, `property`, `variant`, `state`, `orientation`, `position`, `size`, `density`, `shape`.
+Semantic fields are those declared with `kind: "semantic"` in the field catalog. The authoritative list for any given design system is determined by its field catalog declarations (see `packages/design-data/fields/` for Spectrum's catalog).
 
 ### Mode-set fields
 
@@ -237,7 +237,7 @@ Mode-set fields represent axes of variation that drive the [cascade](cascade.md)
 
 **NORMATIVE:** Mode-set field values are validated against declared [mode set](mode-sets.md) modes with **strict** severity (error). An invalid mode value would silently fail to match any context during cascade resolution.
 
-Mode-set fields are those declared with `kind: "mode-set"` in the field catalog, plus any additional mode set keys from the dataset's [mode set declarations](mode-sets.md). In Spectrum's foundation catalog, the standard mode-set fields are: `colorScheme`, `scale`, `contrast`.
+Mode-set fields are those declared with `kind: "mode-set"` in the field catalog, plus any additional mode set keys from the dataset's [mode set declarations](mode-sets.md). The authoritative list for any given design system is determined by its field catalog and mode-set declarations (see `packages/design-data/fields/` for Spectrum's catalog).
 
 See [Mode Sets](mode-sets.md) for mode set declarations, modes, and defaults.
 
@@ -281,7 +281,7 @@ package to avoid bumping the tokens version on every taxonomy change.
 | ----------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
 | Token source data | `packages/tokens/src/*.json`        | `$schema`, `value`, `uuid`, `sets`, … — no `name` field                          |
 | Taxonomy sidecar  | `packages/token-names/names/*.json` | `{ "<slug>": { property, colorFamily, … }, … }` — one file per token source file |
-| Field definitions | `packages/design-data-spec/fields/` | Authoritative field catalog with scope and type                                  |
+| Field definitions | `packages/design-data/fields/`      | Authoritative field catalog with scope and type                                  |
 
 The sidecar package (`@adobe/token-names`) is **private** (not published to npm).
 Its delivery format for downstream consumers is TBD.

package/spec/token-format.md

@@ -98,7 +98,15 @@ The table below lists all semantic fields. Fields marked with a scope are domain
 
 ### Alias (`$ref`)
 
-When **`$ref`** is present, the token is an **alias**. The value **MUST** be a non-empty string interpreted as a **token path** or **stable identifier** resolvable by the validator (resolution rules are Layer 2; see rule `SPEC-001` in `rules/rules.yaml`).
+When **`$ref`** is present, the token is an **alias**. The value **MUST** be a non-empty string. In cascade format the value is the **UUID** of the target token (rename-proof, resolved via the graph's `uuid_index`). In the legacy transition format the value is the target token's kebab-case name (serialized legacy slug). Both forms are accepted; resolution rules are Layer 2 (see rule `SPEC-001` in `rules/rules.yaml`).
+
+```json
+// Cascade canonical form (recommended) — the UUID is stable across renames.
+{ "name": { "property": "accent-background-color", "state": "default", "colorScheme": "dark" },
+  "$schema": "…/alias.json",
+  "$ref": "87a2c8f0-54fd-4939-8f42-3124fde1e49e",
+  "uuid": "f24eb871-6419-4cef-88a2-cca8548ae31e" }
+```
 
 ### Literal `value`
 
@@ -179,7 +187,7 @@ No string-named token may remain in a conforming dataset after the `2.0.0` cut w
 
 The `property` field on a name object is the **CSS/styling attribute or design-system abstraction** being defined — not an anatomy part, not a styling surface, and not a legacy compound name string. Not all valid values are CSS property identifiers; design-system abstractions (e.g. `padding-horizontal`, `overlay-color`, `size`) are permitted.
 
-**NORMATIVE:** Values for `property` **SHOULD** come from the [`property-terms`](../../packages/design-system-registry/registry/property-terms.json) registry. Non-registry values emit an advisory warning (SPEC-009 applied to the `property` field).
+**NORMATIVE:** Values for `property` **SHOULD** come from the [`property-terms`](../../packages/design-data/registry/property-terms.json) registry. Non-registry values emit an advisory warning (SPEC-009 applied to the `property` field).
 
 Examples of **valid** `property` values: `color`, `background-color`, `border-radius`, `font-size`, `gap`, `opacity`.
 
@@ -268,7 +276,7 @@ Within a composite value, a string sub-value **MAY** be an **inline alias**: a r
 }
 ```
 
-**NORMATIVE:** In legacy format, inline aliases use the syntax `{token-name}` (curly-brace-wrapped token property name). In cascade format, the inline alias syntax is `{token-name}` for backward compatibility; UUID-based inline aliases are reserved for a future spec version.
+**NORMATIVE:** In legacy format, inline aliases use the syntax `{token-name}` (curly-brace-wrapped token property name). In cascade format, top-level `$ref` aliases use a UUID (canonical, rename-proof); inline composite aliases within `value` objects remain `{token-name}` for backward compatibility. UUID-based inline composite aliases are reserved for a future spec version.
 
 **NORMATIVE:** Inline aliases within composite values are subject to alias resolution rules. Validators **MUST** resolve inline aliases and report errors for missing targets (SPEC-014), type mismatches (SPEC-015), and circular references (SPEC-003, extended).