@adobe/design-data-spec 2.6.0 → 2.7.0

package/conformance/generation/README.md

@@ -12,18 +12,41 @@ generation/<case>/
   expected/ — expected legacy output (keyed-object format, one file per input file)
 ```
 
-## Running
+## Automated driver
+
+These fixtures are exercised automatically by the `generation_conformance` module in
+`sdk/core/src/lib.rs`. Each test case runs `legacy::convert_dir` twice and asserts:
+
+1. **Byte-identical output** — the generated files match `expected/` exactly.
+2. **Determinism** — pass 1 and pass 2 output are identical.
 
 ```bash
-design-data migrate legacy-output --output <out-dir> <input-dir>/
-diff <out-dir>/tokens.json expected/tokens.json
+# Run all generation conformance tests:
+moon run sdk:test
+# or directly:
+cd sdk && cargo test generation_conformance
 ```
 
-Byte-identical output with no diff = conformance. Run twice to verify determinism.
+To regenerate `expected/` after changing conversion logic, run the CLI and commit the result:
+
+```bash
+design-data migrate legacy-output <case>/input --output <case>/expected
+```
+
+## Cases
+
+| 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`)                            |
+| `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`)
 
-The `mode-set-token` fixture input uses two cascade-internal grouping fields:
+The `mode-set-token` and `mode-set-edit` fixtures use two cascade-internal grouping fields:
 
 | Field        | Type   | Role                                                                                                                                                                                                                                                                             |
 | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/conformance/generation/alias-rewire/expected/tokens.json

@@ -0,0 +1,12 @@
+{
+  "background": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "{gray-100}",
+    "uuid": "ffffffff-0001-4000-8000-000000000001"
+  },
+  "gray-100": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(255, 255, 255)",
+    "uuid": "ffffffff-0002-4000-8000-000000000002"
+  }
+}

package/conformance/generation/alias-rewire/input/tokens.tokens.json

@@ -0,0 +1,14 @@
+[
+  {
+    "name": { "property": "color", "colorFamily": "background" },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "$ref": "ffffffff-0002-4000-8000-000000000002",
+    "uuid": "ffffffff-0001-4000-8000-000000000001"
+  },
+  {
+    "name": { "property": "color", "colorFamily": "gray-100" },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(255, 255, 255)",
+    "uuid": "ffffffff-0002-4000-8000-000000000002"
+  }
+]

package/conformance/generation/deprecated-token/expected/tokens.json

@@ -0,0 +1,9 @@
+{
+  "red": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(255, 0, 0)",
+    "uuid": "dddddddd-0001-4000-8000-000000000001",
+    "deprecated": true,
+    "deprecated_comment": "Use color-blue-100 instead"
+  }
+}

package/conformance/generation/deprecated-token/input/tokens.tokens.json

@@ -0,0 +1,11 @@
+[
+  {
+    "name": { "property": "color", "colorFamily": "red" },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(255, 0, 0)",
+    "uuid": "dddddddd-0001-4000-8000-000000000001",
+    "deprecated": "2.0",
+    "deprecated_comment": "Use color-blue-100 instead",
+    "plannedRemoval": "3.0"
+  }
+]

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

@@ -0,0 +1,25 @@
+{
+  "accent-400": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
+    "uuid": "11111111-0003-4000-8000-000000000003",
+    "deprecated": true,
+    "sets": {
+      "light": {
+        "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+        "value": "rgb(20, 115, 230)",
+        "uuid": "11111111-0001-4000-8000-000000000001"
+      },
+      "dark": {
+        "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+        "value": "rgb(56, 145, 254)",
+        "uuid": "11111111-0002-4000-8000-000000000002"
+      }
+    },
+    "renamed": "accent-new-400"
+  },
+  "accent-new-400": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(20, 115, 230)",
+    "uuid": "11111111-0004-4000-8000-000000000004"
+  }
+}

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

@@ -0,0 +1,40 @@
+[
+  {
+    "name": {
+      "property": "color",
+      "colorFamily": "accent",
+      "scaleIndex": 400,
+      "colorScheme": "light"
+    },
+    "$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",
+    "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
+    "deprecated": true,
+    "replaced_by": "11111111-0004-4000-8000-000000000004"
+  },
+  {
+    "name": {
+      "property": "color",
+      "colorFamily": "accent",
+      "scaleIndex": 400,
+      "colorScheme": "dark"
+    },
+    "$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",
+    "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
+    "deprecated": true,
+    "replaced_by": "11111111-0004-4000-8000-000000000004"
+  },
+  {
+    "name": { "property": "color", "colorFamily": "accent-new-400" },
+    "$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",
+    "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
+  }
+]

package/conformance/generation/renamed-token/expected/tokens.json

@@ -0,0 +1,14 @@
+{
+  "gray": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(128, 128, 128)",
+    "uuid": "eeeeeeee-0001-4000-8000-000000000001",
+    "deprecated": true,
+    "renamed": "neutral"
+  },
+  "neutral": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(128, 128, 128)",
+    "uuid": "eeeeeeee-0002-4000-8000-000000000002"
+  }
+}

package/conformance/generation/renamed-token/input/tokens.tokens.json

@@ -0,0 +1,16 @@
+[
+  {
+    "name": { "property": "color", "colorFamily": "gray" },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(128, 128, 128)",
+    "uuid": "eeeeeeee-0001-4000-8000-000000000001",
+    "deprecated": true,
+    "replaced_by": "eeeeeeee-0002-4000-8000-000000000002"
+  },
+  {
+    "name": { "property": "color", "colorFamily": "neutral" },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(128, 128, 128)",
+    "uuid": "eeeeeeee-0002-4000-8000-000000000002"
+  }
+]

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

@@ -0,0 +1,25 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "accordion",
+        "property": "space-between",
+        "from": "top",
+        "to": "banana"
+      },
+      "value": "8px"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/accordion.json",
+      "name": "accordion",
+      "displayName": "Accordion",
+      "meta": {
+        "category": "containers",
+        "documentationUrl": "https://spectrum.adobe.com/page/accordion/"
+      },
+      "anatomy": [{ "name": "handle", "description": "Drag handle." }]
+    }
+  ]
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-047",
+      "severity": "error",
+      "message_pattern": ".*space-between endpoint.*banana.*"
+    }
+  ]
+}

package/conformance/valid/SPEC-047/dataset.json

@@ -0,0 +1,25 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "accordion",
+        "property": "space-between",
+        "from": "bottom",
+        "to": "handle"
+      },
+      "value": "8px"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/accordion.json",
+      "name": "accordion",
+      "displayName": "Accordion",
+      "meta": {
+        "category": "containers",
+        "documentationUrl": "https://spectrum.adobe.com/page/accordion/"
+      },
+      "anatomy": [{ "name": "handle", "description": "Drag handle." }]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "2.6.0",
+  "version": "2.7.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

@@ -527,3 +527,20 @@ rules:
     message: "Guideline '{name}' references '{ref}' which is not a known component or guideline"
     spec_ref: spec/guideline-format.md#related-references
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-047
+    name: space-between-endpoint-valid
+    severity: error
+    layer: 2
+    category: reference-integrity
+    assert: >
+      A token name-object with `property` "space-between" MUST carry both `from` and
+      `to` fields, and `from`/`to` MUST NOT appear unless `property` is "space-between".
+      Each of `from`/`to` MUST be one of: an edge position (`positions.json`), a generic
+      anatomy term (`anatomy-terms.json`), or — when `component` is present and declares
+      an `anatomy` array — the `name` of a declared anatomy part on that component.
+      Mirrors SPEC-020's component→anatomy resolution, unioned with the position and
+      generic-anatomy vocabularies.
+    message: "Token '{token}' has space-between endpoint '{endpoint}' that is not a known position, anatomy term, or declared anatomy part on component '{component}'"
+    spec_ref: spec/token-format.md#space-between-endpoints
+    introduced_in: "1.0.0-draft"

package/schemas/field.schema.json

@@ -79,6 +79,11 @@
       "enum": ["string", "integer"],
       "description": "Type of the field value. Default: 'string'.",
       "default": "string"
+    },
+    "excludeFromLegacyKey": {
+      "type": "boolean",
+      "description": "When true, this field is omitted from legacy key generation in naming.rs. Opt-in: absence means false. Use for mode-set selectors, color-domain fields, and legacy-annotation fields that must not appear in the serialized token name.",
+      "default": false
     }
   },
   "additionalProperties": false

package/schemas/token.schema.json

@@ -71,6 +71,14 @@
           "type": "string",
           "description": "Semantic: overall component shape (e.g. uniform)."
         },
+        "from": {
+          "type": "string",
+          "description": "Semantic: starting endpoint of a space-between measurement (e.g. top, edge, text). Paired with `to`; used with property `space-between`."
+        },
+        "to": {
+          "type": "string",
+          "description": "Semantic: ending endpoint of a space-between measurement (e.g. text, visual, control). Paired with `from`; used with property `space-between`."
+        },
         "colorScheme": {
           "type": "string",
           "description": "Mode set: color scheme mode (e.g. light, dark, wireframe)."

package/spec/token-format.md

@@ -71,6 +71,25 @@ The table below lists all semantic fields. Fields marked with a scope are domain
 | `density`      | OPTIONAL | Density           | Space within or around component parts (e.g. `spacious`, `compact`).                                                                                                     |
 | `shape`        | OPTIONAL | Shape             | Relative to overall component shape (e.g. `uniform`).                                                                                                                    |
 | `scaleIndex`   | OPTIONAL | —                 | Numeric scale index appended at the end of the serialized name (e.g. `100`, `200`, `900`). Used by color palette, spacing, font-size, and motion duration tokens.        |
+| `from`         | OPTIONAL | —                 | Starting endpoint of a `space-between` measurement (e.g. `top`, `edge`, `text`). See [Space-between endpoints](#space-between-endpoints).                                |
+| `to`           | OPTIONAL | —                 | Ending endpoint of a `space-between` measurement (e.g. `text`, `visual`, `control`). See [Space-between endpoints](#space-between-endpoints).                            |
+
+#### Space-between endpoints
+
+A token whose `property` is **`space-between`** represents the spacing between two named endpoints (e.g. an edge and an anatomy part, or two anatomy parts) and **MUST** carry both the `from` and `to` fields; conversely, `from`/`to` **MUST NOT** appear unless `property` is `space-between` (rule `SPEC-047`).
+
+Each of `from`/`to` **MUST** be one of:
+
+* an edge position from `registry/positions.json` (e.g. `top`, `bottom`, `start`, `end`, `affixed`);
+* a generic anatomy term from `registry/anatomy-terms.json` (e.g. `text`, `icon`, `label`);
+* when `component` is present and declares an `anatomy` array, the `name` of a declared anatomy part on that component (e.g. `handle` on `accordion`).
+
+```json
+{ "name": { "component": "accordion", "property": "space-between", "from": "bottom", "to": "handle" },
+  "value": "8px" }
+```
+
+The `space-between` property term does not itself appear in the serialized legacy key; the key is reconstructed from the endpoints as `{component}-{from}-to-{to}` (e.g. `accordion-bottom-to-handle`).
 
 **Domain-scoped semantic fields** (only valid on the indicated token type):