@adobe/design-data-spec 0.1.1 → 0.3.0

package/spec/index.md

@@ -11,12 +11,15 @@ The specification defines:
 
 1. **Token format** — structured token identity (`name`), literal `value` or alias `$ref`, and lifecycle metadata ([Token format](token-format.md)).
 2. **Taxonomy** — concept categories, token term vocabulary, formatting style, and the distinction between component anatomy and token objects ([Taxonomy](taxonomy.md)).
-3. **Cascade and resolution** — layered data (foundation, platform, product), specificity, and how a context picks a winning value ([Cascade](cascade.md)).
-4. **Dimensions** — declared modes, defaults, and coverage expectations ([Dimensions](dimensions.md)).
-5. **Platform manifest** — how a platform repo pins foundation data, filters tokens, and applies typed overrides ([Manifest](manifest.md)).
-6. **Semantic diff** — change taxonomy, token identity rules, and property-level change tracking for comparing dataset versions ([Diff](diff.md)).
-7. **Query notation** — filter syntax for selecting tokens by structured fields ([Query](query.md)).
-8. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
+3. **Component format** — component declaration shape: API options, named content slots, anatomy parts, state model, and cross-reference validation rules ([Component format](component-format.md)).
+   3a. **Anatomy format** — anatomy part declaration shape: field constraints, canonical anatomy vocabulary, and cross-reference rules for token `anatomy` field values ([Anatomy format](anatomy-format.md)).
+   3b. **State model** — state declaration shape: trigger semantics, precedence and resolution algorithm, canonical state vocabulary, and cross-reference rules for token `state` field values ([State model](state-model.md)).
+4. **Cascade and resolution** — layered data (foundation, platform, product), specificity, and how a context picks a winning value ([Cascade](cascade.md)).
+5. **Dimensions** — declared modes, defaults, and coverage expectations ([Dimensions](dimensions.md)).
+6. **Platform manifest** — how a platform repo pins foundation data, filters tokens, and applies typed overrides ([Manifest](manifest.md)).
+7. **Semantic diff** — change taxonomy, token identity rules, and property-level change tracking for comparing dataset versions ([Diff](diff.md)).
+8. **Query notation** — filter syntax for selecting tokens by structured fields ([Query](query.md)).
+9. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
 
 ## Conformance
 
@@ -50,16 +53,19 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 
 ## Normative references (sibling documents)
 
-| Document                        | Role                                                             |
-| ------------------------------- | ---------------------------------------------------------------- |
-| [Token format](token-format.md) | Token `name`, `value` / `$ref`, value types, lifecycle metadata. |
-| [Taxonomy](taxonomy.md)         | Concept categories, vocabulary, formatting, anatomy vs objects.  |
-| [Cascade](cascade.md)           | Layers, specificity, resolution algorithm.                       |
-| [Dimensions](dimensions.md)     | Dimension declarations, built-in dimensions, coverage.           |
-| [Manifest](manifest.md)         | Platform manifest fields and validation expectations.            |
-| [Diff](diff.md)                 | Semantic diff change taxonomy, token identity, property changes. |
-| [Query](query.md)               | Filter notation for selecting tokens by structured fields.       |
-| [Evolution](evolution.md)       | Deprecation lifecycle, migration windows, change classification. |
+| Document                                | Role                                                                                                        |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| [Token format](token-format.md)         | Token `name`, `value` / `$ref`, value types, lifecycle metadata.                                            |
+| [Taxonomy](taxonomy.md)                 | Concept categories, vocabulary, formatting, anatomy vs objects.                                             |
+| [Component format](component-format.md) | Component declaration: options, slots, anatomy (→ anatomy-format.md), states (→ state-model.md), lifecycle. |
+| [Anatomy format](anatomy-format.md)     | Anatomy part declarations: field constraints, canonical vocabulary, SPEC-020/SPEC-023/SPEC-024/SPEC-025.    |
+| [State model](state-model.md)           | State declarations: trigger semantics, precedence algorithm, canonical vocabulary, SPEC-022/SPEC-026.       |
+| [Cascade](cascade.md)                   | Layers, specificity, resolution algorithm.                                                                  |
+| [Dimensions](dimensions.md)             | Dimension declarations, built-in dimensions, coverage.                                                      |
+| [Manifest](manifest.md)                 | Platform manifest fields and validation expectations.                                                       |
+| [Diff](diff.md)                         | Semantic diff change taxonomy, token identity, property changes.                                            |
+| [Query](query.md)                       | Filter notation for selecting tokens by structured fields.                                                  |
+| [Evolution](evolution.md)               | Deprecation lifecycle, migration windows, change classification.                                            |
 
 ## JSON Schema `$id` and versioning
 
@@ -76,11 +82,11 @@ Packaged copies in this repository live under `packages/design-data-spec/schemas
 
 ## Relationship to existing Adobe packages
 
-| Package / area                          | Relationship                                                                                                                                                                                                                                                            |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@adobe/spectrum-tokens`                | **Current** token JSON under `packages/tokens/` is the **legacy** shape (e.g. `color-set`, `scale-set`). This spec defines the **target** format; backward-compat schemas and migration are Phase 1 ([#723](https://github.com/adobe/spectrum-design-data/issues/723)). |
-| `@adobe/design-system-registry`         | Registry enums and component metadata MAY be referenced by validation rules (e.g. component association); exact coupling is Layer 2.                                                                                                                                    |
-| `@adobe/spectrum-component-api-schemas` | Component schemas MAY be cross-checked by graph rules; not required for Layer 1 structural validation.                                                                                                                                                                  |
+| Package / area                          | Relationship                                                                                                                                                                                                                                                                 |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@adobe/spectrum-tokens`                | **Current** token JSON under `packages/tokens/` is the **legacy** shape (e.g. `color-set`, `scale-set`). This spec defines the **target** format; backward-compat schemas and migration are Phase 1 ([#723](https://github.com/adobe/spectrum-design-data/issues/723)).      |
+| `@adobe/design-system-registry`         | Registry enums and component metadata MAY be referenced by validation rules (e.g. component association); exact coupling is Layer 2.                                                                                                                                         |
+| `@adobe/spectrum-component-api-schemas` | Will become a thin adapter over component declarations in `packages/design-data-spec/components/` (Phase 6.5). Until migration, existing schemas remain authoritative. Cross-reference rules SPEC-018–SPEC-020 apply when component declarations are present in the dataset. |
 
 ## Umbrella discussions
 

package/spec/state-model.md

@@ -0,0 +1,245 @@
+# State model
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the normative **state declaration** object: the named conditions that affect a component's visual appearance or token resolution, declared in the `states` array of a component declaration. State declarations complete the machine-readable contract introduced by the component declaration (see [Component format — States stub](component-format.md#states-stub)) and enable cross-reference validation between tokens and component surfaces.
+
+Scoped under [RFC-A — Component Contract in Design Data Spec](https://github.com/adobe/spectrum-design-data/discussions/832). See also [Component format](component-format.md).
+
+## Introduction
+
+A **component state** is a named condition under which a component's visual presentation differs from its baseline. States drive token resolution: when a component is in a given state, the design system selects tokens scoped to that state name rather than (or layered on top of) the baseline tokens.
+
+State names appear in the `state` field of token name objects (see [Token format — Name object](token-format.md#name-object)). A token with `"state": "hover"` applies only when the component is in the `hover` state. For this cross-reference to be machine-enforceable, state declarations **MUST** be present on the component declaration.
+
+States fall into two trigger types:
+
+* **`prop`** — set by a persistent component API property (e.g. `isDisabled`, `isSelected`). The state remains active until the property value changes.
+* **`interaction`** — set by runtime user interaction (hover, focus, pressed, dragging). The state is transient and is cleared when the interaction ends.
+
+Full normative rules for the `states` array within a component declaration are in this document. The component declaration format is defined in [`spec/component-format.md`](component-format.md).
+
+## State declaration object
+
+A state declaration is a **JSON object** that appears as an element of a component declaration's `states` array. Each state declaration object **MUST** validate against the standalone schema [`state-declaration.schema.json`](../schemas/state-declaration.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/state-declaration.schema.json`).
+
+**NORMATIVE:** `states` **MUST** be a JSON array within the component declaration. Each element **MUST** be a state declaration object.
+
+### Fields
+
+| Field         | Type    | Required | Description                                                                                                                                |
+| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`        | string  | REQUIRED | Kebab-case state identifier. **MUST** match the pattern `^[a-z][a-z0-9-]*$`. Used as the value of the `state` field in token name objects. |
+| `description` | string  | OPTIONAL | Plain-text description of the state's semantics and the conditions under which it is active.                                               |
+| `trigger`     | string  | OPTIONAL | `"prop"` for persistent prop-driven states; `"interaction"` for runtime interaction states. See [Trigger semantics](#trigger-semantics).   |
+| `precedence`  | integer | OPTIONAL | Resolution precedence; higher value wins when multiple non-layered states are active simultaneously. Defaults to `0` if omitted.           |
+| `layered`     | boolean | OPTIONAL | When `true`, this state composes on top of the winning non-layered state rather than competing with it. Default: `false`.                  |
+
+**NORMATIVE:** No properties beyond those listed above are permitted in a state declaration object. Additional fields **MUST** cause a Layer 1 schema error.
+
+### `name`
+
+**NORMATIVE:** `name` **MUST** match the pattern `^[a-z][a-z0-9-]*$` — lower-case kebab-case, non-empty.
+
+**NORMATIVE:** `name` **MUST** be unique within the `states` array of a single component declaration. No two state declaration objects in the same component may share a `name` value.
+
+**NORMATIVE:** Token name-object `state` field values referencing a component **MUST** match the `name` of a declared state on that component, when state declarations are present (rule SPEC-022). An undeclared `state` value is a validation error.
+
+### `description`
+
+**OPTIONAL.** A plain-text description of the state's semantics and the conditions that activate it (e.g. `"Applied while the pointer is positioned over the component."`).
+
+**RECOMMENDED:** Custom state names (those outside the [canonical state vocabulary](#canonical-state-vocabulary)) **SHOULD** include a `description` to document intent (rule SPEC-026 fires a warning for undocumented custom names).
+
+### `trigger`
+
+**OPTIONAL.** One of two string values:
+
+* `"prop"` — the state is driven by a persistent component API property. The state is active as long as the property holds a truthy or specific value (e.g. `isDisabled: true`).
+* `"interaction"` — the state is driven by transient user interaction. The state activates when the interaction begins and clears when it ends.
+
+When `trigger` is omitted, the trigger type is unspecified. Validators **MAY** warn for state declarations without a `trigger` when the component has states listed in the canonical vocabulary with a known trigger type.
+
+### `precedence`
+
+**OPTIONAL.** A non-negative integer indicating this state's weight in the resolution algorithm. When multiple non-layered states are simultaneously active, the state with the highest `precedence` integer wins for token selection.
+
+When `precedence` is omitted, it is treated as `0`.
+
+**RECOMMENDED:** Components **SHOULD** declare explicit `precedence` values when two or more states could be active simultaneously, to avoid relying on declaration-order tie-breaking.
+
+### `layered`
+
+**OPTIONAL.** A boolean indicating whether this state composes on top of the winning non-layered state instead of competing with it. Default: `false`.
+
+When `layered: true`, the state does not participate in the non-layered precedence competition. Instead, after the winning non-layered state is determined, all active `layered: true` states are applied on top of it in order of their `precedence` values (higher precedence layered states apply last / outermost).
+
+Typical use: focus ring states (`focus`, `focus-visible`) that must be visible regardless of whether the component is also in a `hover` or `selected` state.
+
+## Trigger semantics
+
+### `prop` trigger
+
+A `prop` state is driven by a component API property. The state is persistent: it is active for the full duration that the property holds its activating value and is cleared only when the property changes.
+
+Examples:
+
+* `isDisabled: true` activates the `disabled` state.
+* `isSelected: true` activates the `selected` state.
+* `isIndeterminate: true` activates the `indeterminate` state.
+* `isReadOnly: true` activates the `read-only` state.
+
+`prop` states are typically mutually exclusive with each other in practice (a component is either disabled or selected, rarely both), but the spec permits multiple `prop` states to be simultaneously active; the precedence algorithm resolves which token set applies.
+
+### `interaction` trigger
+
+An `interaction` state is driven by transient user input. The state is active only while the interaction is occurring and is automatically cleared when the interaction ends.
+
+Examples:
+
+* `hover` — active while a pointer device is positioned over the component's interactive area.
+* `focus` — active while the component holds keyboard focus.
+* `focus-visible` — active when focus was received via keyboard navigation (not pointer).
+* `active` / `pressed` — active while a pointer button or key is held down.
+* `dragging` — active while a drag-and-drop gesture originating from the component is in progress.
+
+`interaction` states may overlay `prop` states (e.g. a disabled button may still receive a hover event on some platforms). When both are active, the precedence algorithm determines which token set wins, or, if the interaction state is `layered: true`, the interaction state's tokens are applied on top.
+
+## Precedence and resolution algorithm
+
+The following algorithm is **NORMATIVE** for conforming validators and renderers that implement state-aware token resolution.
+
+**Inputs:** A set of currently active state names for a given component instance.
+
+**Algorithm:**
+
+1. Partition the active states into two groups:
+   * **Non-layered states:** states with `layered: false` (or `layered` omitted).
+   * **Layered states:** states with `layered: true`.
+
+2. Among non-layered states, select the **winning state**:
+   * Compare `precedence` values. The state with the highest `precedence` integer wins.
+   * If `precedence` is omitted, treat it as `0`.
+   * If two non-layered states tie on `precedence`, the state that appears **earlier** in the component's `states` array wins. **MUST** be treated as a tie; implementations **SHOULD** emit a warning (see SPEC-006 for the analogous cascade tie rule).
+
+3. Resolve tokens for the winning non-layered state. If no non-layered state is active, resolve the `default` state (or baseline tokens when no `default` state is declared).
+
+4. For each active layered state, in ascending `precedence` order (lowest first, so the highest-precedence layered state is applied last and sits outermost):
+   * Apply the layered state's tokens on top of the tokens resolved in step 3. Tokens explicitly declared for the layered state override the corresponding tokens from the non-layered resolution.
+
+5. The resulting merged token set is the resolved appearance for the component instance in its current state combination.
+
+**Example:** A checkbox is simultaneously `selected` (precedence 80) and `hover` (precedence 50). `focus` (precedence 60, layered) is also active.
+
+* Non-layered active states: `selected` (80), `hover` (50). Winner: `selected`.
+* Layered active state: `focus`. Applied on top of `selected`.
+* Resolution: `selected` tokens, with `focus` tokens composited over them.
+
+## Canonical state vocabulary
+
+The following state names are defined by the cross-platform design audit and **SHOULD** be used in preference to custom names when their semantics match. Using canonical names enables cross-component tooling, documentation generation, and token audits.
+
+| Name            | Trigger     | Precedence | Layered | Semantics                                                                 |
+| --------------- | ----------- | ---------- | ------- | ------------------------------------------------------------------------- |
+| `default`       | —           | 0          | false   | No special state; baseline component appearance.                          |
+| `hover`         | interaction | 50         | false   | Pointer device is positioned over the component's interactive area.       |
+| `dragging`      | interaction | 55         | false   | A drag-and-drop gesture originating from this component is in progress.   |
+| `focus`         | interaction | 60         | true    | Component holds keyboard or programmatic focus.                           |
+| `focus-visible` | interaction | 65         | true    | Focus received via keyboard navigation; used for visible focus ring only. |
+| `active`        | interaction | 70         | false   | Pointer button or activation key is currently held down.                  |
+| `pressed`       | interaction | 70         | false   | Alias for `active`; prefer `active` for new declarations.                 |
+| `invalid`       | prop        | 75         | false   | Component value has failed validation.                                    |
+| `valid`         | prop        | 75         | false   | Component value has passed validation.                                    |
+| `selected`      | prop        | 80         | false   | Component is in a selected state (checkbox checked, tab active, etc.).    |
+| `indeterminate` | prop        | 85         | false   | Component has partial selection (tri-state checkbox mixed state).         |
+| `read-only`     | prop        | 90         | false   | Component value is visible but not editable by the user.                  |
+| `disabled`      | prop        | 100        | false   | Component is non-interactive; all user input is suppressed.               |
+
+Custom state names are permitted. When a custom name is used, the state declaration object **SHOULD** include a `description` field explaining its semantics (rule SPEC-026).
+
+**NORMATIVE:** The values in the canonical vocabulary table (trigger type, precedence, layered) are **RECOMMENDED defaults**. A component declaration MAY override any of these values for a canonical state name by explicitly declaring a different value in the state declaration object. When overriding a canonical default, the `description` **SHOULD** explain the deviation.
+
+## Cross-reference with token name objects
+
+Token name objects use a `state` field to scope a token to a specific component state. The `state` field value must correspond to a state declared in the component's `states` array.
+
+**NORMATIVE:** A token name-object `state` field value **MUST** match the `name` of a declared state on the component identified by the token's `component` field, when state declarations are present on that component (rule SPEC-022). A `state` value that does not match any declared state name is a validation error.
+
+See [Token format — Name object](token-format.md#name-object) for the full name object field catalog.
+
+**NORMATIVE:** The `state` field in a token name object **MUST NOT** be present unless the token's `component` field is also present. States are always scoped to a component.
+
+```json
+{
+  "name": {
+    "component": "checkbox",
+    "anatomy": "checkmark",
+    "property": "color",
+    "state": "selected"
+  },
+  "value": "#0265dc"
+}
+```
+
+## SPEC rules
+
+The following rules in the Layer 2 rule catalog (`rules/rules.yaml`) apply to state declarations. SPEC-022 was introduced in Phase 6.1 (component-format); SPEC-026 is introduced by this chapter.
+
+| Rule ID  | Name                           | Severity | Assert                                                                                                                                              |
+| -------- | ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SPEC-022 | `component-state-valid`        | error    | Token `state` field value **MUST** match the `name` of a declared state on the referenced component (when state declarations are present).          |
+| SPEC-026 | `state-custom-name-documented` | warning  | State declarations with a `name` outside the canonical state vocabulary **SHOULD** include a `description` field documenting the state's semantics. |
+
+## Full example
+
+A complete `states` array for a checkbox component, demonstrating prop states (`selected`, `indeterminate`, `disabled`), interaction states (`hover`, `focus` with `layered: true`, `pressed`), and explicit precedence values:
+
+```json
+"states": [
+  {
+    "name": "default",
+    "description": "Baseline unchecked checkbox appearance.",
+    "trigger": "prop",
+    "precedence": 0
+  },
+  {
+    "name": "hover",
+    "description": "Applied while a pointer device is positioned over the checkbox.",
+    "trigger": "interaction",
+    "precedence": 50
+  },
+  {
+    "name": "focus",
+    "description": "Applied while the checkbox holds keyboard or programmatic focus. Composes on top of the active non-layered state.",
+    "trigger": "interaction",
+    "precedence": 60,
+    "layered": true
+  },
+  {
+    "name": "pressed",
+    "description": "Applied while the pointer button or Space key is held down during activation.",
+    "trigger": "interaction",
+    "precedence": 70
+  },
+  {
+    "name": "selected",
+    "description": "Applied when isSelected is true (checkbox checked).",
+    "trigger": "prop",
+    "precedence": 80
+  },
+  {
+    "name": "indeterminate",
+    "description": "Applied when isIndeterminate is true (tri-state mixed selection).",
+    "trigger": "prop",
+    "precedence": 85
+  },
+  {
+    "name": "disabled",
+    "description": "Applied when isDisabled is true. Suppresses all user input.",
+    "trigger": "prop",
+    "precedence": 100
+  }
+]
+```
+
+In this example, if the checkbox is simultaneously `selected` (80) and `hover` (50) with `focus` (60, layered) active, the resolution is: `selected` wins the non-layered competition; `focus` tokens are then applied on top of the `selected` tokens.

package/spec/token-format.md

@@ -12,13 +12,33 @@ A **token** is a JSON object that satisfies the Layer 1 schema [`token.schema.js
 
 A token **MUST** contain:
 
-1. **`name`** — a JSON object (the **name object**) as defined below.
+1. **`name`** — a JSON object (the **name object**) as defined below, or a non-empty plain string (escape hatch — see [String-name escape hatch](#string-name-escape-hatch)).
 2. Exactly one of:
    * **`value`** — a literal token value (type depends on value-type schema), or
    * **`$ref`** — a string reference to another token (alias).
 
 A token **MUST NOT** include both `value` and `$ref`.
 
+### String-name escape hatch
+
+A token's `name` field **MAY** be a non-empty plain string instead of a name object when the token's identity cannot be expressed using the structured taxonomy fields.
+
+```json
+{
+  "name": "focus-ring-color-key-focus",
+  "value": "#0265dc",
+  "uuid": "aaaaaaaa-0011-4000-8000-000000000001"
+}
+```
+
+**NORMATIVE:** String-named tokens are schema-valid. Validators **MUST** accept them without a structural error.
+
+**NORMATIVE:** String-named tokens **MUST** trigger rule SPEC-017 (severity: `warning`, category: `tech-debt`). The warning surfaces the token as tracked debt requiring future remediation.
+
+**NORMATIVE:** String-named tokens **MUST NOT** participate in name-object cascade dimension matching, specificity calculation, or registry vocabulary checks (SPEC-009 does not apply).
+
+**RECOMMENDED:** Authors **SHOULD** treat string names as a temporary escape hatch and track a remediation plan. Each string-named token **SHOULD** eventually be given a structured name object, at which point SPEC-017 no longer fires.
+
 ### Name object
 
 The **name object** identifies the token in a structured way. Implementations use it for cascade matching, specificity, and tooling.
@@ -72,16 +92,15 @@ When **`value`** is present, it **MUST** conform to the declared value type for
 
 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"`).                                                        |
-| `lastModified`       | string (version)                        | Spec version when the token's value or metadata last changed (e.g. `"2.1.0"`). Updated on any non-formatting change. |
-| `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.                                                                                      |
+| 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.                                                                                 |
 
 #### Lifecycle example
 
@@ -91,7 +110,6 @@ The following OPTIONAL fields implement the token lifecycle model described in [
   "value": "#0265dc",
   "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
   "introduced": "1.0.0",
-  "lastModified": "3.2.0",
   "deprecated": "3.2.0",
   "deprecated_comment": "Use action-background-default instead.",
   "replaced_by": "bbbbbbbb-0002-4000-8000-000000000001",
@@ -111,15 +129,13 @@ The following OPTIONAL fields implement the token lifecycle model described in [
 
 **NORMATIVE:** Each UUID in `replaced_by` **MUST** resolve to an existing token in the dataset (see rule `SPEC-010`).
 
-**NORMATIVE:** If `lastModified` is present, its version **MUST NOT** precede `introduced` (see rule `SPEC-014`). Authors **SHOULD** bump `lastModified` whenever a token's `value`, alias `$ref`, or non-formatting metadata changes; pure formatting or comment-only edits do not require a bump.
-
 #### 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`, `lastModified`, and `plannedRemoval` have no legacy equivalent and are not emitted
+* `introduced` and `plannedRemoval` have no legacy equivalent and are not emitted
 
 When migrating legacy-format tokens to cascade:
 
@@ -153,6 +169,55 @@ Example:
 
 Individual types (color, dimension, opacity, etc.) **MUST** be defined as JSON Schemas under `schemas/value-types/` and **MUST** use `$id` under the same `v0` base path as [Overview — JSON Schema `$id`](index.md).
 
+### Value-type declaration (`$valueType`)
+
+A token **MAY** include a `$valueType` field: a URI reference pointing to a value-type schema under `schemas/value-types/`.
+
+```json
+{
+  "name": { "property": "typography-scale", "scale": "desktop" },
+  "$valueType": "value-types/typography-scale.schema.json",
+  "value": { "fontSize": "14px", "lineHeight": "18px" },
+  "uuid": "377145e8-079b-43fd-b522-8f16b1b8f883"
+}
+```
+
+**NORMATIVE:** When `$valueType` is present on a token with a literal `value`, the value **MUST** validate against the referenced schema (rule SPEC-016).
+
+**NORMATIVE:** When `$valueType` is present on an alias token (`$ref`), the alias resolution chain **MUST** terminate at a token whose value validates against the same value-type schema (rule SPEC-002, extended).
+
+**RECOMMENDED:** All tokens with composite values (see below) **SHOULD** include `$valueType` to enable tooling discovery and validation. Tokens without `$valueType` remain valid under the permissive `anyOf` union in `token.schema.json`.
+
+### Composite value types
+
+A **composite value type** is a value-type schema whose root type is `object` or `array`. Composite values bundle multiple sub-values into a single token.
+
+**NORMATIVE:** Composite value types **MUST** be defined as JSON Schemas under `schemas/value-types/` following the same conventions as primitive value types.
+
+**NORMATIVE:** A composite token participates in cascade resolution as an **atomic unit**. Sub-values within a composite **MUST NOT** independently match, override, or participate in specificity calculation.
+
+### Inline alias references
+
+Within a composite value, a string sub-value **MAY** be an **inline alias**: a reference to another token that is resolved to produce the final sub-value.
+
+```json
+{
+  "name": { "property": "component-m-regular" },
+  "$valueType": "value-types/typography.schema.json",
+  "value": {
+    "fontFamily": "{sans-serif-font-family}",
+    "fontSize": "{font-size-100}",
+    "fontWeight": "{regular-font-weight}",
+    "letterSpacing": "{letter-spacing}",
+    "lineHeight": "{line-height-font-size-100}"
+  }
+}
+```
+
+**NORMATIVE:** In legacy format, inline aliases use the syntax `{token-name}` (curly-brace-wrapped token property name). In cascade format, the inline alias syntax is `{token-name}` for backward compatibility; UUID-based inline aliases are reserved for a future spec version.
+
+**NORMATIVE:** Inline aliases within composite values are subject to alias resolution rules. Validators **MUST** resolve inline aliases and report errors for missing targets (SPEC-014), type mismatches (SPEC-015), and circular references (SPEC-003, extended).
+
 ## Relationship to legacy Spectrum tokens
 
 The current `@adobe/spectrum-tokens` JSON uses **sets** (`color-set`, `scale-set`, …). This specification describes the **target** per-token model. Mapping from legacy to this format is out of scope for this document; see [#743](https://github.com/adobe/spectrum-design-data/issues/743).

package/src/canonical.js

@@ -0,0 +1,61 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+// Canonical vocabulary sets derived from spec chapters.
+// Sources: spec/component-format.md, spec/anatomy-format.md, spec/state-model.md
+
+export const CANONICAL_SLOTS = new Set([
+  "default",
+  "icon",
+  "label",
+  "help-text",
+  "negative-help-text",
+  "action",
+  "heading",
+  "description",
+  "hero",
+  "footer",
+  "tooltip",
+]);
+
+export const CANONICAL_ANATOMY_PARTS = new Set([
+  "body",
+  "checkmark",
+  "disclosure-triangle",
+  "field",
+  "handle",
+  "header",
+  "icon",
+  "label",
+  "picker",
+  "progress-bar",
+  "swatch",
+  "thumbnail",
+  "track",
+  "value",
+]);
+
+export const CANONICAL_STATES = new Set([
+  "default",
+  "hover",
+  "focus",
+  "focus-visible",
+  "active",
+  "pressed",
+  "selected",
+  "indeterminate",
+  "disabled",
+  "read-only",
+  "invalid",
+  "valid",
+  "dragging",
+]);