@adobe/design-data-spec 1.5.0 → 2.1.0

package/spec/agent-surface.md

@@ -1,7 +1,7 @@
 # Agent-readable surface
 
 **Spec version:** `1.0.0-draft` (see [Overview](index.md))\
-**Status:** Draft — RFC-C / Phase 8. Surface and tool list are subject to change. No reference implementation exists yet.
+**Status:** Implemented — RFC-C / Phase 8 (epic [#830](https://github.com/adobe/spectrum-design-data/issues/830)). Core read/validate/write surface shipped. `write_component` and `explain` deferred (no CLI subcommand or MCP tool yet).
 
 This document defines the **agent-readable surface**: the contract an external AI agent uses to consume design data conformant with this specification. It standardizes a small set of operations exposed through three transports — a CLI, a Model Context Protocol (MCP) server, and a Claude Code Agent Skill — all backed by the same resolver, validator, and query implementations that power the rest of the SDK.
 
@@ -25,19 +25,19 @@ The surface targets three consumer shapes:
 
 **NORMATIVE:** A conforming implementation MUST expose the following operations. Transport-specific naming (CLI subcommand vs MCP tool name vs skill action) MAY differ; the semantics MUST NOT.
 
-| Operation            | Reads                                                  | Returns                                                                                                                                                                                   | Backed by                                                 |
-| -------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| `resolve_token`      | property + mode set context                            | winning token (literal or resolved alias) with file/UUID/specificity                                                                                                                      | `cascade::resolve`                                        |
-| `query_tokens`       | filter expression (see [Query](query.md))              | matching token list                                                                                                                                                                       | `query::filter`                                           |
-| `validate_usage`     | candidate token document or fragment                   | `ValidationReport` (Layer 1 + Layer 2 diagnostics)                                                                                                                                        | `validate::validate_*`                                    |
-| `describe_component` | component identifier                                   | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape) | (Phase 6 contract)                                        |
-| `suggest_token`      | natural-language intent + optional property hint       | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1)                                                                                                                 | registry + query                                          |
-| `get_guidance`       | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D                                                                                                            | document blocks                                           |
-| `diff_datasets`      | two dataset roots                                      | `DiffReport` per [Diff](diff.md)                                                                                                                                                          | `diff::semantic_diff`                                     |
-| `write_token`        | token object + optional rationale string               | updated product-layer token file + `product-context.json` (RECOMMENDED, not NORMATIVE in v1)                                                                                              | `write::write_token` (Phase 8.x, not yet implemented)     |
-| `write_component`    | component object + optional rationale string           | updated product-layer component file + `product-context.json` (RECOMMENDED, not NORMATIVE in v1)                                                                                          | `write::write_component` (Phase 8.x, not yet implemented) |
+| Operation            | Reads                                                  | Returns                                                                                                                                                                                   | Backed by                                                                                          |
+| -------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `resolve_token`      | property + mode set context                            | winning token (literal or resolved alias) with file/UUID/specificity                                                                                                                      | `cascade::resolve`                                                                                 |
+| `query_tokens`       | filter expression (see [Query](query.md))              | matching token list                                                                                                                                                                       | `query::filter`                                                                                    |
+| `validate_usage`     | candidate token document or fragment                   | `ValidationReport` (Layer 1 + Layer 2 diagnostics)                                                                                                                                        | `validate::validate_*`                                                                             |
+| `describe_component` | component identifier                                   | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape) | (Phase 6 contract)                                                                                 |
+| `suggest_token`      | natural-language intent + optional property hint       | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1)                                                                                                                 | registry + query                                                                                   |
+| `get_guidance`       | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D                                                                                                            | document blocks                                                                                    |
+| `diff_datasets`      | two dataset roots                                      | `DiffReport` per [Diff](diff.md)                                                                                                                                                          | `diff::semantic_diff`                                                                              |
+| `write_token`        | token object + optional rationale string               | updated product-layer token file + `product-context.json` (RECOMMENDED, not NORMATIVE in v1)                                                                                              | `write::write_token` — shipped: `design-data write-token` (CLI) / `authoring_session_commit` (MCP) |
+| `write_component`    | component object + optional rationale string           | updated product-layer component file + `product-context.json` (RECOMMENDED, not NORMATIVE in v1)                                                                                          | `write::write_component` — deferred; no CLI subcommand or MCP tool yet                             |
 
-**NORMATIVE:** `validate_usage`, `resolve_token`, `query_tokens`, and `diff_datasets` MUST be implemented in a conforming agent surface. `suggest_token`, `get_guidance`, `write_token`, and `write_component` are RECOMMENDED. `describe_component` becomes NORMATIVE once [#832](https://github.com/adobe/spectrum-design-data/discussions/832) reaches implemented status.
+**NORMATIVE:** `validate_usage`, `resolve_token`, `query_tokens`, `diff_datasets`, and `describe_component` MUST be implemented in a conforming agent surface. `suggest_token`, `get_guidance`, `write_token`, and `write_component` are RECOMMENDED.
 
 **RECOMMENDED:** When `write_token` or `write_component` is invoked, the implementation SHOULD capture a `rationale` argument from the agent session context and record it in both the token's inline `rationale` field and the product context document's `overrides[].rationale` or `extensions.tokens[].rationale`. See [Product context — Agent capture behavior](product-context.md#agent-capture-behavior).
 
@@ -70,7 +70,7 @@ The reference CLI is `design-data` (see [`sdk/cli/`](../../../sdk/cli/)). RFC-C
 
 * `design-data primer [PATH]` — emit the [Session primer](#session-primer) payload.
 * `design-data suggest "<intent>" [--property <hint>]` — invoke `suggest_token`.
-* `design-data explain <token-uuid|component-id>` — invoke `get_guidance`.
+* `design-data explain <token-uuid|component-id>` — invoke `get_guidance`. (Deferred — not yet shipped; pending `get_guidance` wire-up.)
 
 **NORMATIVE:** All RFC-C CLI output MUST default to JSON when stdout is not a TTY, and MUST emit human-friendly output when stdout is a TTY. This makes the CLI directly composable from agent shells without per-call format flags.
 
@@ -84,6 +84,8 @@ A reference MCP server is RECOMMENDED to ship as `@adobe/design-data-agent-mcp`
 
 A reference Claude Code Agent Skill is RECOMMENDED at `tools/design-data-agent-mcp/skills/design-data/SKILL.md`. The skill SHOULD trigger on intent words covering all three [Goals](#goals) — for example "design system", "design tokens", "drift", "spec-conformant", and explicit Spectrum mentions when the active manifest binds Spectrum.
 
+A separate Spectrum-oriented skill (embedded snapshot, zero config) lives at `tools/design-data-skill/skills/design-data/SKILL.md`. Install both via the `spectrum-design-data` Claude Code marketplace as `design-data-agent@spectrum-design-data` and `design-data@spectrum-design-data` respectively.
+
 **RECOMMENDED:** The skill SHOULD shell out to the CLI rather than embedding tool calls, so its description (the only persistent context cost) stays small and the heavy lifting happens out-of-band.
 
 ## `describe_component` return shape

package/spec/anatomy-format.md

@@ -99,7 +99,7 @@ The following anatomy part names are defined by the cross-platform design audit
 
 Custom part names are permitted. When a custom name is used, the anatomy part object **SHOULD** include a `description` field explaining its visual role (rule SPEC-023).
 
-The table above is informative; the authoritative vocabulary is `@adobe/design-system-registry/registry/anatomy-terms.json` (119 entries). SPEC-035 fires advisory warnings when a declared anatomy part `name` is not in that registry, pointing authors at the canonical list. Custom names remain valid — SPEC-035 is advisory, not an error.
+The table above is informative; the authoritative vocabulary is `@adobe/spectrum-design-data/registry/anatomy-terms.json` (119 entries). SPEC-035 fires advisory warnings when a declared anatomy part `name` is not in that registry, pointing authors at the canonical list. Custom names remain valid — SPEC-035 is advisory, not an error.
 
 ## Cross-reference with token name objects
 

package/spec/cascade.md

@@ -55,7 +55,7 @@ Exact matching rules for omitted mode sets are defined alongside mode set declar
 
 **NORMATIVE:** Alias (`$ref`) resolution **MUST** occur **after** cascade selection. The resolution algorithm selects the winning candidate using layer, specificity, and tie-breaking rules before any alias chain is followed.
 
-**NORMATIVE:** If the winning candidate is an alias, its `$ref` chain **MUST** be resolved to a literal value using the standard alias-resolution rules (SPEC-001 through SPEC-003 in `rules/rules.yaml`). The alias target is resolved within the same dataset (i.e. the same merged layer stack), not relative to any single layer.
+**NORMATIVE:** If the winning candidate is an alias, its `$ref` chain **MUST** be resolved to a literal value using the standard alias-resolution rules (SPEC-001 through SPEC-003 in `rules/rules.yaml`). The alias target is resolved within the same dataset (i.e. the same merged layer stack), not relative to any single layer. In cascade format, `$ref` holds the **UUID** of the target token (see [`token-format.md` §Alias](token-format.md#alias-ref)); resolution proceeds UUID-first, then direct graph key (legacy slug), then serialised name.
 
 **RATIONALE:** Aliases participate in cascade as opaque references — their target values are not examined during specificity calculation or layer comparison. This keeps resolution deterministic and allows aliases to be valid candidates at any specificity level.
 

package/spec/dataset-layout.md

@@ -0,0 +1,72 @@
+# Dataset layout
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the normative **directory layout** of a conformant design-data **dataset**: which directories are required, which are optional but registered, how files in each directory are named and validated, how tooling **discovers** a dataset on disk, and the optional root **descriptor** a dataset MAY carry.
+
+A **dataset** is a directory tree that holds design tokens and the optional catalogs (components, fields, mode sets, registry vocabulary) that describe them. The Spectrum foundation dataset lives at `packages/design-data/`, but any design system MAY publish a dataset in this layout.
+
+## Directory layout
+
+A dataset is rooted at a single **dataset root** directory. The following table defines the directories tooling recognizes:
+
+| Directory     | Status                | Contents                                                             | Schema                                                            |
+| ------------- | --------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `tokens/`     | **Required**          | Cascade-format token files, named `*.tokens.json`.                   | [`cascade-file.schema.json`](../schemas/cascade-file.schema.json) |
+| `components/` | Optional (registered) | One component declaration per `*.json` file.                         | [`component.schema.json`](../schemas/component.schema.json)       |
+| `fields/`     | Optional (registered) | Name-object field declarations, one or more `*.json` files.          | [`field.schema.json`](../schemas/field.schema.json)               |
+| `mode-sets/`  | Optional (registered) | Mode set declarations, one per `*.json` file.                        | [`mode-set.schema.json`](../schemas/mode-set.schema.json)         |
+| `registry/`   | Optional (registered) | Registry value collections (vocabulary), one or more `*.json` files. | [`registry-value.json`](../schemas/registry-value.json)           |
+
+**NORMATIVE:** A conformant dataset **MUST** contain a `tokens/` directory holding at least one `*.tokens.json` file. A dataset with no `tokens/` directory, or a `tokens/` directory containing no `*.tokens.json` file, is **not** conformant.
+
+**NORMATIVE:** When a **registered** directory name (`components/`, `fields/`, `mode-sets/`, `registry/`) is present, the files it contains **MUST** validate against the schema named above. Tooling validating a dataset **MUST** validate the files in every registered directory that is present.
+
+**RECOMMENDED:** A registered directory that exists **SHOULD** contain at least one conformant `*.json` file. An empty registered directory is permitted but **SHOULD** produce a warning, since it usually indicates incomplete data rather than intent.
+
+**NORMATIVE:** Directory names not listed above carry no special meaning and are ignored by dataset-layout validation. Tooling **MUST NOT** treat an unrecognized sibling directory as an error.
+
+### File-naming patterns
+
+| Directory     | Pattern            | Notes                                                                          |
+| ------------- | ------------------ | ------------------------------------------------------------------------------ |
+| `tokens/`     | `**/*.tokens.json` | May be nested in subdirectories; only `*.tokens.json` files are token sources. |
+| `components/` | `*.json`           | One declaration per file.                                                      |
+| `fields/`     | `*.json`           | The catalog MAY be split across multiple files.                                |
+| `mode-sets/`  | `*.json`           | One declaration per file.                                                      |
+| `registry/`   | `*.json`           | One value collection per file.                                                 |
+
+## Dataset discovery
+
+Tooling that operates on "the current dataset" (rather than an explicit path) **MUST** resolve the dataset root using the following precedence. The first match wins; later tiers are only consulted when an earlier tier does not resolve a value.
+
+1. **Explicit override** — a path passed directly by the caller (CLI positional argument or `--*-path` flag, environment variable). Explicit overrides always win.
+2. **Config file** — a `.design-data.toml` discovered by walking **up** the ancestor chain from the working directory. A `[source]` block of `type = "path"` names the dataset root (resolved relative to the config file's directory). This is the explicit, portable way to point a project at a dataset outside its own tree.
+3. **In-repo probing** — when running inside a monorepo checkout, probe for the standard layout relative to the working directory (`packages/design-data/tokens` and one level up). This preserves the in-repo workflow with zero configuration.
+4. **Embedded snapshot** — when no dataset is found on disk, tooling MAY fall back to a snapshot of the foundation dataset embedded in the binary, materialized to a local cache directory.
+
+**NORMATIVE:** The required directory (`tokens/`) and registered optional directories are resolved **relative to the dataset root** determined above. A discovery tier that resolves a dataset root **MUST** look for `tokens/`, `components/`, `fields/`, `mode-sets/`, and `registry/` directly under that root.
+
+The reference implementation of this algorithm lives in the SDK at `sdk/core/src/data_source/mod.rs` (`resolve`, `from_root`, and `probe_cwd`).
+
+## Root descriptor
+
+A dataset **MAY** carry a root **descriptor** to make its structure and target spec version explicit. Two forms are recognized:
+
+* **`.design-data.toml`** — a project-level config (TOML) that primarily declares where the dataset lives (`[source]`) and cache overrides. It is consumed during [discovery](#dataset-discovery) tier 2.
+* **`dataset.json`** — an OPTIONAL JSON descriptor placed at the dataset root that **MAY** declare which optional directories are present, pin the spec version the dataset targets, and override default discovery paths. It **MUST** conform to [`dataset.schema.json`](../schemas/dataset.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/dataset.schema.json`).
+
+**NORMATIVE:** Neither descriptor is required. A dataset with a conformant `tokens/` directory and no descriptor is fully conformant. When a `dataset.json` is present it **MUST** validate against `dataset.schema.json`, but its absence **MUST NOT** be treated as an error.
+
+## Structural validation
+
+**NORMATIVE:** Validators implementing rule **`SPEC-044`** (`dataset-structure`) **MUST** report an **error** when a dataset path lacks a `tokens/` directory containing at least one `*.tokens.json` file. The check **MUST** fire **before** token- and component-level rules so that downstream rules can assume the dataset structure is present, and so that an incomplete dataset produces a clear "dataset structure is incomplete" diagnostic rather than a cascade of confusing per-file errors.
+
+**RECOMMENDED:** Validators implementing `SPEC-044` **SHOULD** emit a **warning** when a registered optional directory is present but contains no conformant `*.json` file. See `rules/rules.yaml` for the full rule definition.
+
+## References
+
+* [#1114 — Define normative dataset-directory layout and add SPEC-044 structural pre-check](https://github.com/adobe/spectrum-design-data/issues/1114)
+* [#1113 — Consolidate Spectrum design data into a single package](https://github.com/adobe/spectrum-design-data/pull/1113)
+* [#714 — Design Data Specification (umbrella)](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#715 — Distributed Design Data Architecture](https://github.com/adobe/spectrum-design-data/discussions/715)

package/spec/index.md

@@ -25,6 +25,7 @@ The specification defines:
 11. **Document blocks** — typed prose blocks attachable to tokens, components, and anatomy parts; makes design guidance machine-readable and agent-queryable ([Document blocks](document-blocks.md)).
 12. **Agent-readable surface** — operations and transport contracts (CLI, MCP server, Agent Skill) for AI agents consuming spec-conformant design data; covers session primer, token resolution, validation, query, and component description ([Agent-readable surface](agent-surface.md)).
 13. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
+14. **Dataset layout** — normative directory structure of a dataset (`tokens/`, `components/`, `fields/`, `mode-sets/`, `registry/`), discovery algorithm, and optional root descriptor ([Dataset layout](dataset-layout.md)).
 
 ## Conformance
 
@@ -77,6 +78,7 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 | [Document blocks](document-blocks.md)               | Typed prose blocks (purpose, guideline, accessibility, do-dont, examples) attachable to any entity.                               |
 | [Agent-readable surface](agent-surface.md)          | Transport contracts (CLI, MCP, Agent Skill) and operation catalog for AI agents consuming spec-conformant design data.            |
 | [Evolution](evolution.md)                           | Deprecation lifecycle, migration windows, change classification.                                                                  |
+| [Dataset layout](dataset-layout.md)                 | Normative dataset directory structure, discovery algorithm, optional root descriptor, and SPEC-044 structural pre-check.          |
 
 ## JSON Schema `$id` and versioning
 
@@ -93,11 +95,11 @@ Packaged copies in this repository live under `packages/design-data-spec/schemas
 
 ## Relationship to existing Adobe packages
 
-| Package / area                          | Relationship                                                                                                                                                                                                                                                                 |
-| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@adobe/spectrum-tokens`                | **Current** token JSON under `packages/tokens/` is the **legacy** shape (e.g. `color-set`, `scale-set`). This spec defines the **target** format; backward-compat schemas and migration are Phase 1 ([#723](https://github.com/adobe/spectrum-design-data/issues/723)).      |
-| `@adobe/design-system-registry`         | Registry enums and component metadata MAY be referenced by validation rules (e.g. component association); exact coupling is Layer 2.                                                                                                                                         |
-| `@adobe/spectrum-component-api-schemas` | Will become a thin adapter over component declarations in `packages/design-data-spec/components/` (Phase 6.5). Until migration, existing schemas remain authoritative. Cross-reference rules SPEC-018–SPEC-020 apply when component declarations are present in the dataset. |
+| Package / area                          | Relationship                                                                                                                                                                                                                                                            |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@adobe/spectrum-tokens`                | **Current** token JSON under `packages/tokens/` is the **legacy** shape (e.g. `color-set`, `scale-set`). This spec defines the **target** format; backward-compat schemas and migration are Phase 1 ([#723](https://github.com/adobe/spectrum-design-data/issues/723)). |
+| `@adobe/spectrum-design-data`           | Registry enums (under `registry/`) and component metadata MAY be referenced by validation rules (e.g. component association); exact coupling is Layer 2.                                                                                                                |
+| `@adobe/spectrum-component-api-schemas` | Will become a thin adapter over component declarations in `packages/design-data/components/` (Phase 6.5). Until migration, existing schemas remain authoritative. Cross-reference rules SPEC-018–SPEC-020 apply when component declarations are present in the dataset. |
 
 ## Umbrella discussions
 

package/spec/mode-sets.md

@@ -35,7 +35,7 @@ These mode sets are declared in the `mode-sets/` catalog (see [Mode Set catalog]
 
 ## Mode Set catalog
 
-The Spectrum foundation publishes mode set declarations as JSON files under `packages/design-data-spec/mode-sets/`. Each file conforms to [`mode-set.schema.json`](../schemas/mode-set.schema.json).
+The Spectrum foundation publishes mode set declarations as JSON files under `packages/design-data/mode-sets/`. Each file conforms to [`mode-set.schema.json`](../schemas/mode-set.schema.json).
 
 **NORMATIVE:** Tooling (validators, resolution engine) **MUST** load mode set declarations from the dataset's mode set catalog before performing specificity calculations or coverage validation.
 

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).