@adobe/design-data-spec 3.5.0 → 4.1.0

package/conformance/manifest-extensions/valid/override-relationship-by-uuid/expected.json

@@ -0,0 +1,7 @@
+{
+  "relationships": {
+    "byUuid": {
+      "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a": { "count": 1, "value": "8px" }
+    }
+  }
+}

package/conformance/manifest-extensions/valid/override-relationship-by-uuid/extensions/relationships/a-override.json

@@ -0,0 +1,9 @@
+{
+  "op": "override",
+  "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a",
+  "value": {
+    "scope": { "component": "button", "property": "corner-radius" },
+    "value": "8px",
+    "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"
+  }
+}

package/conformance/manifest-extensions/valid/override-relationship-by-uuid/extensions/relationships/z-add.json

@@ -0,0 +1,5 @@
+{
+  "scope": { "component": "button", "property": "corner-radius" },
+  "value": "4px",
+  "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"
+}

package/conformance/manifest-extensions/valid/override-relationship-by-uuid/manifest.json

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

package/conformance/manifest-extensions/valid/plain-add-uuid-collision-append/expected.json

@@ -0,0 +1,5 @@
+{
+  "relationships": {
+    "byUuid": { "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a": { "count": 2 } }
+  }
+}

package/conformance/manifest-extensions/valid/plain-add-uuid-collision-append/extensions/relationships/button.json

@@ -0,0 +1,5 @@
+{
+  "scope": { "component": "button", "property": "corner-radius" },
+  "value": "4px",
+  "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"
+}

package/conformance/manifest-extensions/valid/plain-add-uuid-collision-append/extensions/relationships/slider.json

@@ -0,0 +1,5 @@
+{
+  "scope": { "component": "slider", "property": "corner-radius" },
+  "value": "2px",
+  "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"
+}

package/conformance/manifest-extensions/valid/plain-add-uuid-collision-append/manifest.json

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

package/conformance/manifest-extensions/valid/remove-relationship-by-uuid/expected.json

@@ -0,0 +1 @@
+{ "relationships": { "absent": ["9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"] } }

package/conformance/manifest-extensions/valid/remove-relationship-by-uuid/extensions/relationships/button.json

@@ -0,0 +1,5 @@
+{
+  "scope": { "component": "button", "property": "corner-radius" },
+  "value": "4px",
+  "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"
+}

package/conformance/manifest-extensions/valid/remove-relationship-by-uuid/extensions/relationships/remove-button.json

@@ -0,0 +1,4 @@
+{
+  "op": "remove",
+  "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"
+}

package/conformance/manifest-extensions/valid/remove-relationship-by-uuid/manifest.json

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

package/conformance/manifest-extensions/valid/tokens-sorted-order/expected.json

@@ -0,0 +1,8 @@
+{
+  "tokens": {
+    "orderByUuid": [
+      "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f01",
+      "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f02"
+    ]
+  }
+}

package/conformance/manifest-extensions/valid/tokens-sorted-order/extensions/tokens/a.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "elevation", "component": "card" },
+    "value": "4dp",
+    "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f01"
+  }
+]

package/conformance/manifest-extensions/valid/tokens-sorted-order/extensions/tokens/b.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "elevation", "component": "sheet" },
+    "value": "8dp",
+    "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f02"
+  }
+]

package/conformance/manifest-extensions/valid/tokens-sorted-order/manifest.json

@@ -0,0 +1,4 @@
+{
+  "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": "3.5.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/schemas/manifest.schema.json

@@ -83,122 +83,64 @@
         "additionalProperties": false
       }
     },
-    "extensions": {
+    "extensionsDir": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path (relative to the manifest) to the platform's extensions directory, holding platform-local tokens/components/fields/relationships/guidelines/platform-extensions as one file per artifact (see spec/manifest.md#extensions-directory). Default: \"extensions\"."
+    },
+    "namingExceptions": {
       "type": "object",
-      "description": "Platform-local tokens, mode sets, and formatting rules.",
+      "description": "Platform-local overlay on the base naming-exceptions set: names to add and/or remove for this platform's naming validation.",
       "properties": {
-        "tokens": {
-          "$ref": "cascade-file.schema.json",
-          "description": "Platform-local token definitions, in cascade-format (same shape as a cascade token file)."
-        },
-        "components": {
+        "add": {
           "type": "array",
-          "items": { "$ref": "component.schema.json" },
-          "description": "Platform-local component specs, injected into the component catalog (add-or-replace by name)."
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Token names to add to the naming-exceptions set for this platform."
         },
-        "fields": {
+        "remove": {
           "type": "array",
-          "items": { "$ref": "field.schema.json" },
-          "description": "Platform-local field declarations, injected into the field catalog (add-or-replace by name)."
-        },
-        "relationships": {
-          "type": "array",
-          "items": {
-            "oneOf": [
-              { "$ref": "relationship.schema.json#/$defs/relationship" },
-              {
-                "type": "object",
-                "required": ["op", "uuid", "value"],
-                "properties": {
-                  "op": { "const": "override" },
-                  "uuid": { "type": "string", "format": "uuid" },
-                  "value": {
-                    "$ref": "relationship.schema.json#/$defs/relationship"
-                  }
-                },
-                "additionalProperties": false
-              },
-              {
-                "type": "object",
-                "required": ["op", "uuid"],
-                "properties": {
-                  "op": { "const": "remove" },
-                  "uuid": { "type": "string", "format": "uuid" }
-                },
-                "additionalProperties": false
-              }
-            ]
-          },
-          "description": "Platform-local Component/Token Relationship (CTR) add/override/remove. Entries without \"op\" are added positionally; \"override\"/\"remove\" require a \"uuid\" to target an existing relationship."
-        },
-        "platformExtensions": {
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Token names to remove from the base naming-exceptions set for this platform."
+        }
+      },
+      "additionalProperties": false
+    },
+    "formatting": {
+      "type": "object",
+      "description": "Rules for serializing structured name objects into platform-specific token name strings.",
+      "properties": {
+        "conceptOrder": {
           "type": "array",
           "items": {
-            "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/platform-extension.json"
+            "type": "string"
           },
-          "description": "Platform-local terminology extensions (e.g. iOS state vocabulary), annotating ids in an existing base registry."
+          "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."
         },
-        "guidelines": {
-          "type": "array",
-          "items": { "$ref": "guideline.schema.json" },
-          "description": "Platform-local guideline docs, injected into the guideline catalog (add-or-replace by name)."
+        "casing": {
+          "type": "string",
+          "enum": [
+            "kebab-case",
+            "camelCase",
+            "PascalCase",
+            "SCREAMING_SNAKE_CASE"
+          ],
+          "description": "Casing style for serialized token names. Default: kebab-case."
         },
-        "namingExceptions": {
-          "type": "object",
-          "description": "Platform-local overlay on the base naming-exceptions set: names to add and/or remove for this platform's naming validation.",
-          "properties": {
-            "add": {
-              "type": "array",
-              "items": { "type": "string", "minLength": 1 },
-              "description": "Token names to add to the naming-exceptions set for this platform."
-            },
-            "remove": {
-              "type": "array",
-              "items": { "type": "string", "minLength": 1 },
-              "description": "Token names to remove from the base naming-exceptions set for this platform."
-            }
-          },
-          "additionalProperties": false
+        "delimiter": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Character(s) separating concepts in the serialized string. Default: -."
         },
-        "formatting": {
+        "abbreviations": {
           "type": "object",
-          "description": "Rules for serializing structured name objects into platform-specific token name strings.",
-          "properties": {
-            "conceptOrder": {
-              "type": "array",
-              "items": {
-                "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."
-            },
-            "casing": {
-              "type": "string",
-              "enum": [
-                "kebab-case",
-                "camelCase",
-                "PascalCase",
-                "SCREAMING_SNAKE_CASE"
-              ],
-              "description": "Casing style for serialized token names. Default: kebab-case."
-            },
-            "delimiter": {
-              "type": "string",
-              "minLength": 1,
-              "description": "Character(s) separating concepts in the serialized string. Default: -."
-            },
-            "abbreviations": {
-              "type": "object",
-              "additionalProperties": {
-                "type": "string"
-              },
-              "description": "Map of full term to abbreviated form, applied after ordering and before casing."
-            }
+          "additionalProperties": {
+            "type": "string"
           },
-          "additionalProperties": false
+          "description": "Map of full term to abbreviated form, applied after ordering and before casing."
         }
       },
-      "additionalProperties": true
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

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-schema-override-spike.md

@@ -24,9 +24,12 @@ schemas for its own data?
 3. **No concrete need surfaced.** Nothing in the h890.22/h890.23 work (iOS
    externalization, or the guidelines/fields/relationships/naming-exceptions cascade
    additions) needed schema relaxation — every platform-local addition validates fine
-   against the existing schemas via `extensions.*`. The `extensions` object is already
-   `additionalProperties: true`, which covers "the platform wants to attach data the
-   schema doesn't know about" without touching the schema itself.
+   against the existing per-artifact schemas via the `extensions/` directory (see
+   [Manifest — `extensions/` directory](manifest.md#extensions-directory)). Each fragment
+   file there is checked against the same `component.schema.json` /
+   `field.schema.json` / `guideline.schema.json` / etc. as the foundation dataset, which
+   already covers "the platform wants to attach data the schema knows how to validate"
+   without touching the schema itself.
 
 ## Decision