@adobe/design-data-spec 4.0.0 → 4.1.0

package/conformance/README.md

@@ -79,14 +79,14 @@ These fixtures verify the field-mapping contract in [Evolution — Legacy format
 | Folder                      | Intent                                                                                             |
 | --------------------------- | -------------------------------------------------------------------------------------------------- |
 | `generation/flat-token`     | A single cascade token with no mode sets maps to a single keyed entry `{ slug: { value, uuid } }`. |
-| `generation/mode-set-token` | Multiple cascade tokens sharing a `set_uuid` merge into a single `sets`-keyed entry.               |
+| `generation/mode-set-token` | Multiple cascade tokens sharing a `conceptId` merge into a single `sets`-keyed entry.              |
 
 The Rust SDK drives these fixtures via `design-data migrate legacy-output` (see `sdk/core/src/legacy.rs`).
 Consumer implementations MUST regenerate each `input/` and diff against `expected/` to claim conformance
 with the output-generator determinism contract.
 
 See [`generation/README.md`](generation/README.md) for the fixture format, the run command, and
-documentation of the `set_uuid`/`set_schema` cascade grouping fields used in `mode-set-token`.
+documentation of the `conceptId`/`set_schema` cascade grouping fields used in `mode-set-token`.
 
 ***
 

package/conformance/generation/README.md

@@ -38,20 +38,20 @@ design-data migrate legacy-output <case>/input --output <case>/expected
 | Case               | What it exercises                                                                                           |
 | ------------------ | ----------------------------------------------------------------------------------------------------------- |
 | `flat-token`       | Basic flat token conversion (property key derivation, field passthrough)                                    |
-| `mode-set-token`   | Color-set reconstruction from per-mode cascade records (`set_uuid`/`set_schema`)                            |
+| `mode-set-token`   | Color-set reconstruction from per-mode cascade records (`conceptId`/`set_schema`)                           |
 | `deprecated-token` | `deprecated: "version"` string → `true` boolean; `deprecated_comment` passthrough; `plannedRemoval` dropped |
 | `renamed-token`    | `replaced_by: "<uuid>"` → `renamed: "<property-name>"` via global UUID→name map                             |
 | `alias-rewire`     | `$ref: "<uuid>"` → `value: "{<property-name>}"` (alias denormalization with UUID resolution)                |
 | `mode-set-edit`    | `deprecated`/`renamed` hoisted to outer set level when consistent across all mode entries                   |
 
-## Cascade grouping fields (`set_uuid` / `set_schema`)
+## Cascade grouping fields (`conceptId` / `set_schema`)
 
 The `mode-set-token` and `mode-set-edit` fixtures use two cascade-internal grouping fields:
 
-| Field        | Type   | Role                                                                                                                                                                                                                                                                             |
-| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `set_uuid`   | string | Shared UUID that groups per-mode cascade records into one set-keyed legacy entry. The SDK registers this as `set_uuid → child-key list` in `sdk/core/src/graph.rs` and the legacy generator collapses all records sharing a `set_uuid` into a single `sets`-keyed output object. |
-| `set_schema` | string | The `$schema` URI of the aggregate set token emitted at the outer (non-mode-keyed) level in the legacy output (e.g. `color-set.json`).                                                                                                                                           |
+| Field        | Type   | Role                                                                                                                                                                                                                                                                        |
+| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `conceptId`  | string | Canonical concept-level UUID shared by every mode row of a design concept. The SDK registers this as `conceptId → child-key list` in `sdk/core/src/graph.rs` and the legacy generator collapses all records sharing a `conceptId` into a single `sets`-keyed output object. |
+| `set_schema` | string | The `$schema` URI of the aggregate set token emitted at the outer (non-mode-keyed) level in the legacy output (e.g. `color-set.json`).                                                                                                                                      |
 
 These fields are not yet in the normative token-format field table — they are Rust SDK
 implementation fields defined in `sdk/core/src/graph.rs` and emitted by the cascade ingest

package/conformance/generation/mode-set-edit/input/tokens.tokens.json

@@ -9,7 +9,7 @@
     "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
     "value": "rgb(20, 115, 230)",
     "uuid": "11111111-0001-4000-8000-000000000001",
-    "set_uuid": "11111111-0003-4000-8000-000000000003",
+    "conceptId": "11111111-0003-4000-8000-000000000003",
     "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
     "lifecycle": {
       "deprecatedIn": true,
@@ -26,7 +26,7 @@
     "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
     "value": "rgb(56, 145, 254)",
     "uuid": "11111111-0002-4000-8000-000000000002",
-    "set_uuid": "11111111-0003-4000-8000-000000000003",
+    "conceptId": "11111111-0003-4000-8000-000000000003",
     "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
     "lifecycle": {
       "deprecatedIn": true,
@@ -38,7 +38,7 @@
     "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
     "value": "rgb(20, 115, 230)",
     "uuid": "11111111-0004-4000-8000-000000000004",
-    "set_uuid": "11111111-0005-4000-8000-000000000005",
+    "conceptId": "11111111-0005-4000-8000-000000000005",
     "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
   }
 ]

package/conformance/generation/mode-set-token/input/tokens.tokens.json

@@ -9,7 +9,7 @@
     "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
     "value": "rgb(245, 249, 255)",
     "uuid": "bbbbbbbb-0001-4000-8000-000000000001",
-    "set_uuid": "cccccccc-0001-4000-8000-000000000001",
+    "conceptId": "cccccccc-0001-4000-8000-000000000001",
     "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
     "private": true
   },
@@ -23,7 +23,7 @@
     "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
     "value": "rgb(14, 23, 63)",
     "uuid": "bbbbbbbb-0002-4000-8000-000000000002",
-    "set_uuid": "cccccccc-0001-4000-8000-000000000001",
+    "conceptId": "cccccccc-0001-4000-8000-000000000001",
     "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
     "private": true
   }

package/conformance/reference/set-alias-dark/expected.json

@@ -1,5 +1,5 @@
 {
-  "description": "A set-level alias ($ref targeting a set_uuid) MUST resolve to the mode-appropriate child. Under colorScheme=dark, accent-color-900 → blue-900 dark (different value from light).",
+  "description": "A set-level alias ($ref targeting a conceptId) MUST resolve to the mode-appropriate child. Under colorScheme=dark, accent-color-900 → blue-900 dark (different value from light).",
   "resolved": true,
   "expected_value": "rgb(75, 117, 255)",
   "expected_chain_length": 3,

package/conformance/reference/set-alias-dark/input/tokens.tokens.json

@@ -9,7 +9,7 @@
     "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
     "value": "rgb(59, 99, 251)",
     "uuid": "ref-blue900-light-0000-000000000002",
-    "set_uuid": "ref-blue900-set-000-0000-000000000002"
+    "conceptId": "ref-blue900-set-000-0000-000000000002"
   },
   {
     "name": {
@@ -21,7 +21,7 @@
     "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
     "value": "rgb(75, 117, 255)",
     "uuid": "ref-blue900-dark-0000-000000000002",
-    "set_uuid": "ref-blue900-set-000-0000-000000000002"
+    "conceptId": "ref-blue900-set-000-0000-000000000002"
   },
   {
     "name": { "property": "accent-color-900" },

package/conformance/reference/set-alias-light/expected.json

@@ -1,5 +1,5 @@
 {
-  "description": "A set-level alias ($ref targeting a set_uuid) MUST resolve to the mode-appropriate child. Under colorScheme=light, accent-color-900 → blue-900 light.",
+  "description": "A set-level alias ($ref targeting a conceptId) MUST resolve to the mode-appropriate child. Under colorScheme=light, accent-color-900 → blue-900 light.",
   "resolved": true,
   "expected_value": "rgb(59, 99, 251)",
   "expected_chain_length": 3,

package/conformance/reference/set-alias-light/input/tokens.tokens.json

@@ -9,7 +9,7 @@
     "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
     "value": "rgb(59, 99, 251)",
     "uuid": "ref-blue900-light-0000-000000000001",
-    "set_uuid": "ref-blue900-set-000-0000-000000000001"
+    "conceptId": "ref-blue900-set-000-0000-000000000001"
   },
   {
     "name": {
@@ -21,7 +21,7 @@
     "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
     "value": "rgb(75, 117, 255)",
     "uuid": "ref-blue900-dark-0000-000000000001",
-    "set_uuid": "ref-blue900-set-000-0000-000000000001"
+    "conceptId": "ref-blue900-set-000-0000-000000000001"
   },
   {
     "name": { "property": "accent-color-900" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for the design data format",
   "type": "module",
   "repository": {

package/rules/rules.yaml

@@ -707,3 +707,20 @@ rules:
     message: "Relationship $ref {ref} resolves to a token deprecated in {deprecatedIn}"
     spec_ref: spec/relationship-format.md#legacy-fields-interim
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-059
+    name: alias-mode-context-compatibility
+    severity: warning
+    layer: 2
+    category: reference-integrity
+    note: >
+      Mode analogue of SPEC-002. A `$ref` target that is a `conceptId` (see
+      token-format.md#concept-identity-conceptid) is context-resolved elsewhere and exempt
+      here; only a direct per-value target is checked.
+    assert: >
+      An alias whose name object sets a mode-set field (e.g. `colorScheme: dark`) SHOULD NOT
+      resolve, via its `$ref` chain, to a per-value token that sets the same field to a
+      different value. Tokens whose name object omits the field (mode-agnostic) are exempt.
+    message: "Alias {token} sets {field}={ownValue} but its $ref chain resolves to a token with {field}={leafValue}"
+    spec_ref: spec/cascade.md#alias-resolution
+    introduced_in: "1.0.0-draft"

package/spec/cascade.md

@@ -57,7 +57,9 @@ Exact matching rules for omitted mode sets are defined alongside mode set declar
 
 **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.
+**NORMATIVE:** When a `$ref` target is a **`conceptId`** (see [`token-format.md` §Concept identity](token-format.md#concept-identity-conceptid)) rather than a per-row `uuid`, resolution **MUST** pick the mode row registered under that `conceptId` whose name-object fields best match the referencing token's own resolution context (greatest count of matching mode-set key/value pairs). Ties **MUST** be broken by the lexicographically smallest `uuid` among equally-scoring rows, so repeated resolution of the same alias always returns the same token. This context-aware step runs in place of, not in addition to, the UUID-first/direct-key/name fallback above — a `conceptId` target either resolves to its best-matching row or (when no rows are registered under it) falls through to the standard chain.
+
+**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. Resolving a `conceptId` target against the *referencing* token's own context (rather than always the first or an arbitrary row) is what lets one alias correctly track a multi-mode concept (e.g. a semantic color that must stay light/dark-aligned with whatever aliases to it) without one alias per mode.
 
 ## Cross-mode-set overrides
 

package/spec/token-format.md

@@ -128,6 +128,34 @@ When **`$ref`** is present, the token is an **alias**. The value **MUST** be a n
   "uuid": "f24eb871-6419-4cef-88a2-cca8548ae31e" }
 ```
 
+### Concept identity (`conceptId`)
+
+**`conceptId`** is a UUID shared by every mode row of the same design concept — e.g. the light,
+dark, and wireframe rows of one color, or the mobile/desktop rows of one scale. It is additive to
+the per-value `uuid` (which remains the `$ref`/diff/`replacedBy`/sync anchor for one specific mode
+row) and, unlike `uuid`, is stable across the whole concept rather than one row.
+
+```json
+// Two mode rows of the same concept share one conceptId, each with its own uuid.
+{ "name": { "property": "accent-color", "colorScheme": "light" },
+  "value": "rgb(59, 99, 251)",
+  "uuid": "aaaaaaaa-0000-4000-8000-000000000001",
+  "conceptId": "cccccccc-0000-4000-8000-000000000099" }
+{ "name": { "property": "accent-color", "colorScheme": "dark" },
+  "value": "rgb(75, 117, 255)",
+  "uuid": "aaaaaaaa-0000-4000-8000-000000000002",
+  "conceptId": "cccccccc-0000-4000-8000-000000000099" }
+```
+
+**NORMATIVE:** All mode rows of the same design concept **MUST** carry the same `conceptId`.
+
+**NORMATIVE:** A `$ref` target **MAY** be a `conceptId` instead of a per-row `uuid`. When it is,
+resolution **MUST** pick the mode row registered under that `conceptId` whose name-object fields
+best match the referencing token's own resolution context (see
+[Cascade resolution — Alias resolution](cascade.md#alias-resolution)), rather than an arbitrary
+row — this is what makes a single alias correctly track light/dark or mobile/desktop without one
+alias per mode.
+
 ### Literal `value`
 
 When **`value`** is present, it **MUST** conform to the declared value type for that token. Value types are defined under `schemas/value-types/` and referenced from the token schema.