@adobe/design-data-spec 0.0.1 → 0.1.1

package/spec/query.md

@@ -0,0 +1,135 @@
+# Query notation
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the **query filter notation**: a concise syntax for selecting tokens from a dataset by matching against structured token fields.
+
+## Filter notation
+
+A **filter expression** is a string that describes a set of conditions a token must satisfy to be included in the result. The notation uses `key=value` pairs combined with logical operators.
+
+| Operator | Syntax           | Meaning                                                 |
+| -------- | ---------------- | ------------------------------------------------------- |
+| `=`      | `key=value`      | Field `key` equals `value`.                             |
+| `!=`     | `key!=value`     | Field `key` does not equal `value`.                     |
+| `,`      | `a=x,b=y`        | Logical AND — both conditions must match.               |
+| `\|`     | `a=x\|b=y`       | Logical OR — at least one condition must match.          |
+| `*`      | `key=patt*ern`   | Glob wildcard — `*` matches zero or more characters.    |
+
+## Supported keys
+
+**NORMATIVE:** Implementations **MUST** support the following keys:
+
+| Key              | Source                      | Description                                      |
+| ---------------- | --------------------------- | ------------------------------------------------ |
+| `property`       | `name.property`             | Token property identifier.                       |
+| `component`      | `name.component`            | Associated component name.                       |
+| `variant`        | `name.variant`              | Component variant.                               |
+| `state`          | `name.state`                | Component or interaction state.                  |
+| `colorScheme`    | `name.colorScheme`          | Color scheme dimension value.                    |
+| `scale`          | `name.scale`                | Scale dimension value.                           |
+| `contrast`       | `name.contrast`             | Contrast dimension value.                        |
+| `uuid`           | `uuid`                      | Token UUID (top-level field).                    |
+| `$schema`        | `$schema`                   | Token schema URL (top-level field).              |
+
+**NORMATIVE:** Implementations **MUST** reject filter expressions containing keys not listed above with a parse error. Future spec versions MAY add keys.
+
+**RATIONALE:** Restricting keys to a known set ensures that typos are caught early and that all implementations agree on which fields are queryable. This also enables implementations to build indexes for supported keys.
+
+## Formal grammar
+
+The following EBNF defines the filter expression syntax:
+
+```ebnf
+filter-expr = or-expr ;
+or-expr     = and-expr { "|" and-expr } ;
+and-expr    = condition { "," condition } ;
+condition   = key operator value ;
+key         = (letter | "$") { letter | digit | "$" | "_" } ;
+operator    = "=" | "!=" ;
+value       = { value-char } ;
+value-char  = letter | digit | "-" | "_" | "." | "/" | ":" | "*" ;
+letter      = "A"-"Z" | "a"-"z" ;
+digit       = "0"-"9" ;
+```
+
+**NORMATIVE:** Whitespace around operators and delimiters is **NOT** significant and **MUST** be trimmed by the parser.
+
+**NORMATIVE:** An empty filter expression **MUST** match all tokens (universal match).
+
+## Operator precedence
+
+**NORMATIVE:** The `,` (AND) operator binds more tightly than `|` (OR).
+
+The expression `a=x,b=y|c=z` is equivalent to `(a=x AND b=y) OR (c=z)`.
+
+**NORMATIVE:** Parentheses for grouping are **NOT** supported in `1.0.0-draft`. Implementations **MUST** reject parentheses with a parse error.
+
+**RATIONALE:** Avoiding parentheses keeps the notation simple and shell-friendly. Most practical queries are either pure AND or pure OR; mixed expressions with the defined precedence cover the remaining common cases.
+
+## Evaluation semantics
+
+**NORMATIVE:** A filter expression is evaluated independently against each token in the dataset. A token is included in the result if and only if the expression evaluates to `true` for that token.
+
+**NORMATIVE:** For equality (`=`), a condition matches when the token's field value equals the specified value. If the token does not have the field, the condition does **NOT** match.
+
+**NORMATIVE:** For negation (`!=`), a condition matches when the token's field value does not equal the specified value **OR** the field is absent. A missing field satisfies `!=`.
+
+**RATIONALE:** Negation matching absent fields follows the convention that "not equal to X" includes "does not exist" — the same semantics as label selectors in Kubernetes and CSS attribute selectors.
+
+## Glob matching
+
+**NORMATIVE:** The `*` character in a value is a **glob wildcard** matching zero or more characters.
+
+**NORMATIVE:** Glob matching is **case-sensitive**.
+
+**NORMATIVE:** Multiple `*` characters in a single value are permitted and each independently matches zero or more characters.
+
+**NORMATIVE:** To match a literal `*` character, there is no escape mechanism in `1.0.0-draft`. Future versions MAY define one.
+
+## Examples
+
+### Select all tokens for a specific component
+
+```
+component=button
+```
+
+Matches tokens whose `name.component` is `"button"`.
+
+### Select tokens matching multiple criteria
+
+```
+component=button,state=hover
+```
+
+Matches tokens where `name.component` is `"button"` **AND** `name.state` is `"hover"`.
+
+### Select tokens for either of two properties
+
+```
+property=background-color|property=border-color
+```
+
+Matches tokens whose `name.property` is `"background-color"` **OR** `"border-color"`.
+
+### Select color tokens using wildcard
+
+```
+property=color-*
+```
+
+Matches tokens whose `name.property` starts with `"color-"` (e.g. `color-default`, `color-hover`).
+
+### Exclude a specific color scheme
+
+```
+component=button,colorScheme!=light
+```
+
+Matches button tokens that are **not** in the `light` color scheme. Tokens without a `colorScheme` field also match (absent field satisfies `!=`).
+
+## References
+
+* [#714 — Design Data Specification](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#777 — Phase 3: Query notation definition](https://github.com/adobe/spectrum-design-data/issues/777)

package/spec/taxonomy.md

@@ -0,0 +1,189 @@
+# Taxonomy
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the **token taxonomy**: a hierarchical system of concept categories that classify design tokens, the **token term vocabulary** of allowed words within each category, and the **formatting style** rules that control serialization of structured token names into platform-consumable strings.
+
+## Motivation
+
+"Naming convention" is too broad a term when discussing malleability across platform teams. A token name like `accent-background-color-hover` embeds multiple independent decisions:
+
+1. **Which concepts** are represented and in what hierarchy (taxonomy).
+2. **Which words** describe each concept (vocabulary).
+3. **How the words are rendered** — casing, delimiters, abbreviations, concept order (formatting).
+
+Each layer has a different malleability profile: the taxonomy is shared across all platforms; the vocabulary is shared with platform-aware compromises; the formatting is platform-malleable.
+
+## Three layers of naming
+
+### Layer 1: Token taxonomy
+
+A **token taxonomy** is a hierarchical set of concept categories for classifying design ideas and use cases. It creates a clear, consistent, and predictable shared language across disciplines and teams.
+
+The taxonomy is **NORMATIVE** and **shared** — all platforms use the same concept categories in the same hierarchy. Changing the taxonomy changes the meaning of token names across the entire ecosystem.
+
+Taxonomies are **scoped to specific token types** for clarity. The semantic/layout taxonomy defined in this document is one such scope; additional taxonomies (e.g. for color tokens) will be defined in future spec versions.
+
+### Layer 2: Token term vocabulary
+
+The **token term vocabulary** is the set of specific words used to describe each conceptual option within the taxonomy. The vocabulary creates a shared language across disciplines and teams.
+
+The vocabulary is **NORMATIVE at the foundation level** — the foundation defines canonical terms. Platforms **MAY** declare vocabulary mappings (e.g. `hover` → `highlighted` for iOS) in their [manifest](manifest.md) for platform-specific consumption.
+
+### Layer 3: Formatting style
+
+**Formatting style** defines rules for altering the appearance of a token's name for platform-specific consumption and usability needs. This includes concept ordering, casing, delimiters, and abbreviations.
+
+Formatting is **platform-malleable** — each platform manifest **MAY** declare its own formatting rules. The foundation defines a default formatting style for legacy compatibility.
+
+**NORMATIVE:** The name object defined in [Token format](token-format.md) is unordered structured data. Concept ordering is purely a serialization concern and **MUST NOT** affect cascade resolution, specificity, or validation.
+
+## Principles
+
+The taxonomy is designed with three guiding principles:
+
+1. **Object-oriented** — Designers and developers think in terms of how they would construct components, rather than abstract semantic ideas.
+2. **Agnostic (with compromises)** — Platform-agnostic terms are used except when platforms have specific terms for the same concept. In those cases, the most common or clear term is used.
+3. **Verified** — Multiple existing components must be rebuildable using the taxonomy system, and consumers must find them reasonably understandable or learnable.
+
+## Semantic / layout token taxonomy
+
+Concept categories for name-object fields are declared in the design system's **field catalog** — a set of field declarations in the `fields/` directory, each conforming to [`field.schema.json`](../schemas/field.schema.json). Each declaration specifies the field name, vocabulary registry, validation severity, and default serialization position.
+
+**NORMATIVE:** The field catalog is the authoritative source for what fields exist on the name object. Tools, validators, and serializers **SHOULD** read the catalog rather than hardcoding field knowledge.
+
+The following concept categories are defined in Spectrum's foundation field catalog for semantic and layout tokens, ordered by default serialization position. This ordering is the **default serialization order** for legacy format output; it is not a conformance requirement for stored name objects.
+
+**NORMATIVE:** Each category listed below corresponds to an OPTIONAL field on the token [name object](token-format.md). Tokens **MAY** use any subset of these fields.
+
+| Category      | Name object field | Answers   | Description                                                                                                                                                                                                              |
+| ------------- | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Structure     | `structure`       | What?     | Individual objects or object categories that have shared styling. Distinctly different from "components" in that they represent structures and visual patterns that can or do occur across many varieties of components. |
+| Sub-structure | `substructure`    | What?     | A structure within an element that should only exist within the context of its parent structure.                                                                                                                         |
+| Component     | `component`       | What?     | Component scope when the token is component-scoped.                                                                                                                                                                      |
+| Anatomy       | `anatomy`         | What?     | A visible, named part of a component as defined by designers.                                                                                                                                                            |
+| Object        | `object`          | Where?    | The styling surface to which a visual property is applied (e.g. background, border, edge).                                                                                                                               |
+| Property      | `property`        | Where?    | The stylistic attribute being defined (e.g. color, width, padding, gap).                                                                                                                                                 |
+| Orientation   | `orientation`     | When/Why? | The direction or order of structures and elements within a component or pattern.                                                                                                                                         |
+| Position      | `position`        | When/Why? | The location of an object relative to another, with or without respect to directional order.                                                                                                                             |
+| Size          | `size`            | When/Why? | Relative terms used to create relationships and patterns of usage across multiple tokens and token types.                                                                                                                |
+| Density       | `density`         | When/Why? | Options that create more or less space within or around the parts of a component.                                                                                                                                        |
+| Shape         | `shape`           | When/Why? | Relative to the overall shape of a component (e.g. "uniform" creates a 1:1 padding ratio between horizontal and vertical padding).                                                                                       |
+
+Additional categories for variant and state are inherited from the existing name object:
+
+| Category | Name object field | Description                                                  |
+| -------- | ----------------- | ------------------------------------------------------------ |
+| Variant  | `variant`         | Variant within a component (e.g. accent, negative, primary). |
+| State    | `state`           | Interactive or semantic state (e.g. hover, focus, disabled). |
+
+**NOTE:** The categories above are filtered for semantic and layout token taxonomies. Additional taxonomies for other token types (color, typography, motion) will be defined in future spec versions — see the open follow-up RFC discussion [#806](https://github.com/adobe/spectrum-design-data/discussions/806) (Q3, taxonomy scoping). The taxonomy is built to scale as new concepts and terms are identified.
+
+### Structure vs. component — when does the line move?
+
+The `structure` and `component` fields both answer "What?" but apply at different scopes. A useful rule of thumb:
+
+* Use `component` when the token belongs to a specific component's surface (e.g. `button-background-color` — the background color of the Button component).
+* Use `structure` when the token belongs to a reusable visual pattern that recurs **across** components (e.g. `container-padding` — padding for any container-shaped surface, regardless of which component owns it).
+
+**Worked example — `card`:**
+
+* As a `structure`: when "card" describes a layout primitive used inside many components (e.g. `card-padding-medium` on a list item, a popover body, or a modal header), the token is structure-scoped.
+* As a `component`: when "card" describes the dedicated Card component's own surfaces (e.g. `card-background-color` on the Card root), the token is component-scoped.
+
+The same word can validly appear in both fields across the dataset; they are independent. Authors choose based on whether the token's *meaning* generalizes across many components (structure) or is specific to one component's identity (component).
+
+Source: Nate Baldwin, "Naming conventions & shared taxonomy" — Design Data & Platforms onsite, April 1, 2026.
+
+## Component anatomy vs. token objects
+
+Two concepts that are often conflated but serve different purposes:
+
+### Component anatomy
+
+**Component anatomy** refers to the visible, named parts of a component as defined by designers. These are the parts called out in component specification diagrams (e.g. icon, label, track, handle, hold icon).
+
+Component anatomy is declared per component in [component schemas](../../component-schemas/) and validated against the anatomy registry. A token referencing a component's anatomy part (e.g. `slider` + `handle`) can be validated as a legitimate combination.
+
+Anatomy parts fall into three tiers:
+
+| Tier               | Description                            | Examples                                                      |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------- |
+| Primitive          | Reusable across many components        | icon, label, track, handle, fill, divider, title, description |
+| Composite          | Another component used as a named part | checkbox, close button, popover, avatar                       |
+| Component-specific | Unique to one component                | loupe, gripper, opacity checkerboard                          |
+
+### Token objects (styling surfaces)
+
+**Token objects** (or styling surfaces) describe *where* a visual property is applied on a UI element. These are NOT anatomy — they are abstract styling targets that exist on any element regardless of its component type.
+
+| Object       | Description                                           |
+| ------------ | ----------------------------------------------------- |
+| `background` | Background surface or fill                            |
+| `border`     | Border or outline                                     |
+| `edge`       | Outer boundary of component (used in spacing tokens)  |
+| `visual`     | Visible graphic element area (may be inset from edge) |
+| `content`    | Main content area                                     |
+
+Token objects are stored in a separate registry from anatomy parts. Both may appear in the same token name — e.g. a token for the background color of a slider's handle would reference anatomy `handle` and object `background`.
+
+## Name object field categories
+
+Name object fields fall into two categories with different validation behavior:
+
+### Semantic fields
+
+Semantic fields describe identity, structure, and intent. They are used for querying and organization but do **not** participate in cascade resolution or specificity calculation.
+
+**NORMATIVE:** Semantic field values are validated against their declared vocabulary registry with the severity specified in the field declaration (typically **advisory** — warning, not error). Values not in the registry are permitted but flagged.
+
+Semantic fields are those declared with `kind: "semantic"` in the field catalog. In Spectrum's foundation catalog, these are: `structure`, `substructure`, `component`, `anatomy`, `object`, `property`, `variant`, `state`, `orientation`, `position`, `size`, `density`, `shape`.
+
+### Dimension fields
+
+Dimension fields represent axes of variation that drive the [cascade](cascade.md) resolution algorithm and [specificity](cascade.md#semantic-specificity) calculation.
+
+**NORMATIVE:** Dimension field values are validated against declared [dimension](dimensions.md) modes with **strict** severity (error). An invalid mode value would silently fail to match any context during cascade resolution.
+
+Dimension fields are those declared with `kind: "dimension"` in the field catalog, plus any additional dimension keys from the dataset's [dimension declarations](dimensions.md). In Spectrum's foundation catalog, the standard dimension fields are: `colorScheme`, `scale`, `contrast`.
+
+See [Dimensions](dimensions.md) for dimension declarations, modes, and defaults.
+
+## Default serialization (legacy format)
+
+The **default serialization** produces a kebab-case string from the name object by ordering fields according to their `serialization.position` values (ascending) as declared in the field catalog. Omitted fields are skipped.
+
+For Spectrum's foundation catalog, this produces the following concept order:
+
+```
+{variant}-{component}-{structure}-{substructure}-{anatomy}-{object}-{property}-{orientation}-{position}-{size}-{density}-{shape}-{state}
+```
+
+All fields are independent — `variant` and `component` **MAY** both appear in the same token name (e.g. a token with `component: "button"` and `variant: "accent"` serializes as `accent-button-...`).
+
+This ordering is preserved for backward compatibility with the current `@adobe/spectrum-tokens` package. It is a serialization convention, not a structural requirement.
+
+**NORMATIVE:** A conforming formatter **MUST** produce deterministic output for a given name object and formatting configuration. Two name objects that differ only in field ordering **MUST** produce identical serialized strings.
+
+## Platform formatting configuration
+
+A platform [manifest](manifest.md) **MAY** declare formatting rules in its [`extensions.formatting`](manifest.md#extensionsformatting) section to control concept ordering, casing, delimiters, and abbreviations. The normative contract for these fields is defined in [Manifest — `extensions.formatting`](manifest.md#extensionsformatting).
+
+When no platform formatting is declared, the default serialization above is used.
+
+## Scalability
+
+The taxonomy and terms are built to scale as new concepts and terms are identified:
+
+* New concept categories **MAY** be added by creating a new field declaration file in the field catalog — no spec version change is required for the mechanism itself.
+* New terms **MAY** be added to the vocabulary registry without spec version changes.
+* New token type taxonomies (beyond semantic/layout) **MAY** be defined in future spec versions.
+* Platform manifests **MAY** extend the vocabulary with platform-specific terms and formatting.
+
+## References
+
+* [#806 — Token Taxonomy, Vocabulary, and Formatting](https://github.com/adobe/spectrum-design-data/discussions/806)
+* [#661 — Spectrum Design System Glossary](https://github.com/adobe/spectrum-design-data/discussions/661)
+* [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
+* [Manifest — `extensions.formatting`](manifest.md#extensionsformatting) — normative contract for platform formatting rules
+* Nate Baldwin, "Naming conventions & shared taxonomy" — Design Data & Platforms onsite, April 1, 2026

package/spec/token-format.md

@@ -25,18 +25,40 @@ The **name object** identifies the token in a structured way. Implementations us
 
 **NORMATIVE fields** (all string unless noted):
 
+The set of available name-object fields is declared in the design system's **field catalog** (`fields/` directory). Each field declaration conforms to [`field.schema.json`](../schemas/field.schema.json) and specifies its kind (`semantic` or `dimension`), vocabulary registry, validation severity, and default serialization position. See [Taxonomy](taxonomy.md) for the full concept category hierarchy, component anatomy vs. token objects, and serialization rules.
+
+Fields are divided into **semantic fields** (identity, structure, intent) and **dimension fields** (axes of variation for cascade resolution). The tables below list Spectrum's foundation-standard fields as declared in the catalog.
+
+#### Semantic fields
+
+| Field          | Status   | Taxonomy category | Description                                                                                                                                                              |
+| -------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `property`     | REQUIRED | Property          | The stylistic attribute being defined (e.g. `color`, `width`, `padding`, `gap`).                                                                                         |
+| `component`    | OPTIONAL | Component         | Component name when the token is component-scoped.                                                                                                                       |
+| `structure`    | OPTIONAL | Structure         | Reusable visual pattern or object category (e.g. `base`, `container`, `list`, `accessory`). Distinct from `component`.                                                   |
+| `substructure` | OPTIONAL | Sub-structure     | A structure that only exists within its parent structure (e.g. `item` in `list-item`).                                                                                   |
+| `anatomy`      | OPTIONAL | Anatomy           | A visible, named part of a component as defined by designers (e.g. `handle`, `icon`, `label`). See [Taxonomy — Component anatomy](taxonomy.md#component-anatomy).        |
+| `object`       | OPTIONAL | Object            | Styling surface to which a visual property is applied (e.g. `background`, `border`, `edge`). See [Taxonomy — Token objects](taxonomy.md#token-objects-styling-surfaces). |
+| `variant`      | OPTIONAL | Variant           | Variant within a component (e.g. `accent`, `negative`, `primary`).                                                                                                       |
+| `state`        | OPTIONAL | State             | Interactive or semantic state (e.g. `hover`, `focus`, `disabled`).                                                                                                       |
+| `orientation`  | OPTIONAL | Orientation       | Direction or order of structures and elements (e.g. `vertical`, `horizontal`).                                                                                           |
+| `position`     | OPTIONAL | Position          | Location of an object relative to another (e.g. `affixed`).                                                                                                              |
+| `size`         | OPTIONAL | Size              | Relative t-shirt sizing for relationships across tokens (e.g. `small`, `medium`, `large`).                                                                               |
+| `density`      | OPTIONAL | Density           | Space within or around component parts (e.g. `spacious`, `compact`).                                                                                                     |
+| `shape`        | OPTIONAL | Shape             | Relative to overall component shape (e.g. `uniform`).                                                                                                                    |
+
+#### Dimension fields
+
 | Field           | Status   | Description                                                                                     |
 | --------------- | -------- | ----------------------------------------------------------------------------------------------- |
-| `property`      | REQUIRED | Stable property key (e.g. semantic role of the token).                                          |
-| `component`     | OPTIONAL | Component name when the token is component-scoped.                                              |
-| `variant`       | OPTIONAL | Variant within a component.                                                                     |
-| `state`         | OPTIONAL | Interactive or semantic state.                                                                  |
 | `colorScheme`   | OPTIONAL | Dimension: light / dark / wireframe / etc.                                                      |
-| `scale`         | OPTIONAL | Dimension: t-shirt size or density scale.                                                       |
-| `contrast`      | OPTIONAL | Dimension: contrast level.                                                                      |
+| `scale`         | OPTIONAL | Dimension: platform density scale (e.g. `desktop`, `mobile`). Distinct from semantic `size`.    |
+| `contrast`      | OPTIONAL | Dimension: contrast level (e.g. `regular`, `high`).                                             |
 | Additional keys | OPTIONAL | Other dimensions declared in the dataset’s dimension catalog (see [Dimensions](dimensions.md)). |
 
-**RECOMMENDED:** Name objects use a consistent key ordering in authored files for diffs; this is not a conformance requirement.
+**NORMATIVE:** Each field is validated according to the `validation` severity declared in its field declaration. Semantic fields typically use **advisory** severity (warning); dimension fields use **strict** severity (error). See [Taxonomy — Name object field categories](taxonomy.md#name-object-field-categories).
+
+**RECOMMENDED:** Name objects use a consistent key ordering in authored files for diffs; this is not a conformance requirement. Concept ordering for serialized names is defined in [Taxonomy — Default serialization](taxonomy.md#default-serialization-legacy-format).
 
 ### Alias (`$ref`)
 
@@ -48,33 +70,110 @@ When **`value`** is present, it **MUST** conform to the declared value type for
 
 ### Lifecycle and metadata
 
-The following OPTIONAL fields align with token lifecycle discussions (e.g. [#623](https://github.com/adobe/spectrum-design-data/discussions/623)):
+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.                                                                                      |
+
+#### Lifecycle example
+
+```json
+{
+  "name": { "component": "button", "object": "background", "property": "color", "variant": "primary" },
+  "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",
+  "plannedRemoval": "4.0.0"
+}
+```
+
+#### Normative rules
+
+**NORMATIVE:** If `deprecated` is present, `deprecated_comment` **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 `replaced_by` is present, `deprecated` **MUST** be present.
+
+**NORMATIVE:** If `plannedRemoval` is present, `deprecated` **MUST** be present, and the `plannedRemoval` version **MUST NOT** precede the `deprecated` version.
+
+**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:
 
-| Field                | Type          | Description                                     |
-| -------------------- | ------------- | ----------------------------------------------- |
-| `uuid`               | string (UUID) | Stable unique id for rename tracking and diffs. |
-| `introduced`         | string        | Version or date token was introduced.           |
-| `deprecated`         | boolean       | Marked deprecated.                              |
-| `deprecated_comment` | string        | Human-readable deprecation note.                |
-| `status`             | string        | e.g. `experimental`, `stable`.                  |
-| `renamed`            | string        | Previous name or id if renamed.                 |
-| `private`            | boolean       | Not part of public API surface.                 |
+* `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
 
-**NORMATIVE:** If `deprecated` is `true`, `deprecated_comment` **SHOULD** be present.
+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
 
 ### `specVersion`
 
 **RECOMMENDED:** Root token documents (when stored as standalone JSON files) include `specVersion` with const `1.0.0-draft` for self-identification. Embedded tokens inside larger files **MAY** omit it if the parent document carries version metadata.
 
+## Document shape
+
+Cascade-format tokens are stored in **JSON files** that conform to [`cascade-file.schema.json`](../schemas/cascade-file.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/cascade-file.schema.json`).
+
+**NORMATIVE:** A cascade file **MUST** be a JSON **array** of token objects. Each element **MUST** conform to [`token.schema.json`](../schemas/token.schema.json).
+
+**NORMATIVE:** The array is **ordered**. Document order is used for tie-breaking during cascade resolution (earlier element wins); see [Cascade — Semantic specificity](cascade.md#semantic-specificity).
+
+**RECOMMENDED:** A cascade file uses the `.tokens.json` extension to distinguish it from legacy set-format files.
+
+Example:
+
+```json
+[
+  { "name": { "object": "background", "property": "color" }, "value": "#f5f5f5", "uuid": "..." },
+  { "name": { "object": "background", "property": "color", "colorScheme": "dark" }, "value": "#1e1e1e", "uuid": "..." }
+]
+```
+
 ## Value types
 
 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).
 
 ## 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 [#723](https://github.com/adobe/spectrum-design-data/issues/723).
+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).
+
+## Relationship to RFC [#646](https://github.com/adobe/spectrum-design-data/issues/646) token shape
+
+[RFC #646](https://github.com/adobe/spectrum-design-data/discussions/646) proposed an analytical token shape during the design process. This spec defines the **canonical serialization format**. The two are related but not identical:
+
+| Aspect              | RFC [#646](https://github.com/adobe/spectrum-design-data/issues/646) shape | This spec                                                                  |
+| ------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Identity field      | `id`                                                                       | `uuid`                                                                     |
+| Name model          | `name.original` (string) + `name.structure` (nested object)                | Flat fields directly on `name` (`property`, `component`, `colorScheme`, …) |
+| Complexity tracking | `name.semanticComplexity` (stored on token)                                | Computed at validation time from dimension declarations                    |
+
+**NORMATIVE:** The flat `name` object defined in this spec is the authoritative serialization format. RFC [#646](https://github.com/adobe/spectrum-design-data/issues/646)'s `name.structure` / `name.original` shape is not a conformance target; it remains a useful reference for the analytical model that informed this design.
+
+RFC [#646](https://github.com/adobe/spectrum-design-data/issues/646) remains open as a historical reference. It is not superseded; the spec evolved the format during Phase 2 based on implementation experience.
 
 ## References
 
 * [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
 * [#623 — Token Lifecycle Metadata](https://github.com/adobe/spectrum-design-data/discussions/623)
+* [#756 — Phase 2: Cascade token file schema](https://github.com/adobe/spectrum-design-data/issues/756)
+* [#759 — Phase 2: Token shape reconciliation](https://github.com/adobe/spectrum-design-data/issues/759)