@adobe/design-data-spec 4.0.0 → 4.2.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/manifest-extensions/README.md

@@ -4,7 +4,7 @@ Exercises the Layer 2 platform manifest's `extensions/` **directory** loader
 (`packages/design-data-spec/spec/manifest.md#extensions-directory`): a sibling
 `extensions/` tree (or a custom name via the manifest's `extensionsDir` field)
 whose category subdirectories (`tokens/`, `components/`, `fields/`,
-`guidelines/`, `platform-extensions/`, `relationships/`) are discovered,
+`guidelines/`, `mode-sets/`, `platform-extensions/`, `relationships/`) are discovered,
 glob+merged in sorted path order, per-fragment schema-validated, and spliced
 into the manifest before it's applied to the graph.
 
@@ -23,6 +23,7 @@ into the manifest before it's applied to the graph.
     },
     "components": { "present": ["tab-bar-ios"] },
     "fields": { "present": ["hapticStyle"] },
+    "modeSets": { "present": ["interfaceLevel"] },
     "guidelines": { "present": ["ios-haptics"] },
     "tokens": { "orderByUuid": ["<uuid-1>", "<uuid-2>"] }
   }
@@ -42,6 +43,7 @@ Rust SDK drives these fixtures in `sdk/core/src/lib.rs` via the
 | `valid/injects-platform-extension`             | A `platform-extensions/` fragment is injected.                                                                           |
 | `valid/injects-field`                          | A `fields/` fragment is injected.                                                                                        |
 | `valid/injects-guideline`                      | A `guidelines/` fragment is injected.                                                                                    |
+| `valid/injects-mode-set`                       | A `mode-sets/` fragment is injected (declare-or-replace by name).                                                        |
 | `valid/injects-relationship`                   | A `relationships/` plain-add fragment is injected.                                                                       |
 | `valid/override-relationship-by-uuid`          | An `op: "override"` entry replaces a plain add sharing its `uuid`, regardless of file sort order.                        |
 | `valid/plain-add-uuid-collision-append`        | Two plain adds sharing a `uuid` both append rather than one overwriting the other.                                       |
@@ -55,6 +57,7 @@ Rust SDK drives these fixtures in `sdk/core/src/lib.rs` via the
 | `invalid/component-missing-name`               | A `components/` fragment missing `name` fails Layer 1 fragment schema validation.                                        |
 | `invalid/field-invalid-kind`                   | A `fields/` fragment with an invalid `kind` enum value fails schema validation.                                          |
 | `invalid/guideline-invalid-category`           | A `guidelines/` fragment with an invalid `category` enum value fails schema validation.                                  |
+| `invalid/mode-set-missing-default`             | A `mode-sets/` fragment missing the required `default` field fails Layer 1 fragment schema validation.                   |
 | `invalid/platform-extension-missing-extends`   | A `platform-extensions/` fragment missing `extends` fails schema validation.                                             |
 | `invalid/token-invalid-uuid`                   | A `tokens/*.tokens.json` fragment with a malformed `uuid` fails schema validation.                                       |
 | `invalid/relationship-missing-scope`           | A `relationships/` plain-add fragment missing `scope` fails schema validation.                                           |

package/conformance/manifest-extensions/invalid/mode-set-missing-default/expected-errors.json

@@ -0,0 +1,7 @@
+{
+  "errors": [
+    { "message_pattern": "broken\\.json" },
+    { "message_pattern": "mode-set\\.schema\\.json" },
+    { "message_pattern": "\"default\"" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-missing-default/extensions/mode-sets/broken.json

@@ -0,0 +1 @@
+{ "name": "interfaceLevel", "modes": ["base", "elevated"] }

package/conformance/manifest-extensions/invalid/mode-set-missing-default/manifest.json

@@ -0,0 +1,4 @@
+{
+  "specVersion": "1.0.0-draft",
+  "foundationVersion": "1.0.0"
+}

package/conformance/manifest-extensions/invalid/mode-set-remove-mode-of-default/expected-errors.json

@@ -0,0 +1,6 @@
+{
+  "errors": [
+    { "message_pattern": "removeMode" },
+    { "message_pattern": "current default" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-remove-mode-of-default/extensions/mode-sets/remove-desktop.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "removeMode", "mode": "desktop" }

package/conformance/manifest-extensions/invalid/mode-set-remove-mode-of-default/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile"], "default": "desktop" }

package/conformance/manifest-extensions/invalid/mode-set-remove-mode-of-default/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/invalid/mode-set-set-default-nonmember/expected-errors.json

@@ -0,0 +1,6 @@
+{
+  "errors": [
+    { "message_pattern": "setDefault" },
+    { "message_pattern": "not in its modes" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-set-default-nonmember/extensions/mode-sets/default-tv.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "setDefault", "default": "tv" }

package/conformance/manifest-extensions/invalid/mode-set-set-default-nonmember/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile"], "default": "desktop" }

package/conformance/manifest-extensions/invalid/mode-set-set-default-nonmember/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/invalid/mode-set-target-not-found/expected-errors.json

@@ -0,0 +1,6 @@
+{
+  "errors": [
+    { "message_pattern": "\"scale\"" },
+    { "message_pattern": "does not exist" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-target-not-found/extensions/mode-sets/add-tv.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "addMode", "mode": "tv" }

package/conformance/manifest-extensions/invalid/mode-set-target-not-found/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/invalid/mode-set-unknown-op/expected-errors.json

@@ -0,0 +1,6 @@
+{
+  "errors": [
+    { "message_pattern": "unknown op" },
+    { "message_pattern": "\"bogus\"" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-unknown-op/extensions/mode-sets/bogus.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "bogus" }

package/conformance/manifest-extensions/invalid/mode-set-unknown-op/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile"], "default": "desktop" }

package/conformance/manifest-extensions/invalid/mode-set-unknown-op/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/valid/injects-mode-set/expected.json

@@ -0,0 +1 @@
+{ "modeSets": { "present": ["interfaceLevel"] } }

package/conformance/manifest-extensions/valid/injects-mode-set/extensions/mode-sets/interface-level.json

@@ -0,0 +1,5 @@
+{
+  "name": "interfaceLevel",
+  "modes": ["base", "elevated"],
+  "default": "base"
+}

package/conformance/manifest-extensions/valid/injects-mode-set/manifest.json

@@ -0,0 +1,4 @@
+{
+  "specVersion": "1.0.0-draft",
+  "foundationVersion": "1.0.0"
+}

package/conformance/manifest-extensions/valid/mode-set-add-mode/expected.json

@@ -0,0 +1,8 @@
+{
+  "modeSets": {
+    "present": ["scale"],
+    "modes": {
+      "scale": { "modes": ["desktop", "mobile", "tv"], "default": "desktop" }
+    }
+  }
+}

package/conformance/manifest-extensions/valid/mode-set-add-mode/extensions/mode-sets/add-tv.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "addMode", "mode": "tv" }

package/conformance/manifest-extensions/valid/mode-set-add-mode/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile"], "default": "desktop" }

package/conformance/manifest-extensions/valid/mode-set-add-mode/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/valid/mode-set-remove/expected.json

@@ -0,0 +1 @@
+{ "modeSets": { "absent": ["contrast"] } }

package/conformance/manifest-extensions/valid/mode-set-remove/extensions/mode-sets/contrast.json

@@ -0,0 +1 @@
+{ "name": "contrast", "modes": ["regular", "high"], "default": "regular" }

package/conformance/manifest-extensions/valid/mode-set-remove/extensions/mode-sets/remove-contrast.json

@@ -0,0 +1 @@
+{ "name": "contrast", "op": "remove" }

package/conformance/manifest-extensions/valid/mode-set-remove/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/valid/mode-set-remove-mode/expected.json

@@ -0,0 +1,8 @@
+{
+  "modeSets": {
+    "present": ["colorScheme"],
+    "modes": {
+      "colorScheme": { "modes": ["light", "dark"], "default": "light" }
+    }
+  }
+}

package/conformance/manifest-extensions/valid/mode-set-remove-mode/extensions/mode-sets/color-scheme.json

@@ -0,0 +1,5 @@
+{
+  "name": "colorScheme",
+  "modes": ["light", "dark", "wireframe"],
+  "default": "light"
+}

package/conformance/manifest-extensions/valid/mode-set-remove-mode/extensions/mode-sets/remove-wireframe.json

@@ -0,0 +1 @@
+{ "name": "colorScheme", "op": "removeMode", "mode": "wireframe" }

package/conformance/manifest-extensions/valid/mode-set-remove-mode/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/valid/mode-set-set-default/expected.json

@@ -0,0 +1,6 @@
+{
+  "modeSets": {
+    "present": ["scale"],
+    "modes": { "scale": { "default": "tv" } }
+  }
+}

package/conformance/manifest-extensions/valid/mode-set-set-default/extensions/mode-sets/default-tv.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "setDefault", "default": "tv" }

package/conformance/manifest-extensions/valid/mode-set-set-default/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile", "tv"], "default": "desktop" }

package/conformance/manifest-extensions/valid/mode-set-set-default/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

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.2.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/manifest.md

@@ -8,23 +8,25 @@ This document defines the **platform manifest**: how a platform implementation r
 
 The manifest supports a fixed, enumerated set of operations against the foundation — it does **not** allow overriding, aliasing, or removing arbitrary foundation artifacts. Support is concentrated on tokens; translations and schemas have no manifest-level override mechanism at all.
 
-| Operation                                          | Supported?                                                   | Field                             | Applies to            |
-| -------------------------------------------------- | ------------------------------------------------------------ | --------------------------------- | --------------------- |
-| Remove / exclude                                   | Yes                                                          | `exclude`                         | Tokens only           |
-| Include / whitelist                                | Yes                                                          | `include`                         | Tokens only           |
-| Override value (type-preserving)                   | Yes                                                          | `overrides[].value`               | Tokens only           |
-| Override → re-alias                                | Yes                                                          | `overrides[].$ref`                | Tokens only           |
-| Add new tokens (may alias via `$ref`)              | Yes                                                          | `extensions/tokens/`              | Tokens                |
-| Add / replace components                           | Yes                                                          | `extensions/components/`          | Components            |
-| Add / replace field declarations                   | Yes                                                          | `extensions/fields/`              | Fields                |
-| Add / replace guideline documents                  | Yes                                                          | `extensions/guidelines/`          | Guidelines            |
-| Add relationships/CTRs; override/remove by `uuid`  | Yes                                                          | `extensions/relationships/`       | Relationships (CTRs)  |
-| Add / remove naming exceptions                     | Yes                                                          | `namingExceptions`                | Naming validation     |
-| Annotate existing terminology (cannot add new ids) | Yes                                                          | `extensions/platform-extensions/` | Existing registry ids |
-| Restrict allowed mode-set values                   | Yes                                                          | `modeSetRestrictions`             | Mode sets             |
-| Reformat name serialization                        | Schema-declared only, not yet applied by the reference SDK   | `formatting`                      | Token name strings    |
-| Override/remove/alias translations                 | No                                                           | —                                 | —                     |
-| Override Layer-1 schemas                           | No (decided; see [spike](manifest-schema-override-spike.md)) | —                                 | —                     |
+| Operation                                           | Supported?                                                   | Field                             | Applies to            |
+| --------------------------------------------------- | ------------------------------------------------------------ | --------------------------------- | --------------------- |
+| Remove / exclude                                    | Yes                                                          | `exclude`                         | Tokens only           |
+| Include / whitelist                                 | Yes                                                          | `include`                         | Tokens only           |
+| Override value (type-preserving)                    | Yes                                                          | `overrides[].value`               | Tokens only           |
+| Override → re-alias                                 | Yes                                                          | `overrides[].$ref`                | Tokens only           |
+| Add new tokens (may alias via `$ref`)               | Yes                                                          | `extensions/tokens/`              | Tokens                |
+| Add / replace components                            | Yes                                                          | `extensions/components/`          | Components            |
+| Add / replace field declarations                    | Yes                                                          | `extensions/fields/`              | Fields                |
+| Add / replace guideline documents                   | Yes                                                          | `extensions/guidelines/`          | Guidelines            |
+| Declare / replace platform-local mode set           | Yes                                                          | `extensions/mode-sets/`           | Mode sets             |
+| Add / remove / retarget a single mode; remove a set | Yes                                                          | `extensions/mode-sets/` (`op`)    | Mode sets             |
+| Add relationships/CTRs; override/remove by `uuid`   | Yes                                                          | `extensions/relationships/`       | Relationships (CTRs)  |
+| Add / remove naming exceptions                      | Yes                                                          | `namingExceptions`                | Naming validation     |
+| Annotate existing terminology (cannot add new ids)  | Yes                                                          | `extensions/platform-extensions/` | Existing registry ids |
+| Restrict allowed mode-set values                    | Yes                                                          | `modeSetRestrictions`             | Mode sets             |
+| Reformat name serialization                         | Schema-declared only, not yet applied by the reference SDK   | `formatting`                      | Token name strings    |
+| Override/remove/alias translations                  | No                                                           | —                                 | —                     |
+| Override Layer-1 schemas                            | No (decided; see [spike](manifest-schema-override-spike.md)) | —                                 | —                     |
 
 ## Manifest document
 
@@ -86,6 +88,7 @@ extensions/
   tokens/               *.tokens.json          cascade-format token files
   components/           <component>.json       one component per file
   fields/                <field>.json          one field declaration per file
+  mode-sets/             <mode-set>.json       one mode set per file
   relationships/         <component>.json      one CTR set per file
   guidelines/             <topic>.json         one guideline per file
   platform-extensions/   <platform>-<registry>.json
@@ -103,7 +106,7 @@ or empty subdirectory contributes nothing and is not an error.
   cascade token file) and **MUST** validate against `cascade-file.schema.json`. Files are
   **deep-merged** into one tokens object, in sorted path order. Entries **MAY** carry a `$ref`
   to alias an existing token instead of a literal value.
-* **`components/`, `fields/`, `guidelines/`, `platform-extensions/`** — one artifact per file.
+* **`components/`, `fields/`, `guidelines/`, `mode-sets/`, `platform-extensions/`** — one artifact per file.
   Entries across all files in the subdirectory are concatenated, in sorted path order, and
   injected into the corresponding catalog **add-or-replace by name** (for
   `platform-extensions/`, by `termId`; see below). When two files declare the same name,
@@ -115,6 +118,7 @@ load time — this is enforced reference-SDK behavior, not an aspirational goal:
 * **`components/`** → `component.schema.json`
 * **`fields/`** → `field.schema.json` (see [`extensions/fields/`](#extensionsfields) below)
 * **`guidelines/`** → `guideline.schema.json`
+* **`mode-sets/`** → `mode-set.schema.json` (see [`extensions/mode-sets/`](#extensionsmode-sets) below)
 * **`relationships/`** → `relationship.schema.json` (see the Add/Override/remove rules above)
 * **`platform-extensions/`** → `platform-extension.json` (see
   [`extensions/platform-extensions/`](#extensionsplatform-extensions) below)
@@ -143,6 +147,45 @@ declared) references field names by string — a platform that renames or remove
 also references there is self-inconsistent; that is a manifest-authoring concern, not enforced
 by the reference SDK.
 
+#### `extensions/mode-sets/`
+
+Platform-local mode-set declarations and edits, injected into the mode-set catalog for this
+platform's resolution. A mode set's `name` is its stable key (there is no separate `uuid`, unlike
+relationships) — every entry, add or op alike, identifies its target by `name`:
+
+* **Add / replace:** an entry with no `op` field is a full mode-set object (**NORMATIVE:** MUST
+  validate against `mode-set.schema.json`, requiring `name`, `modes`, `default`). A `name` not
+  already in the foundation catalog is a clean new platform axis (e.g. `interfaceLevel: [base,
+  elevated]`); a `name` matching a foundation mode set replaces it, for this platform only — the
+  foundation catalog is untouched.
+* **`"op": "addMode"`** — appends one mode value (`mode`) to an existing set, without restating its
+  other modes. **NORMATIVE:** the target set (by `name`) MUST already exist and MUST NOT already
+  contain `mode`; either condition failing is a manifest error.
+* **`"op": "removeMode"`** — drops one mode value (`mode`) from an existing set. **NORMATIVE:** the
+  target MUST exist, MUST contain `mode`, `mode` MUST NOT be the set's current default (retarget the
+  default first with `setDefault`), the set MUST have more than one mode remaining afterward, and no
+  token in the resolved graph MAY still carry `mode` as that mode set's value — each violation is a
+  manifest error. (This mirrors the reference SDK's authoring-time `remove_mode` guard, which checks
+  the same "still referenced" condition against cascade token files.)
+* **`"op": "setDefault"`** — retargets an existing set's default mode (`default`). **NORMATIVE:**
+  the target MUST exist and `default` MUST already be one of its modes.
+* **`"op": "remove"`** — drops the whole set (by `name`) from this platform's resolution.
+  **NORMATIVE:** the target MUST exist, and no token in the resolved graph MAY still carry this mode
+  set's `name` as a key — either violation is a manifest error.
+
+Add/replace entries are applied before op entries, regardless of file sort order, so a set declared
+in one file can be edited by an op in another file within the same `extensions/mode-sets/`
+directory. Ops within each group apply in sorted path order. Any other `op` value, or an op entry
+missing its required field (`mode` for `addMode`/`removeMode`, `default` for `setDefault`), is a
+manifest error — the reference SDK rejects the load rather than silently skipping it, consistent
+with `extensions/relationships/`'s override/remove ops above. `default ∈ modes` remains a Layer 2
+concern for the resolved graph as a whole, enforced by SPEC-005 against whichever mode sets end up
+there, foundation or platform-declared alike.
+
+Contrast with `modeSetRestrictions` ([Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions)), a top-level manifest field that only *narrows* the allowed values of an
+existing mode set at resolution time — it cannot add, remove, or retarget a mode value, or declare
+a new axis.
+
 #### `extensions/platform-extensions/`
 
 Platform terminology annotations layered onto **existing** foundation registry entries (for

package/spec/mode-sets.md

@@ -45,6 +45,16 @@ The Spectrum foundation publishes mode set declarations as JSON files under `pac
 
 Additional mode sets (e.g. `language`, `motion`) **MAY** be declared in a dataset's mode set catalog. Token name objects **MAY** include keys matching declared mode set names.
 
+A platform manifest **MAY** also declare or edit mode sets local to that platform, one entry per
+file under `extensions/mode-sets/` (see [Platform manifest — `extensions/`
+directory](manifest.md#extensions-directory)). An entry with no `op` uses **declare-or-replace-by-name** semantics, same as `extensions/fields/`: a new `name` adds a platform-local axis (e.g.
+`interfaceLevel`), while a `name` matching a foundation mode set replaces it for that platform only,
+leaving the foundation catalog untouched. `op: "addMode"` / `"removeMode"` / `"setDefault"` /
+`"remove"` instead edit an existing set in place — adding or dropping a single mode value,
+retargeting its default, or dropping the whole set — without restating its other modes. This is
+distinct from `modeSetRestrictions` (below), which only *narrows* the allowed values of an existing
+mode set at resolution time rather than editing the declared set itself.
+
 ## Defaults and specificity
 
 **NORMATIVE:** A token name object **omitting** a mode set field implies the token applies under the mode set's **`default`** mode for specificity and matching purposes unless the spec for that mode set states otherwise.

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.