@adobe/design-data-spec 1.4.0 → 2.0.0

package/conformance/invalid/SPEC-009/expected-errors.json

@@ -4,7 +4,7 @@
     {
       "rule_id": "SPEC-009",
       "severity": "warning",
-      "message_pattern": ".*not in the design-system-registry.*"
+      "message_pattern": ".*not in the spectrum-design-data.*"
     }
   ]
 }

package/conformance/invalid/SPEC-018/dataset.json

@@ -5,5 +5,12 @@
       "value": "#ff0000"
     }
   ],
-  "components": []
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": { "category": "actions" }
+    }
+  ]
 }

package/conformance/invalid/SPEC-034/expected-errors.json

@@ -4,7 +4,7 @@
     {
       "rule_id": "SPEC-034",
       "severity": "warning",
-      "message_pattern": ".*not in the design-system-registry categories vocabulary.*"
+      "message_pattern": ".*not in the spectrum-design-data registry/categories vocabulary.*"
     }
   ]
 }

package/conformance/invalid/SPEC-035/expected-errors.json

@@ -4,7 +4,7 @@
     {
       "rule_id": "SPEC-035",
       "severity": "warning",
-      "message_pattern": ".*not in the design-system-registry anatomy-terms vocabulary.*"
+      "message_pattern": ".*not in the spectrum-design-data registry/anatomy-terms vocabulary.*"
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "1.4.0",
-  "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
+  "version": "2.0.0",
+  "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for the design data format",
   "type": "module",
   "repository": {
     "type": "git",
@@ -20,7 +20,6 @@
   },
   "exports": {
     "./package.json": "./package.json",
-    "./components/*.json": "./components/*.json",
     "./schemas/token.schema.json": "./schemas/token.schema.json",
     "./schemas/mode-set.schema.json": "./schemas/mode-set.schema.json",
     "./schemas/field.schema.json": "./schemas/field.schema.json",
@@ -29,12 +28,12 @@
     "./schemas/component.schema.json": "./schemas/component.schema.json",
     "./schemas/anatomy-part.schema.json": "./schemas/anatomy-part.schema.json",
     "./schemas/state-declaration.schema.json": "./schemas/state-declaration.schema.json",
-    "./rules/rules.yaml": "./rules/rules.yaml"
+    "./rules/rules.yaml": "./rules/rules.yaml",
+    "./schemas/registry-value.json": "./schemas/registry-value.json",
+    "./schemas/platform-extension.json": "./schemas/platform-extension.json"
   },
   "files": [
-    "components",
     "conformance",
-    "fields",
     "rules",
     "schemas",
     "spec",

package/rules/rules.yaml

@@ -78,8 +78,8 @@ rules:
     name: name-field-enum-sync
     severity: warning
     category: naming-consistency
-    assert: Recognized name object fields (component, state, variant, etc.) SHOULD use values drawn from the corresponding design-system-registry enums when those enums are available.
-    message: "Token name field '{field}' value '{value}' is not in the design-system-registry enum for '{field}'"
+    assert: Recognized name object fields (component, state, variant, etc.) SHOULD use values drawn from the corresponding spectrum-design-data registry when those enums are available.
+    message: "Token name field '{field}' value '{value}' is not in the spectrum-design-data registry for '{field}'"
     spec_ref: spec/token-format.md#name-object
     introduced_in: "1.0.0-draft"
 
@@ -161,6 +161,7 @@ rules:
     category: reference-integrity
     assert: Token name-object 'component' field value MUST match the 'name' of a declared component in the dataset.
     message: "Token '{token}' references undeclared component '{component}'"
+    note: "Skipped when no component catalog is loaded (empty components list). Token-only validation runs that omit component declarations will not trigger this rule."
     spec_ref: spec/component-format.md#name
     introduced_in: "1.0.0-draft"
 
@@ -327,9 +328,9 @@ rules:
     category: naming-consistency
     assert: >
       A component's meta.category SHOULD reference an id from the categories registry in
-      @adobe/design-system-registry (categories.json). Unknown values are reported as
+      @adobe/spectrum-design-data registry/categories.json. Unknown values are reported as
       warnings; the registry is the authoritative vocabulary.
-    message: "Component '{entity}' meta.category value '{value}' is not in the design-system-registry categories vocabulary"
+    message: "Component '{entity}' meta.category value '{value}' is not in the spectrum-design-data registry/categories vocabulary"
     spec_ref: spec/registry.md#categories
     introduced_in: "1.0.0-draft"
   - id: SPEC-035
@@ -338,9 +339,9 @@ rules:
     category: naming-consistency
     assert: >
       A component anatomy part's name SHOULD reference an id from the anatomy-terms registry in
-      @adobe/design-system-registry (anatomy-terms.json). Unknown values are reported as
+      @adobe/spectrum-design-data registry/anatomy-terms.json. Unknown values are reported as
       warnings; custom names remain permitted but the registry is the authoritative vocabulary.
-    message: "Component '{entity}' anatomy part name '{value}' is not in the design-system-registry anatomy-terms vocabulary"
+    message: "Component '{entity}' anatomy part name '{value}' is not in the spectrum-design-data registry/anatomy-terms vocabulary"
     spec_ref: spec/anatomy-format.md#canonical-anatomy-vocabulary
     introduced_in: "1.0.0-draft"
 
@@ -445,13 +446,16 @@ rules:
     rfc: "#806"
     assert: >
       When a token's name object contains a domain-scoped field (e.g. `colorFamily`,
-      `weight`, `motionRole`), the token's `$schema` MUST reference a compatible token
-      type for that domain. Using a color-scoped field on a typography token, or a
+      `weight`, `motionRole`), the token's effective domain schema MUST be compatible
+      with that field's scope. For alias tokens (`alias.json`), the rule follows the
+      `alias_target` chain to the terminal non-alias schema before checking domain
+      compatibility — a color alias may carry `colorFamily` when its target is a
+      color-domain token. Using a color-scoped field on a typography token, or a
       typography-scoped field on a color token, is a taxonomy violation. The set of
       domain-scoped fields and their valid schema URL suffixes is declared in the field
-      catalog under `packages/design-data-spec/fields/` via the `scope` property.
+      catalog under `packages/design-data/fields/` via the `scope` property.
       Tokens without a `$schema` are skipped (domain cannot be determined).
-    message: "name.{field} is a {scope}-scoped field but token schema '{schema_url}' is not a {scope} token type"
+    message: "name.{field} is a {scope}-scoped field but token schema '{effective_schema}' is not a {scope} token type"
     spec_ref: spec/taxonomy.md#token-type-taxonomies
     introduced_in: "1.0.0-draft"
 

package/schemas/component.schema.json

@@ -89,7 +89,7 @@
         "category": {
           "type": "string",
           "minLength": 1,
-          "description": "Category id from @adobe/design-system-registry categories.json. Advisory validation via SPEC-034."
+          "description": "Category id from @adobe/spectrum-design-data registry/categories.json. Advisory validation via SPEC-034."
         },
         "documentationUrl": {
           "type": "string",

package/schemas/manifest.schema.json

@@ -94,28 +94,7 @@
             "conceptOrder": {
               "type": "array",
               "items": {
-                "type": "string",
-                "enum": [
-                  "variant",
-                  "component",
-                  "structure",
-                  "substructure",
-                  "anatomy",
-                  "object",
-                  "property",
-                  "orientation",
-                  "position",
-                  "size",
-                  "density",
-                  "shape",
-                  "state",
-                  "colorFamily",
-                  "family",
-                  "weight",
-                  "style",
-                  "motionRole",
-                  "easing"
-                ]
+                "type": "string"
               },
               "uniqueItems": true,
               "description": "Ordered list of field names for serialization. Values must match declared field names from the design system's field catalog (field.schema.json declarations). Replaces the default serialization.position order from each field declaration."

package/schemas/platform-extension.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/platform-extension.json",
+  "title": "Platform Extension",
+  "description": "Schema for platform-specific terminology extensions",
+  "type": "object",
+  "required": ["platform", "extends", "extensions"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "platform": {
+      "type": "string",
+      "description": "The platform this extension is for (e.g., iOS, Android, Web Components, Qt)"
+    },
+    "platformVersion": {
+      "type": "string",
+      "description": "Optional platform version or framework version"
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of what this extension provides"
+    },
+    "extends": {
+      "type": "string",
+      "description": "Which registry this extends (sizes, states, variants, etc.)"
+    },
+    "extensions": {
+      "type": "array",
+      "description": "Array of term extensions",
+      "items": {
+        "$ref": "#/$defs/extension"
+      }
+    }
+  },
+  "$defs": {
+    "extension": {
+      "type": "object",
+      "required": ["termId"],
+      "properties": {
+        "termId": {
+          "type": "string",
+          "description": "The ID of the term being extended (must exist in the base registry)"
+        },
+        "platformTerm": {
+          "type": "string",
+          "description": "Platform-specific term or name"
+        },
+        "platformAliases": {
+          "type": "array",
+          "description": "Platform-specific aliases",
+          "items": {
+            "type": "string"
+          }
+        },
+        "notes": {
+          "type": "string",
+          "description": "Platform-specific implementation notes"
+        },
+        "reference": {
+          "type": "string",
+          "description": "Platform documentation reference or API name"
+        },
+        "codeExample": {
+          "type": "string",
+          "description": "Code example showing platform usage"
+        },
+        "differences": {
+          "type": "array",
+          "description": "Key differences from the base term",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/registry-value.json

@@ -0,0 +1,230 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
+  "title": "Registry Value",
+  "description": "Schema for design system registry value entries",
+  "type": "object",
+  "required": ["type", "description", "values"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "type": {
+      "type": "string",
+      "description": "The type of registry (size, state, variant, etc.)"
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of what this registry contains"
+    },
+    "allowCustom": {
+      "type": "boolean",
+      "description": "Whether custom values are allowed beyond the registry"
+    },
+    "customPattern": {
+      "type": "string",
+      "description": "Regex pattern for validating custom values"
+    },
+    "values": {
+      "type": "array",
+      "description": "Array of registry values",
+      "items": {
+        "$ref": "#/$defs/value"
+      }
+    }
+  },
+  "$defs": {
+    "value": {
+      "type": "object",
+      "required": ["id", "label"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for this value"
+        },
+        "label": {
+          "type": "string",
+          "description": "Human-readable label"
+        },
+        "aliases": {
+          "type": "array",
+          "description": "Alternative names or spellings",
+          "items": {
+            "type": "string"
+          }
+        },
+        "description": {
+          "type": "string",
+          "description": "Detailed description of this value"
+        },
+        "default": {
+          "type": "boolean",
+          "description": "Whether this is the default value"
+        },
+        "deprecated": {
+          "type": "boolean",
+          "description": "Whether this value is deprecated"
+        },
+        "usedIn": {
+          "type": "array",
+          "description": "Where this value is used (tokens, component-schemas, etc.)",
+          "items": {
+            "type": "string"
+          }
+        },
+        "category": {
+          "type": "string",
+          "description": "Category or grouping for this value"
+        },
+        "value": {
+          "type": ["string", "number", "boolean"],
+          "description": "Actual value (if different from id)"
+        },
+        "documentationUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to documentation"
+        },
+        "definition": {
+          "type": "object",
+          "description": "Structured definition following Spectrum naming methodology",
+          "properties": {
+            "superordinate": {
+              "type": "string",
+              "description": "The higher-level category or class this term belongs to"
+            },
+            "description": {
+              "type": "string",
+              "description": "Core definition explaining what it is and how it differs"
+            },
+            "essentialCharacteristics": {
+              "type": "array",
+              "description": "Key characteristics that distinguish this term",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "platforms": {
+          "type": "object",
+          "description": "Platform-specific terminology and notes",
+          "patternProperties": {
+            ".*": {
+              "type": "object",
+              "properties": {
+                "term": {
+                  "type": "string",
+                  "description": "Platform-specific term or name"
+                },
+                "notes": {
+                  "type": "string",
+                  "description": "Platform-specific implementation notes"
+                },
+                "reference": {
+                  "type": "string",
+                  "description": "Platform documentation reference"
+                }
+              }
+            }
+          }
+        },
+        "terminology": {
+          "type": "object",
+          "description": "Terminology metadata and classification",
+          "properties": {
+            "conceptType": {
+              "type": "string",
+              "enum": ["word", "term", "name", "concept"],
+              "description": "Classification per Spectrum naming guide"
+            },
+            "namingRationale": {
+              "type": "string",
+              "description": "Why this name was chosen"
+            },
+            "alternatives": {
+              "type": "array",
+              "description": "Alternative terms considered but not used",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "sources": {
+          "type": "array",
+          "description": "References to source documentation",
+          "items": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "wiki",
+                  "industry-standard",
+                  "platform-standard",
+                  "internal-doc",
+                  "research"
+                ],
+                "description": "Type of source"
+              },
+              "url": {
+                "type": "string",
+                "format": "uri",
+                "description": "URL to source"
+              },
+              "reference": {
+                "type": "string",
+                "description": "Text reference or citation"
+              },
+              "date": {
+                "type": "string",
+                "format": "date",
+                "description": "Date of source or last update"
+              }
+            }
+          }
+        },
+        "governance": {
+          "type": "object",
+          "description": "Governance and ownership metadata",
+          "properties": {
+            "owner": {
+              "type": "string",
+              "description": "Team or person responsible for this term"
+            },
+            "reviewDate": {
+              "type": "string",
+              "format": "date",
+              "description": "Last review date"
+            },
+            "nextReviewDate": {
+              "type": "string",
+              "format": "date",
+              "description": "Scheduled next review date"
+            },
+            "status": {
+              "type": "string",
+              "enum": ["draft", "review", "approved", "deprecated"],
+              "description": "Current status of this term"
+            },
+            "replacedBy": {
+              "type": "string",
+              "description": "If deprecated, the term that replaces this one"
+            }
+          }
+        },
+        "relatedTerms": {
+          "type": "array",
+          "description": "Related or cross-referenced terms",
+          "items": {
+            "type": "string",
+            "description": "ID of related term"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/token.schema.json

@@ -218,7 +218,7 @@
         "$ref": {
           "type": "string",
           "minLength": 1,
-          "description": "Alias target path or stable token id (resolution is Layer 2)."
+          "description": "Alias target. In cascade format: the target token's UUID (canonical, rename-proof, resolved via uuid_index — Layer 2). In the legacy transition format: the target's kebab-case name slug."
         },
         "uuid": {
           "type": "string",

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/index.md

@@ -93,11 +93,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.