@adobe/design-data-spec 3.1.0 → 3.2.0

package/spec/authoring-workflow.md

@@ -56,19 +56,19 @@ The following table defines the **target token-authoring contract**: the complet
 
 ### 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                                    |
+| Operation               | Description                                                                                                                               | Required fields                            |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| **create**              | Introduce a new token to the dataset. Assign a fresh UUID. Populate name object, value or alias `$ref`, `lifecycle.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 `lifecycle.deprecatedIn` to the current spec version string; optionally set `lifecycle.replacedBy` and `lifecycle.deprecatedComment`. | `lifecycle.deprecatedIn`, `uuid`           |
+| **rename**              | Assign a new name object. Introduce a `lifecycle.replacedBy` pointer on the old token (or retire it). Preserve UUID on the renamed token. | Name-object fields, `lifecycle.replacedBy` |
+| **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 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`, `lifecycle.replacedBy`, 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 write a valid `lifecycle.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.
 
@@ -95,13 +95,13 @@ Tokens are authored in `tokens/**/*.tokens.json`. Files may be nested arbitraril
 
 **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                                                                                     |
+| 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/`                                         |
+| `lifecycle.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).
@@ -261,7 +261,7 @@ authoring is Phase C scope; vocabulary additions today follow the manual process
 
 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.
+3. Write a valid `lifecycle.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.
 

package/spec/evolution.md

@@ -12,36 +12,36 @@ Tokens progress through the following lifecycle stages:
 introduced → active → deprecated → planned removal → removed
 ```
 
-| Stage               | Token state                                                                                                                                                                    |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Introduced**      | Token first appears in the dataset. `introduced` field records the version.                                                                                                    |
-| **Active**          | Token is current and recommended for use. No `deprecated` field.                                                                                                               |
-| **Deprecated**      | Token is no longer recommended. `deprecated` records the version. Consumers receive warnings. `replaced_by` points to the successor token(s) when a direct replacement exists. |
-| **Planned removal** | `plannedRemoval` records the target version. The token remains in the dataset but consumers should complete migration.                                                         |
-| **Removed**         | Token is deleted from the dataset. Consumers that still reference it will break.                                                                                               |
+| Stage               | Token state                                                                                                                                                                                         |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Introduced**      | Token first appears in the dataset. `lifecycle.introduced` field records the version.                                                                                                               |
+| **Active**          | Token is current and recommended for use. No `lifecycle` field (or no `deprecatedIn` within it).                                                                                                    |
+| **Deprecated**      | Token is no longer recommended. `lifecycle.deprecatedIn` records the version. Consumers receive warnings. `lifecycle.replacedBy` points to the successor token(s) when a direct replacement exists. |
+| **Planned removal** | `lifecycle.plannedRemoval` records the target version. The token remains in the dataset but consumers should complete migration.                                                                    |
+| **Removed**         | Token is deleted from the dataset. Consumers that still reference it will break.                                                                                                                    |
 
 ### Lifecycle fields
 
 See [Token format — Lifecycle and metadata](token-format.md#lifecycle-and-metadata) for the full field definitions and normative rules.
 
-### What `replaced_by` guarantees
+### What `lifecycle.replacedBy` guarantees
 
-When a token carries `replaced_by`:
+When a token carries `lifecycle.replacedBy`:
 
 * Each target UUID **MUST** resolve to an existing token in the dataset (rule `SPEC-010`).
 * The target token **SHOULD NOT** itself be deprecated. Chains of replacements (A replaced by B, B replaced by C) are discouraged; authors should point directly to the final replacement.
 * For a single UUID (1:1 replacement), consumers can mechanically rewrite references.
-* For an array of UUIDs (one-to-many split), the `deprecated_comment` **MUST** explain which replacement applies in which context.
+* For an array of UUIDs (one-to-many split), the `lifecycle.deprecatedComment` **MUST** explain which replacement applies in which context.
 
 ## Migration windows
 
-**NORMATIVE:** A deprecated token **MUST** remain in the published dataset for at least **two minor versions** after the version recorded in `deprecated` before it may be removed.
+**NORMATIVE:** A deprecated token **MUST** remain in the published dataset for at least **two minor versions** after the version recorded in `lifecycle.deprecatedIn` before it may be removed.
 
 **EXAMPLE:** A token deprecated in `3.2.0` may not be removed until `3.4.0` at the earliest. Removal in a major version (e.g. `4.0.0`) is always permitted regardless of how recently the token was deprecated.
 
 **RATIONALE:** Two minor versions gives consumers at least two release cycles to migrate. The major-version escape hatch allows accumulated deprecations to be cleaned up in a coordinated breaking release.
 
-If `plannedRemoval` is set, it overrides the default window — the token will be removed in the specified version (which must not precede the `deprecated` version).
+If `lifecycle.plannedRemoval` is set, it overrides the default window — the token will be removed in the specified version (which must not precede the `deprecatedIn` version).
 
 ## Change classification
 
@@ -52,7 +52,7 @@ The specification follows [Semantic Versioning](https://semver.org/) for its pub
 * New tokens added to the dataset
 * New optional fields added to token schema
 * New validation rules added to the rule catalog
-* Tokens deprecated (with `deprecated` field)
+* Tokens deprecated (with `lifecycle.deprecatedIn` field)
 * Rule severity relaxed (error → warning)
 * New enum values added to registries
 
@@ -79,13 +79,13 @@ The `@adobe/spectrum-tokens` package continues to publish tokens in the **legacy
 
 ### Lifecycle field mapping
 
-| Cascade format                         | Legacy format                         |
-| -------------------------------------- | ------------------------------------- |
-| `deprecated: "3.2.0"` (version string) | `deprecated: true` (boolean)          |
-| `replaced_by: "<uuid>"`                | `renamed: "<target-token-name>"`      |
-| `introduced`                           | Not emitted                           |
-| `plannedRemoval`                       | Not emitted                           |
-| `deprecated_comment`                   | `deprecated_comment` (passed through) |
+| Cascade format                                     | Legacy format                         |
+| -------------------------------------------------- | ------------------------------------- |
+| `lifecycle.deprecatedIn: "3.2.0"` (version string) | `deprecated: true` (boolean)          |
+| `lifecycle.replacedBy: "<uuid>"`                   | `renamed: "<target-token-name>"`      |
+| `lifecycle.introduced`                             | Not emitted                           |
+| `lifecycle.plannedRemoval`                         | Not emitted                           |
+| `lifecycle.deprecatedComment`                      | `deprecated_comment` (passed through) |
 
 ### Output-generator determinism
 

package/spec/index.md

@@ -28,6 +28,7 @@ The specification defines:
 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)).
+17. **Relationship format** — Component/Token Relationship (CTR): the anonymous-token entity unifying `tokenBindings` and token name-object scope fields, explicit relationship context, options validation, and interim legacy-compatibility fields ([Relationship format](relationship-format.md)).
 
 ## Conformance
 
@@ -83,6 +84,7 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 | [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.   |
+| [Relationship format](relationship-format.md)       | Component/Token Relationship (CTR): shape, explicit relationship context, options validation, and interim legacy-compatibility fields (SPEC-051–057). |
 
 ## JSON Schema `$id` and versioning
 

package/spec/relationship-format.md

@@ -0,0 +1,103 @@
+# Relationship format (Component/Token Relationship — CTR)
+
+## Overview
+
+A Component/Token Relationship (CTR) is an anonymous token that unifies the two mechanisms that today independently connect components and tokens:
+
+1. **`tokenBindings`** on a component declaration (component-declares-usage direction; see [component-format.md#token-bindings](component-format.md#token-bindings)).
+2. **Name-object scope fields** on a token (`component`, `variant`, `anatomy`, `state`, and arbitrary option keys; token-declares-scope direction, validated today by SPEC-018, SPEC-019, SPEC-020, SPEC-022, and SPEC-040).
+
+Rather than encoding component/part/option context inside a token's `name` string, a CTR carries its value (or `$ref` alias) alongside an explicit `scope` object naming the component, part, property, and option scope it belongs to, plus an optional `context` string carrying a human-readable label (the same role `tokenBindings[].context` plays today — e.g. mapping to a Figma Token Group label). CTR entries live under `relationships/*.json`, each file a JSON array of CTR objects (see [`relationship.schema.json`](../schemas/relationship.schema.json)).
+
+**NORMATIVE:** This document defines the CTR **foundation** — shape, validation rules, and interim legacy-compatibility fields. It does not migrate existing token or component data; `tokenBindings` and `componentBindings` remain in the schemas and are **NOT** removed by this chapter (deferred to a future migration phase).
+
+## Shape
+
+Each CTR is one of two subtypes, mirroring the token `oneOf` split (see [token-format.md](token-format.md)):
+
+* **Value-owning CTR** (`ctrWithValue`) — carries a literal `value`, like a token.
+* **Relationship-only CTR** (`ctrWithRef`) — carries a `$ref` alias to another token or CTR `uuid`, instead of an owned value.
+
+```json
+[
+  {
+    "scope": {
+      "component": "button",
+      "part": "label",
+      "property": "color",
+      "options": { "variant": "accent", "state": ["hover"] }
+    },
+    "context": "Label color, accent variant, hover",
+    "value": "#0060e0",
+    "uuid": "5b1a8e2e-9e2f-4b7a-9b2e-1a2b3c4d5e6f"
+  },
+  {
+    "scope": {
+      "component": "checkbox",
+      "property": "corner-radius"
+    },
+    "$ref": "5b1a8e2e-9e2f-4b7a-9b2e-1a2b3c4d5e6f"
+  }
+]
+```
+
+## Scope fields
+
+| Field             | Required | Type   | Description                                                                                                                                                                                                                                                                                                                                                                          |
+| ----------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `scope.component` | yes      | string | Component name (kebab-case). **MUST** match the `name` of a declared component in the dataset (rule SPEC-051, mirrors SPEC-018).                                                                                                                                                                                                                                                     |
+| `scope.part`      | no       | string | Anatomy part name. **MUST** match a declared anatomy part on the referenced component when present (rule SPEC-052, mirrors SPEC-020).                                                                                                                                                                                                                                                |
+| `scope.property`  | yes      | string | The stylistic attribute this relationship describes (e.g. `color`, `width`, `padding`).                                                                                                                                                                                                                                                                                              |
+| `scope.options`   | no       | object | Option-scoped narrowing. Each `options.<key>` value **MUST** validate against the referenced component's `options.<key>.values` (rule SPEC-053 — the headline CTR rule, stricter than the token-side SPEC-040 warning). `options.state` is the exception: an ordered array of atomic state ids, validated against the component's declared states (rule SPEC-054, mirrors SPEC-022). |
+| `context`         | no       | string | Human-readable label for how this CTR is used (mirrors `tokenBindings[].context`; maps to a Figma Token Group label). Purely descriptive — not validated.                                                                                                                                                                                                                            |
+
+Layer 1 (`relationship.schema.json`) only enforces shape: `scope.options` is an object, `scope.options.state` (when present) is an array of strings, and other option values are typically strings. It does **not** enforce which option values are valid — that is a Layer 2 (Rust, `sdk/core`) relational rule, because it requires cross-referencing the component catalog.
+
+## Value-owning vs. relationship-only
+
+| Field   | Subtype        | Description                                                                                                        |
+| ------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `value` | `ctrWithValue` | Literal value owned by this CTR, same value-type narrowing as a token's `value` (`$valueType`).                    |
+| `$ref`  | `ctrWithRef`   | Alias target. **MUST** resolve to a token or CTR `uuid` in the dataset (rule SPEC-055, mirrors SPEC-001/SPEC-027). |
+
+A CTR **MUST NOT** declare both `value` and `$ref` (enforced at Layer 1 via `not: { required: [...] }`, mirroring `token.schema.json`).
+
+## Identity
+
+| Field  | Required | Type          | Description                                                                                                                                                                  |
+| ------ | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `uuid` | no       | string (uuid) | **MUST** be globally unique across all relationship entries within the same cascade layer (rule SPEC-056, mirrors SPEC-004). Required for a CTR to be a valid `$ref` target. |
+
+## Legacy fields (interim)
+
+To keep `packages/tokens/src` (the legacy generated output, produced by `design-data migrate legacy-output` / `sdk/core/src/legacy.rs`) byte-identical while this foundation lands, a CTR that has a legacy counterpart carries transitional fields so the existing legacy generator can still reproduce that output:
+
+| Field       | Required | Type          | Description                                                                                                 |
+| ----------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------- |
+| `legacyKey` | no       | string        | Pins the exact flat key written to legacy output, mirroring the token name-object `legacyKey` escape hatch. |
+| `setUuid`   | no       | string (uuid) | Identifies the legacy color-set entry this CTR belongs to. Only meaningful alongside `legacyKey`.           |
+| `setSchema` | no       | string        | Names the legacy color-set schema this CTR's set entry conforms to. Only meaningful alongside `setUuid`.    |
+
+**NORMATIVE:** A CTR that has no legacy counterpart **SHOULD NOT** carry `legacyKey`/`setUuid`/`setSchema` — these fields exist solely to bridge the interim period before the legacy generator is retired or rewritten to consume CTRs directly. Rule SPEC-057 (`ctr-legacykey-present-if-legacy`, warning) is an advisory placeholder documenting this intent; it does not attempt to detect "should have a legacy counterpart" automatically, since that determination belongs to the (future) generator-side migration work, not this foundation.
+
+These fields are transitional. Once the legacy generator (or its replacement) reads CTRs directly, `legacyKey`/`setUuid`/`setSchema` are expected to be removed in a later spec version.
+
+## Relationship to `tokenBindings` / `componentBindings`
+
+CTRs are designed to eventually supersede both `tokenBindings` (on components, see [component-format.md#token-bindings](component-format.md#token-bindings)) and the token-side `componentBindings` reverse index (see [token-format.md#component-bindings](token-format.md#component-bindings)), by combining both directions — and the token name-object scope fields — into a single first-class relationship record with an explicit `context`.
+
+**NORMATIVE:** This chapter does **NOT** remove or deprecate `tokenBindings` or `componentBindings`. Both remain valid and required as-is. Migrating existing data onto CTRs, and any eventual removal of the superseded mechanisms, is out of scope for this foundation and deferred to a separate migration phase.
+
+## SPEC rules
+
+The following rules are added to the Layer 2 rule catalog (`rules/rules.yaml`) by this chapter. New CTR rules start at SPEC-051 to avoid collision with the existing catalog (SPEC-001–SPEC-050).
+
+| Rule ID  | Name                              | Severity | Assert                                                                                                                                                                                                                                             |
+| -------- | --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SPEC-051 | `ctr-component-exists`            | error    | CTR `scope.component` value **MUST** match the `name` of a declared component in the dataset.                                                                                                                                                      |
+| SPEC-052 | `ctr-part-valid`                  | error    | CTR `scope.part` value **MUST** match the `name` of a declared anatomy part on the referenced component (when present).                                                                                                                            |
+| SPEC-053 | `ctr-option-valid`                | error    | CTR `scope.options.<key>` value **MUST** match a value in the declared `options.<key>.values` list for the referenced component (when that list exists).                                                                                           |
+| SPEC-054 | `ctr-state-valid`                 | error    | CTR `scope.options.state` array elements **MUST** match the `name` of a declared state on the referenced component (when state declarations are present).                                                                                          |
+| SPEC-055 | `ctr-ref-resolves`                | error    | CTR `$ref` value **MUST** resolve to a declared token or relationship `uuid` in the dataset.                                                                                                                                                       |
+| SPEC-056 | `ctr-uuid-unique`                 | error    | CTR `uuid` values **MUST** be unique across all relationship entries within the same cascade layer.                                                                                                                                                |
+| SPEC-057 | `ctr-legacykey-present-if-legacy` | warning  | Advisory placeholder: a CTR that round-trips through the legacy generator **SHOULD** carry `legacyKey`. Generator-side "should have a legacy counterpart" detection is deferred; this rule documents intent rather than enforcing it structurally. |

package/spec/token-format.md

@@ -134,18 +134,25 @@ When **`value`** is present, it **MUST** conform to the declared value type for
 
 ### Lifecycle and metadata
 
-The following OPTIONAL fields implement the token lifecycle model described in [#623](https://github.com/adobe/spectrum-design-data/discussions/623) and the evolution policy in [Evolution](evolution.md). Inspired by Swift's `@available` attribute, Kotlin's `@Deprecated`, and OpenAPI 3.3's deprecation model.
-
-| Field                | Type                                    | Description                                                                                                                    |
-| -------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `uuid`               | string (UUID)                           | Stable unique id for rename tracking and diffs.                                                                                |
-| `introduced`         | string (version)                        | Spec version when the token was first added (e.g. `"1.0.0"`).                                                                  |
-| `deprecated`         | string (version)                        | Spec version when the token was deprecated (e.g. `"3.2.0"`). Truthy = deprecated.                                              |
-| `deprecated_comment` | string                                  | Human-readable deprecation explanation and migration guidance.                                                                 |
-| `replaced_by`        | string (UUID) or array of string (UUID) | UUID(s) of the replacement token(s). Single string for 1:1 replacement; array for one-to-many splits.                          |
-| `plannedRemoval`     | string (version)                        | Spec version when the token will be removed. If omitted, defaults to the next major version after `deprecated`.                |
-| `private`            | boolean                                 | Not part of public API surface.                                                                                                |
-| `rationale`          | string                                  | Why this token has its current value. Intended for product-layer authoring context; see [Product context](product-context.md). |
+Version lifecycle fields are grouped under an OPTIONAL nested `lifecycle` object, mirroring the
+component schema's `lifecycle` pattern (see [Component format](component-format.md)). This
+implements the token lifecycle model described in
+[#623](https://github.com/adobe/spectrum-design-data/discussions/623) and the evolution policy in
+[Evolution](evolution.md). Inspired by Swift's `@available` attribute, Kotlin's `@Deprecated`, and
+OpenAPI 3.3's deprecation model.
+
+| Field                         | Type                                    | Description                                                                                                                    |
+| ----------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `uuid`                        | string (UUID)                           | Stable unique id for rename tracking and diffs.                                                                                |
+| `lifecycle.introduced`        | string (version)                        | Spec version when the token was first added (e.g. `"1.0.0"`).                                                                  |
+| `lifecycle.deprecatedIn`      | string (version)                        | Spec version when the token was deprecated (e.g. `"3.2.0"`). Truthy = deprecated.                                              |
+| `lifecycle.deprecatedComment` | string                                  | Human-readable deprecation explanation and migration guidance.                                                                 |
+| `lifecycle.replacedBy`        | string (UUID) or array of string (UUID) | UUID(s) of the replacement token(s). Single string for 1:1 replacement; array for one-to-many splits.                          |
+| `lifecycle.plannedRemoval`    | string (version)                        | Spec version when the token will be removed. If omitted, defaults to the next major version after `deprecatedIn`.              |
+| `private`                     | boolean                                 | Not part of public API surface.                                                                                                |
+| `rationale`                   | string                                  | Why this token has its current value. Intended for product-layer authoring context; see [Product context](product-context.md). |
+
+`private` and `rationale` stay flat (not version-lifecycle concepts).
 
 #### Lifecycle example
 
@@ -154,38 +161,43 @@ The following OPTIONAL fields implement the token lifecycle model described in [
   "name": { "component": "button", "object": "background", "property": "color", "variant": "primary" },
   "value": "#0265dc",
   "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
-  "introduced": "1.0.0",
-  "deprecated": "3.2.0",
-  "deprecated_comment": "Use action-background-default instead.",
-  "replaced_by": "bbbbbbbb-0002-4000-8000-000000000001",
-  "plannedRemoval": "4.0.0"
+  "lifecycle": {
+    "introduced": "1.0.0",
+    "deprecatedIn": "3.2.0",
+    "deprecatedComment": "Use action-background-default instead.",
+    "replacedBy": "bbbbbbbb-0002-4000-8000-000000000001",
+    "plannedRemoval": "4.0.0"
+  }
 }
 ```
 
 #### Normative rules
 
-**NORMATIVE:** If `deprecated` is present, `deprecated_comment` **SHOULD** be present.
+**NORMATIVE:** If `lifecycle.deprecatedIn` is present, `lifecycle.deprecatedComment` **SHOULD** be present.
 
-**NORMATIVE:** If `replaced_by` is an array, `deprecated_comment` is **REQUIRED** — the comment **MUST** explain which replacement applies in which context.
+**NORMATIVE:** If `lifecycle.replacedBy` is an array, `lifecycle.deprecatedComment` is **REQUIRED** — the comment **MUST** explain which replacement applies in which context.
 
-**NORMATIVE:** If `replaced_by` is present, `deprecated` **MUST** be present.
+**NORMATIVE:** If `lifecycle.replacedBy` is present, `lifecycle.deprecatedIn` **MUST** be present.
 
-**NORMATIVE:** If `plannedRemoval` is present, `deprecated` **MUST** be present, and the `plannedRemoval` version **MUST NOT** precede the `deprecated` version.
+**NORMATIVE:** If `lifecycle.plannedRemoval` is present, `lifecycle.deprecatedIn` **MUST** be present, and the `plannedRemoval` version **MUST NOT** precede the `deprecatedIn` version.
 
-**NORMATIVE:** Each UUID in `replaced_by` **MUST** resolve to an existing token in the dataset (see rule `SPEC-010`).
+**NORMATIVE:** Each UUID in `lifecycle.replacedBy` **MUST** resolve to an existing token in the dataset (see rule `SPEC-010`).
 
 #### Legacy format mapping
 
 When generating legacy-format output from cascade tokens:
 
-* `deprecated: "3.2.0"` maps to `deprecated: true`
-* `replaced_by: "<uuid>"` maps to `renamed: "<target-token-name>"` (resolved via UUID lookup)
-* `introduced` and `plannedRemoval` have no legacy equivalent and are not emitted
+* `lifecycle.deprecatedIn: "3.2.0"` (or any truthy value) maps to flat `deprecated: true`
+* `lifecycle.deprecatedComment` maps to flat `deprecated_comment` (copied verbatim)
+* `lifecycle.replacedBy: "<uuid>"` maps to flat `renamed: "<target-token-name>"` (resolved via UUID lookup)
+* `lifecycle.plannedRemoval` and `lifecycle.introduced` have no legacy equivalent and are not emitted
+* The `lifecycle` wrapper itself is never emitted — legacy format has no nested wrapper
 
 When migrating legacy-format tokens to cascade:
 
-* `deprecated: true` maps to `deprecated: "unknown"` (authors should backfill the actual version)
-* `renamed: "<name>"` maps to `replaced_by: "<uuid>"` (resolved via name lookup across all files in the migrated input set). If the rename target is not found in the scanned corpus, the field is dropped — `replaced_by` must be set manually in that case
+* `deprecated: true` maps to `lifecycle.deprecatedIn: "unknown"` (authors should backfill the actual version)
+* `deprecated_comment` maps to `lifecycle.deprecatedComment` (copied verbatim)
+* `renamed: "<name>"` maps to `lifecycle.replacedBy: "<uuid>"` (resolved via name lookup across all files in the migrated input set). If the rename target is not found in the scanned corpus, the field is dropped — `lifecycle.replacedBy` must be set manually in that case
 
 ### `specVersion`