@adobe/design-data-spec 2.5.0 → 2.7.0

package/conformance/README.md

@@ -67,6 +67,29 @@ The Rust SDK drives these fixtures in `sdk/core/src/lib.rs` (`diff_conformance`
 
 ***
 
+## Generation conformance fixtures
+
+Each **generation** case lives under `generation/<name>/` with:
+
+* `input/` — cascade-format `.tokens.json` files (array-of-objects format)
+* `expected/` — expected deterministic legacy set-format output (keyed-object format, one file per input file)
+
+These fixtures verify the field-mapping contract in [Evolution — Legacy format contract](../spec/evolution.md#legacy-format-contract): given the same cascade input, the output generator MUST produce byte-identical output on successive runs.
+
+| 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.               |
+
+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`.
+
+***
+
 ## Query conformance fixtures
 
 Each **query** case lives under `query/<name>/` with:

package/conformance/generation/README.md

@@ -0,0 +1,61 @@
+# Generation conformance fixtures
+
+Each case pairs a cascade-format input with the expected byte-identical legacy set-format output
+produced by the output generator. These fixtures verify the determinism contract in
+[Evolution — Legacy format contract](../../spec/evolution.md#legacy-format-contract).
+
+## Structure
+
+```
+generation/<case>/
+  input/    — cascade-format *.tokens.json files (array-of-objects)
+  expected/ — expected legacy output (keyed-object format, one file per input file)
+```
+
+## 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
+# Run all generation conformance tests:
+moon run sdk:test
+# or directly:
+cd sdk && cargo test generation_conformance
+```
+
+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` 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`).                                                                                                                                           |
+
+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
+pipeline (`sdk/core/src/cascade.rs`). A future spec update will add them to
+`spec/token-format.md` as normative cascade fields. Until then, implementors of the output
+generator MUST read the SDK implementation as the reference and treat these fixtures as
+illustrative of the expected grouping behavior.

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/flat-token/expected/tokens.json

@@ -0,0 +1,8 @@
+{
+  "black": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(0, 0, 0)",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+    "private": true
+  }
+}

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

@@ -0,0 +1,9 @@
+[
+  {
+    "name": { "property": "color", "colorFamily": "black" },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "rgb(0, 0, 0)",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+    "private": true
+  }
+]

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/mode-set-token/expected/tokens.json

@@ -0,0 +1,19 @@
+{
+  "blue-100": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
+    "uuid": "cccccccc-0001-4000-8000-000000000001",
+    "private": true,
+    "sets": {
+      "light": {
+        "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+        "value": "rgb(245, 249, 255)",
+        "uuid": "bbbbbbbb-0001-4000-8000-000000000001"
+      },
+      "dark": {
+        "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+        "value": "rgb(14, 23, 63)",
+        "uuid": "bbbbbbbb-0002-4000-8000-000000000002"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,30 @@
+[
+  {
+    "name": {
+      "property": "color",
+      "colorFamily": "blue",
+      "scaleIndex": 100,
+      "colorScheme": "light"
+    },
+    "$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",
+    "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
+    "private": true
+  },
+  {
+    "name": {
+      "property": "color",
+      "colorFamily": "blue",
+      "scaleIndex": 100,
+      "colorScheme": "dark"
+    },
+    "$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",
+    "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json",
+    "private": true
+  }
+]

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.5.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/agent-surface.md

@@ -1,7 +1,7 @@
 # Agent-readable surface
 
 **Spec version:** `1.0.0-draft` (see [Overview](index.md))\
-**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).
+**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` is Phase B scheduled (see [Authoring workflow — Scheduled promotion](authoring-workflow.md#scheduled-promotion)); `explain` is pending `get_guidance` wire-up.
 
 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.
 
@@ -35,9 +35,9 @@ The surface targets three consumer shapes:
 | `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                             |
+| `write_component`    | component object + optional rationale string           | updated dataset-root component file (RECOMMENDED, not NORMATIVE in v1; scheduled to become MUST — see [Scheduled promotion](authoring-workflow.md#scheduled-promotion))                   | `write::write_component` — Phase B scheduled; not yet implemented                                  |
 
-**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.
+**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. `write_token` and `write_component` are scheduled to become MUST when the Phase B foundation-corpus write target ships — see [Authoring workflow — Scheduled promotion](authoring-workflow.md#scheduled-promotion).
 
 **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).
 

package/spec/authoring-workflow.md

@@ -0,0 +1,279 @@
+# Authoring workflow
+
+<!-- Copyright 2026 Adobe. All rights reserved. -->
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))\
+**Status:** Draft — RFC [#625](https://github.com/adobe/spectrum-design-data/discussions/625) / Phase 4 (umbrella epic [#714](https://github.com/adobe/spectrum-design-data/discussions/714))
+
+This document defines the **authoring workflow** for spec-conformant design data: the normative contract governing how design tokens and related design-system artifacts are **created, edited, and maintained** over time.
+
+The source-of-truth direction is already normative in [Evolution](evolution.md#legacy-format-contract): the cascade format is the authoritative source; the legacy format is generated from it. This document extends that contract by specifying *where* the authoritative source lives, *what tooling* is expected to author it, and *what lifecycle operations* a conforming authoring surface MUST support across all data categories.
+
+## Goals
+
+1. **Single authoritative source.** All Spectrum design data is authored in `packages/design-data/` (or any spec-conformant dataset root) — not in legacy output directories. Generated outputs are derived artifacts.
+2. **Tool-mediated authoring.** Design data is authored via tooling (`design-data` CLI, `design-data-tui`, MCP authoring-session tools, future management app), not by direct JSON editing of production files. Tooling enforces schema validity, name-object decomposition, and UUID consistency.
+3. **Full lifecycle coverage.** Authoring surfaces cover the complete artifact lifecycle — create, edit, deprecate, rename, alias-rewire, and mode-set management — not just creation.
+4. **All data categories.** The authoring contract applies to every dataset category: tokens, components, fields, registry, mode sets, and guidelines.
+
+## Non-goals
+
+* Specifying the *output format* of generated artifacts. Legacy format mapping is defined in [Evolution — Legacy format contract](evolution.md#legacy-format-contract); DTCG and StyleDictionary outputs are deferred (RFC [#627](https://github.com/adobe/spectrum-design-data/discussions/627)).
+* Specifying the *consumer-facing API* of published packages (`@adobe/spectrum-tokens`, platform SDKs). Those are separately governed.
+* Specifying the *UI* of the authoring tools; this document defines behavioral contracts, not user-interface design.
+* Multi-user collaboration, permissions models, and Figma sync direction (open questions in RFC [#625](https://github.com/adobe/spectrum-design-data/discussions/625)).
+
+## Authoritative source
+
+Per [Evolution — Legacy format contract](evolution.md#legacy-format-contract), `packages/design-data/` (or the dataset root declared in the active `.design-data.toml`) is the **authoritative source** for all design data; output directories are derived artifacts. This document extends that contract with the following authoring-specific obligations:
+
+**NORMATIVE:** The dataset root MUST be the only location where design artifacts are authored. Output directories — including `packages/tokens/src/` and any platform-SDK directories — MUST NOT be independently edited.
+
+**NORMATIVE:** An authoring tool that writes design data MUST write to the dataset root's registered directories (`tokens/`, `components/`, `fields/`, `mode-sets/`, `registry/`, `guidelines/`) as defined in [Dataset layout](dataset-layout.md). Writing to legacy output directories (`foundation.json`, `platform.json`, `product.json`) constitutes a non-conforming write operation for Spectrum foundation corpus authoring.
+
+## Authoring tools
+
+The following tools constitute the normative authoring surface:
+
+| Tool                       | Form                                                         | Status                                                                              | Scope                                                                  |
+| -------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `design-data` CLI          | `design-data write-token` subcommand                         | Shipped — product-layer token creation                                              | Foundation corpus authoring: see [Gap — Phase B](#scheduled-promotion) |
+| `design-data-tui`          | interactive token naming + creation wizard                   | Shipped (RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973)) | Foundation corpus authoring: see [Gap — Phase B](#scheduled-promotion) |
+| MCP authoring session      | `start_authoring_session` / `authoring_session_commit` tools | Shipped (RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973)) | Foundation corpus authoring: see [Gap — Phase B](#scheduled-promotion) |
+| Design Data management app | future browser-based tool                                    | Not yet shipped                                                                     | Full CRUD across all categories                                        |
+
+**RECOMMENDED:** Authors SHOULD use the TUI or MCP authoring session rather than editing cascade JSON files directly. Tooling enforces UUID uniqueness, name-object field decomposition, and referential integrity that is difficult to maintain manually.
+
+### Scheduled promotion {#scheduled-promotion}
+
+The shipped CLI/TUI/MCP write path currently targets product-layer files (`foundation.json`, `platform.json`, `product.json`) — the distributed design system model introduced for product teams. Redirecting those tools to write to the foundation Spectrum corpus (`packages/design-data/tokens/*.tokens.json`) is Phase B work.
+
+**NORMATIVE:** Once the Phase B authoring engine ships, all authoring tools described above MUST write to the dataset root, not to legacy layer files. The `write_token` and `write_component` operations in [Agent-readable surface](agent-surface.md) are currently RECOMMENDED; they are **scheduled to become required** (MUST) when the Phase B foundation-corpus write target ships. The exact promotion version is tracked in RFC [#625](https://github.com/adobe/spectrum-design-data/discussions/625). This mirrors the SPEC-017 escalation precedent in [Token format](token-format.md#string-name-escape-hatch--spec-017-severity-schedule).
+
+## Lifecycle operations
+
+The following table defines the **target token-authoring contract**: the complete set of lifecycle operations a fully conforming authoring tool MUST support. Current shipped conformance covers **create only**; edit and remaining lifecycle operations are Phase B work (see [Per-category authoring contracts](#per-category-authoring-contracts) and [Scheduled promotion](#scheduled-promotion)). Operations for non-token categories are specified in the per-category authoring contracts.
+
+### Token lifecycle operations
+
+| Operation               | Description                                                                                                                      | Required fields                        |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| **create**              | Introduce a new token to the dataset. Assign a fresh UUID. Populate name object, value or alias `$ref`, `introduced` version.    | `uuid`, `name`, `value` or `$ref`      |
+| **edit**                | Update a token's value, alias target, rationale, or name-object fields. Preserve UUID.                                           | `uuid` (for identity lookup)           |
+| **deprecate**           | Set `deprecated` to the current spec version string; optionally set `replaced_by` and `deprecated_comment`.                      | `deprecated`, `uuid`                   |
+| **rename**              | Assign a new name object. Introduce a `replaced_by` pointer on the old token (or retire it). Preserve UUID on the renamed token. | Name-object fields, `replaced_by`      |
+| **alias-rewire**        | Change the `$ref` target UUID of an alias token. Verify the new target resolves in the cascade.                                  | `$ref`                                 |
+| **mode-set management** | Add, rename, or remove a mode-set entry. Update affected `mode` fields across tokens.                                            | Mode-set file + affected token entries |
+| **remove**              | Delete a token that has passed its migration window. Verify no `$ref` in the dataset resolves to the removed UUID.               | n/a                                    |
+
+**NORMATIVE:** A conforming authoring tool MUST assign UUIDs at creation time and MUST NOT change the UUID of an existing token during any edit, deprecate, rename, or alias-rewire operation. UUID stability is the identity contract that allows `$ref`, `replaced_by`, and external consumers to reference tokens across versions.
+
+**NORMATIVE:** A conforming authoring tool MUST write a valid `introduced` version on create, using the declared spec version of the active dataset (`specVersion` field in `dataset.json` or `.design-data.toml`).
+
+**NORMATIVE:** A conforming authoring tool MUST validate the written dataset against Layer 1 (JSON Schema) and Layer 2 (semantic rules) before persisting the write. A write operation that produces a Layer 1 error MUST be rejected.
+
+**RECOMMENDED:** A conforming authoring tool SHOULD capture an optional `rationale` argument at creation or edit time and record it in the token's inline `rationale` field. See [Product context](product-context.md#agent-capture-behavior) for the product-layer rationale convention.
+
+## Per-category authoring contracts
+
+The following per-category contracts specify what the authoring surface authors in each registered directory and which validation rules gate the output. Detailed authoring workflows per category are specified in separate subsections of this document as Phase A work progresses.
+
+| Category   | Directory     | Authoring status                                                                 | Validation gate                            |
+| ---------- | ------------- | -------------------------------------------------------------------------------- | ------------------------------------------ |
+| Tokens     | `tokens/`     | Shipped (create only; edit/lifecycle operations are Phase B)                     | SPEC-001–017, SPEC-041, SPEC-042, SPEC-043 |
+| Components | `components/` | Not yet shipped (`write_component` deferred — [Agent surface](agent-surface.md)) | SPEC-018–040                               |
+| Fields     | `fields/`     | Not yet shipped                                                                  | SPEC-042, SPEC-043                         |
+| Mode sets  | `mode-sets/`  | Not yet shipped                                                                  | SPEC-005, SPEC-008, SPEC-041               |
+| Guidelines | `guidelines/` | Not yet shipped                                                                  | SPEC-045, SPEC-046                         |
+| Registry   | `registry/`   | Not yet shipped (vocabulary is hand-maintained)                                  | SPEC-033, SPEC-034, SPEC-035               |
+
+### Token authoring contract
+
+Tokens are authored in `tokens/**/*.tokens.json`. Files may be nested arbitrarily within
+`tokens/`; the convention is one thematic `.tokens.json` file per token group (e.g.
+`color-palette.tokens.json`, `typography.tokens.json`).
+
+**Required at creation:** A conforming authoring tool MUST write:
+
+| Field             | Requirement            | Notes                                                                                                                                          |
+| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`            | REQUIRED               | Name object with at least `property`; MUST be decomposed via the `fields/` catalog — see [Taxonomy-aware authoring](#taxonomy-aware-authoring) |
+| `uuid`            | REQUIRED               | Fresh UUID v4 assigned by the tool; MUST NOT change for the lifetime of the token                                                              |
+| `value` or `$ref` | REQUIRED (exactly one) | Literal value or alias reference to another token's UUID                                                                                       |
+| `$schema`         | RECOMMENDED            | Token-type schema URI (e.g. `color.json`, `typography.json`) from `packages/design-data-spec/schemas/`                                         |
+| `introduced`      | RECOMMENDED            | Spec version string of the active dataset at creation time                                                                                     |
+
+**Validation gate:** SPEC-001–017 (name, value, lifecycle, tech-debt), SPEC-041 (mode-set
+conformance), SPEC-042 (field-scope), SPEC-043 (domain-required-fields).
+
+**Edit and lifecycle operations (Phase B):** Edit, deprecate, rename, alias-rewire, mode-set
+management, and remove are specified in [Lifecycle operations](#lifecycle-operations) and are
+implemented in Phase B.
+
+***
+
+### Component authoring contract
+
+Components are authored in `components/{name}.json`. Each file declares one component and MUST
+be named with the component's `name` field value (e.g. `button.json` for `name: "button"`).
+
+**Required at creation:**
+
+| Field                   | Requirement | Notes                                                                                                             |
+| ----------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
+| `$id`                   | REQUIRED    | URI: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/{name}.json`                        |
+| `name`                  | REQUIRED    | Kebab-case slug, unique within the dataset                                                                        |
+| `displayName`           | REQUIRED    | Human-readable name (e.g. `"Button"`)                                                                             |
+| `meta.category`         | REQUIRED    | One of: `actions`, `containers`, `data visualization`, `feedback`, `inputs`, `navigation`, `status`, `typography` |
+| `meta.documentationUrl` | REQUIRED    | URI to component documentation page                                                                               |
+
+**Recommended at creation:** `options` (component API), `anatomy` (anatomy parts array),
+`states` (state declarations array).
+
+**Validation gate:** SPEC-018–022 (anatomy/state/slot structure), SPEC-024–027 (tokenBindings,
+cross-references), SPEC-034 (category registry sync), SPEC-035 (anatomy-term registry sync),
+SPEC-038–040 (lifecycle, display name, schema).
+
+**Authoring status:** Not yet shipped — `write_component` is Phase B scheduled (see
+[Scheduled promotion](#scheduled-promotion)).
+
+***
+
+### Field authoring contract
+
+Name-object field declarations are authored in `fields/{fieldName}.json`. Each file declares
+one field. Field declarations extend the `fields/` catalog that the SDK and authoring tools
+load for classification decomposition.
+
+**Required at creation:**
+
+| Field                    | Requirement | Notes                                                              |
+| ------------------------ | ----------- | ------------------------------------------------------------------ |
+| `name`                   | REQUIRED    | Field key on the token name object (e.g. `colorFamily`, `variant`) |
+| `kind`                   | REQUIRED    | One of: `semantic`, `mode-set`, `numeric`                          |
+| `validation`             | REQUIRED    | One of: `strict` (error), `advisory` (warning), `none`             |
+| `serialization.position` | REQUIRED    | Integer; order in default serialized name string                   |
+
+**Recommended at creation:** `description`, `registry` (path to vocabulary file, or `null`),
+`scope` (domain restriction string, or `null` for universal fields).
+
+**Validation gate:** SPEC-042 (field-scope-violation), SPEC-043 (domain-required-fields).
+
+**Authoring status:** Not yet shipped — field declarations are currently hand-authored JSON.
+Phase C will add tooling for field creation.
+
+***
+
+### Mode-set authoring contract
+
+Mode sets are authored in `mode-sets/{name}.json`. Each file declares one mode set. Mode-set
+names MUST be stable identifiers — they are referenced by tokens' mode-keyed `sets` objects
+and by manifests; renaming a mode set is a breaking operation.
+
+**Required at creation:**
+
+| Field     | Requirement | Notes                                                                   |
+| --------- | ----------- | ----------------------------------------------------------------------- |
+| `name`    | REQUIRED    | Stable mode-set identifier (e.g. `colorScheme`, `scale`)                |
+| `modes`   | REQUIRED    | Non-empty array of unique mode-value strings (e.g. `["light", "dark"]`) |
+| `default` | REQUIRED    | A member of `modes`; MUST satisfy SPEC-005                              |
+
+**Recommended at creation:** `description`.
+
+**Validation gate:** SPEC-005 (default-mode-not-in-modes), SPEC-008 (base-variant-absence),
+SPEC-041 (platform mode-set conformance).
+
+**Authoring status:** Not yet shipped — mode sets are hand-authored JSON. Phase C will add
+tooling for mode-set management.
+
+***
+
+### Guideline authoring contract
+
+Guideline documents are authored in `guidelines/{name}.json`. Each file declares one guideline
+document. The filename MUST match the document's `name` field.
+
+**Required at creation:**
+
+| Field            | Requirement | Notes                                                                                 |
+| ---------------- | ----------- | ------------------------------------------------------------------------------------- |
+| `$id`            | REQUIRED    | URI: `https://opensource.adobe.com/spectrum-design-data/guidelines/{name}.json`       |
+| `name`           | REQUIRED    | Kebab-case slug matching filename                                                     |
+| `title`          | REQUIRED    | Human-readable page title                                                             |
+| `category`       | REQUIRED    | One of: `designing`, `fundamentals`, `developing`, `support`                          |
+| `documentBlocks` | REQUIRED    | Array with at least one block (SPEC-045 requires a `purpose` block SHOULD be present) |
+
+**Recommended at creation:** `sourceUrl`, `lastUpdated`, `tags`.
+
+**Validation gate:** SPEC-045 (guideline-purpose-block), SPEC-046 (guideline-related-references-resolve).
+
+**Authoring status:** Not yet shipped — guidelines are hand-authored JSON. Phase C will add
+tooling for guideline creation.
+
+***
+
+### Registry authoring contract
+
+Registry files in `registry/` declare vocabulary collections — the canonical term lists for
+anatomy, component categories, states, variants, and other classified fields. Registry files
+are currently **hand-maintained**: they are not yet authored via tooling.
+
+Each registry file is a JSON object with `type`, `description`, and a `values` array. Each
+value entry carries:
+
+| Field   | Requirement | Notes                                                                |
+| ------- | ----------- | -------------------------------------------------------------------- |
+| `id`    | REQUIRED    | Canonical value string (kebab-case); unique within the registry file |
+| `label` | REQUIRED    | Human-readable display name                                          |
+
+**Recommended per entry:** `description`, `usedIn` (declarative metadata — see
+[Registry spec](registry.md) for the field definition).
+
+**Validation gate:** SPEC-009 (name-field-enum-sync, advisory), SPEC-033 (cross-registry ID
+overlap is permitted), SPEC-034 (component-categories registry sync), SPEC-035
+(anatomy-part-names registry sync).
+
+**Authoring status:** Hand-maintained vocabulary — the `registry/` directory has an
+`AUTHORING.md` guide in `packages/design-data/AUTHORING.md`. Tooling-assisted registry
+authoring is Phase C scope; vocabulary additions today follow the manual process in that guide.
+
+***
+
+## Taxonomy-aware authoring
+
+**NORMATIVE:** A conforming authoring tool MUST decompose the token name into name-object fields using the `fields/` catalog rather than accepting a freeform `property` string. At minimum, authoring tools MUST offer structured field selection for all fields declared in `packages/design-data/fields/*.json` (or the equivalent dataset-relative path).
+
+**RECOMMENDED:** Authoring tools SHOULD validate candidate field values against the corresponding registry (where a `registry` path is declared on the field descriptor) and SHOULD warn the author when a value does not match any registered term.
+
+**RATIONALE:** Baking taxonomy concepts (size, variant, density, etc.) into the `property` slug reproduces technical debt that the structured name-object format was designed to eliminate. SPEC-043 (`domain-required-fields`) tracks this decomposition debt at advisory severity; it is scheduled to tighten — see [Taxonomy — SPEC-043 severity schedule](taxonomy.md#spec-043-severity-schedule) for the escalation schedule and promotion conditions.
+
+## Output generation
+
+**NORMATIVE:** After any authoring operation that modifies the `tokens/` directory, the legacy output (`packages/tokens/src/`) MUST be regenerated by running the output generator pipeline (`design-data:legacy-output` moon task). The regenerated output MUST pass the round-trip verification gates (`design-data:roundtrip-verify`, `tokens:verifyLegacyRoundtrip`, `tokens:verifyLegacyOutput`).
+
+**NORMATIVE:** The output generator MUST be deterministic: given the same input cascade files, it MUST produce byte-identical output on successive runs. See [Evolution — Legacy format contract](evolution.md#legacy-format-contract) for the field-mapping specification.
+
+**RECOMMENDED:** Authoring tooling SHOULD trigger output regeneration automatically after a successful write, so that the generated outputs stay in sync without a manual pipeline step.
+
+## Conformance
+
+**NORMATIVE:** An authoring tool implementation that claims conformance with this section MUST:
+
+1. Write all authored artifacts to the dataset root's registered directories (not to legacy output files).
+2. Assign UUIDs at creation time and preserve them across all subsequent operations.
+3. Write a valid `introduced` version on all created artifacts.
+4. Validate written artifacts against Layer 1 (JSON Schema) and Layer 2 (semantic rules) before persisting.
+5. Support structured name-object field decomposition using the `fields/` catalog for token creation.
+
+## References
+
+* [#625 — Token Authoring Workflow](https://github.com/adobe/spectrum-design-data/discussions/625) — RFC discussion
+* [#714 — Design Data Specification (umbrella)](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#973 — Interactive TUI & Token Authoring Wizard](https://github.com/adobe/spectrum-design-data/discussions/973) — shipped authoring tooling
+* [Dataset layout](dataset-layout.md) — normative directory structure and discovery algorithm
+* [Agent-readable surface](agent-surface.md) — write operations and transport contracts
+* [Evolution — Legacy format contract](evolution.md#legacy-format-contract) — cascade-is-source-of-truth policy
+* [Token format](token-format.md) — token name object, lifecycle fields
+* [Taxonomy](taxonomy.md) — name-object fields and vocabulary
+* [`sdk/core/src/write.rs`](../../../sdk/core/src/write.rs) — reference write implementation
+* [`sdk/core/src/legacy.rs`](../../../sdk/core/src/legacy.rs) — legacy output generator

package/spec/evolution.md

@@ -87,6 +87,23 @@ The `@adobe/spectrum-tokens` package continues to publish tokens in the **legacy
 | `plannedRemoval`                       | Not emitted                           |
 | `deprecated_comment`                   | `deprecated_comment` (passed through) |
 
+### Output-generator determinism
+
+**NORMATIVE:** The output generator MUST be deterministic: given the same cascade input files, it
+MUST produce byte-identical output on successive runs. Key rules:
+
+* Object keys in the generated legacy file MUST be sorted by token slug (lexicographic order).
+* The `sets` object within a set token MUST preserve the order modes appear in the source cascade
+  file (first occurrence of each mode name, in file order).
+* No ephemeral fields (timestamps, run IDs, etc.) MUST be written to the output.
+
+**Conformance fixtures:** The `conformance/generation/` corpus provides annotated input/expected
+pairs that an implementation MUST produce byte-identically to claim conformance with this
+determinism contract. See [Conformance fixtures](../conformance/README.md#generation-conformance-fixtures).
+
+The Rust SDK drives these fixtures via `design-data migrate legacy-output`
+(see [`sdk/core/src/legacy.rs`](../../../sdk/core/src/legacy.rs)).
+
 ### Coexistence during migration
 
 Both formats are published simultaneously. The cascade format is the source of truth; the legacy format is generated from it. This dual-format period continues until platform consumers have migrated to the cascade format or to platform SDKs that consume it.

package/spec/index.md

@@ -27,6 +27,7 @@ The specification defines:
 13. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
 14. **Dataset layout** — normative directory structure of a dataset (`tokens/`, `components/`, `fields/`, `mode-sets/`, `registry/`, `guidelines/`), discovery algorithm, and optional root descriptor ([Dataset layout](dataset-layout.md)).
 15. **Guideline documents** — standalone JSON files representing non-component design guidance pages (color, typography, motion, spacing, principles, etc.); each wraps page metadata and a `documentBlocks` body ([Guideline format](guideline-format.md)).
+16. **Authoring workflow** — normative contract for authoring design data via tooling: authoritative source location, lifecycle operations (create / edit / deprecate / rename / alias-rewire / mode-set management), taxonomy-aware decomposition requirement, and output-generation obligations ([Authoring workflow](authoring-workflow.md)).
 
 ## Conformance
 
@@ -81,6 +82,7 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 | [Evolution](evolution.md)                           | Deprecation lifecycle, migration windows, change classification.                                                                                      |
 | [Dataset layout](dataset-layout.md)                 | Normative dataset directory structure, discovery algorithm, optional root descriptor, and SPEC-044 structural pre-check.                              |
 | [Guideline format](guideline-format.md)             | Standalone guideline document shape: metadata fields, `category` enum, `related` cross-references, and required `documentBlocks` body (SPEC-045/046). |
+| [Authoring workflow](authoring-workflow.md)         | Normative authoring contract: authoritative source location, lifecycle operations, taxonomy-aware decomposition, and output-generation obligations.   |
 
 ## JSON Schema `$id` and versioning
 

package/spec/taxonomy.md

@@ -145,6 +145,27 @@ Motion tokens describe timing, easing, and animation role for UI animation. Thei
 
 Example: `motionRole=enter` + `easing=ease-out` → `enter-ease-out`. `motionRole=transition` + `scaleIndex=100` → `transition-100`.
 
+### SPEC-043 severity schedule {#spec-043-severity-schedule}
+
+Domain-specific tokens (color, typography, motion) that are missing required domain-identifying
+fields trigger SPEC-043 (`domain-required-fields`) at **`warning`** severity (see the individual
+domain sections above). Authors **SHOULD** treat SPEC-043 warnings as actionable decomposition
+debt — tracking which tokens are missing structured field annotations and working toward
+eliminating the gap incrementally.
+
+**NORMATIVE:** SPEC-043 **MUST** graduate from `warning` to `error` at spec version `2.0.0`,
+no earlier than two minor versions after Phase B (catalog-aware authoring — see [Authoring
+workflow — Taxonomy-aware authoring](authoring-workflow.md#taxonomy-aware-authoring)) ships.
+This conforms to the [evolution policy](evolution.md) — rule severity tightening is a major
+change. Tightening is conditional on Phase B shipping because authors need catalog-aware
+tooling before they can systematically resolve SPEC-043 warnings without hand-editing
+cascade JSON.
+
+Until Phase B ships and the foundation corpus reaches ≥ 90% SPEC-043 compliance per domain,
+SPEC-043 stays advisory. No SPEC-043 warning blocks a conforming dataset today. Adoption
+progress is tracked in RFC [#806](https://github.com/adobe/spectrum-design-data/discussions/806)
+and RFC [#625](https://github.com/adobe/spectrum-design-data/discussions/625).
+
 ### Alias / semantic token name objects
 
 Alias tokens (`$schema: …/alias.json`) MAY carry name objects using the same field vocabulary

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):