@adobe/design-data-spec 0.0.1 → 0.1.0

package/spec/diff.md

@@ -0,0 +1,97 @@
+# Semantic diff
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the **semantic diff model**: how two versions of a design data dataset are compared to produce a structured change report with awareness of renames, deprecations, and property-level changes.
+
+## Token identity
+
+A **token identity** determines whether a token in the old dataset and a token in the new dataset refer to the same logical token.
+
+**NORMATIVE:** Implementations **MUST** use the following matching rules, in order:
+
+1. **UUID match** — If a token in the old dataset and a token in the new dataset share the same `uuid` value, they are the **same token** regardless of name.
+2. **Name-object equivalence** — When a UUID match is not found for a token — because the old token, the new token, or both lack a `uuid`, or because no counterpart with the matching `uuid` exists in the other dataset — two tokens are the same if their `name` objects are deeply equal (all fields present with identical values).
+3. **Replacement link** — When passes 1 and 2 leave an old token unpaired and it carries a `replaced_by` field whose UUID matches an unpaired new token, the pair is established. This enables diff classification as **renamed** for tokens that were deprecated with a machine-readable replacement pointer.
+
+**NORMATIVE:** UUID matching **MUST** take precedence over name-object equivalence, which **MUST** take precedence over replacement link matching. A UUID match always identifies the token pair, even if name objects differ (which constitutes a rename).
+
+**RATIONALE:** UUID-based identity allows tokens to be renamed without breaking continuity tracking. Name-object equivalence is a fallback for legacy datasets that predate UUID adoption. Replacement link matching is a tertiary fallback for deprecated tokens that carry an explicit `replaced_by` UUID pointing to their successor.
+
+## Change taxonomy
+
+A semantic diff classifies every token into exactly one of six categories:
+
+| Category       | Definition                                                                                       |
+| -------------- | ------------------------------------------------------------------------------------------------ |
+| **renamed**    | Token exists in both datasets (matched by identity) but the name has changed.                    |
+| **deprecated** | Token exists only in the new dataset (unmatched) and carries a `deprecated` field.               |
+| **reverted**   | Token existed with `deprecated` in the old dataset and no longer carries it in the new dataset.  |
+| **added**      | Token exists only in the new dataset and is not renamed, deprecated, or pre-existing.            |
+| **deleted**    | Token exists only in the old dataset and is not the source of a rename.                          |
+| **updated**    | Token exists in both datasets (matched by identity) with the same name but changed properties.   |
+
+**NORMATIVE:** Every token that appears in the old dataset, the new dataset, or both **MUST** be classified into exactly one category. Categories are mutually exclusive.
+
+## Category partitioning
+
+**NORMATIVE:** Implementations **MUST** resolve categories in the following order to ensure mutual exclusivity:
+
+1. **Renamed** — Identify all identity-matched pairs where the name has changed. These tokens are removed from further classification as added or deleted.
+2. **Deprecated** — Among remaining unmatched new tokens, identify those carrying a `deprecated` field. These are removed from the "added" pool.
+3. **Reverted** — Among identity-matched pairs, identify tokens where `deprecated` was present in the old version and absent in the new. These are removed from the "updated" pool.
+4. **Added** — Remaining unmatched new tokens that are not renamed, deprecated, or pre-existing in the old dataset.
+5. **Deleted** — Remaining unmatched old tokens that are not the source of a rename.
+6. **Updated** — Remaining identity-matched pairs with unchanged names but differing properties.
+
+**RATIONALE:** This ordering mirrors the pipeline in existing tooling and ensures that a renamed token does not also appear as "added" + "deleted", a deprecated token does not appear as "added", and so forth. A matched token that newly gains a `deprecated` field is classified as **updated** — the deprecation surfaces as a property-level change in the updated sub-categories, not as a new-token deprecation.
+
+## Deprecation normalization
+
+**NORMATIVE:** When a token uses the legacy `sets` structure and **all** set entries carry `deprecated: true`, the token **MUST** be treated as deprecated at the token level for diff classification purposes, even if the top-level token object does not carry `deprecated`.
+
+**RATIONALE:** Set-level deprecation that covers all variants is semantically equivalent to token-level deprecation. Normalizing this prevents diff noise from implementation-level differences in where the `deprecated` flag is placed.
+
+## Property-level changes
+
+For tokens classified as **updated** (or **renamed** with additional property changes), a semantic diff **SHOULD** produce property-level change records.
+
+### Change record format
+
+Each property-level change is described by:
+
+| Field            | Type   | Description                                             |
+| ---------------- | ------ | ------------------------------------------------------- |
+| `path`           | string | Dot-separated path from the token root (e.g. `value`, `name.colorScheme`, `sets.light.value`). |
+| `new_value`      | any    | The value in the new dataset. Present for additions and updates. |
+| `original_value` | any    | The value in the old dataset. Present for deletions and updates. |
+
+### Property change sub-categories
+
+| Sub-category          | Condition                                         |
+| --------------------- | ------------------------------------------------- |
+| **added-properties**  | Property exists in new but not in old.             |
+| **deleted-properties**| Property exists in old but not in new.             |
+| **updated-properties**| Property exists in both but with different values. |
+
+**NORMATIVE:** Property comparison **MUST** be recursive: nested objects are traversed and changes reported at the leaf level with full dot-separated paths.
+
+**NORMATIVE:** Property comparison **MUST** use deep equality for values. Two values are equal if their JSON serializations are identical.
+
+## Output ordering
+
+**RECOMMENDED:** Diff output **SHOULD** be deterministic. Within each category, tokens **SHOULD** be sorted by their canonical name (or new name for renames) in lexicographic order.
+
+**RATIONALE:** Deterministic output makes diff reports suitable for snapshot testing and human review.
+
+## Cross-format compatibility
+
+**NORMATIVE:** A conforming diff engine **MUST** accept both legacy format (JSON object maps) and cascade format (JSON arrays with `.tokens.json` extension) as inputs for either the old or new dataset, including mixed-format comparisons (e.g. legacy old, cascade new).
+
+**RATIONALE:** The diff operates on the token graph abstraction, which normalizes both formats into the same `TokenRecord` structure. This enables diffing across format migrations without special-case handling.
+
+## References
+
+* [#623 — Token Lifecycle Metadata](https://github.com/adobe/spectrum-design-data/discussions/623)
+* [#714 — Design Data Specification](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#776 — Phase 3: Diff change taxonomy and token identity rules](https://github.com/adobe/spectrum-design-data/issues/776)

package/spec/dimensions.md

@@ -25,13 +25,21 @@ A **dimension declaration** is a JSON object describing one axis of variation. I
 
 ## Built-in dimensions
 
-These dimensions **SHOULD** be used consistently across Spectrum-compatible datasets:
+These dimensions are declared in the `dimensions/` catalog (see [Dimension catalog](#dimension-catalog)) and **SHOULD** be used consistently across Spectrum-compatible datasets:
 
-| `name`        | Typical `modes`                 | Notes                         |
-| ------------- | ------------------------------- | ----------------------------- |
-| `colorScheme` | `light`, `dark`, `wireframe`, … | Theme / appearance.           |
-| `scale`       | `medium`, `large`, …            | Density / t-shirt scale.      |
-| `contrast`    | `regular`, `high`, …            | Accessibility contrast level. |
+| `name`        | `modes`                      | `default` | Notes                                                                             |
+| ------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------- |
+| `colorScheme` | `light`, `dark`, `wireframe` | `light`   | Theme / appearance.                                                               |
+| `scale`       | `desktop`, `mobile`          | `desktop` | Density scale. Legacy names; desktop = medium, mobile = large in W3C terminology. |
+| `contrast`    | `regular`, `high`            | `regular` | Accessibility contrast level.                                                     |
+
+## Dimension catalog
+
+The Spectrum foundation publishes dimension declarations as JSON files under `packages/design-data-spec/dimensions/`. Each file conforms to [`dimension.schema.json`](../schemas/dimension.schema.json).
+
+**NORMATIVE:** Tooling (validators, resolution engine) **MUST** load dimension declarations from the dataset’s dimension catalog before performing specificity calculations or coverage validation.
+
+**RECOMMENDED:** The catalog directory is named `dimensions/` and is co-located with the dataset’s spec package or manifest.
 
 ## Optional dimensions
 
@@ -53,3 +61,4 @@ Additional dimensions (e.g. `language`, `motion`) **MAY** be declared in a datas
 
 * [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
 * [#714 — Design Data Specification](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#746 — Phase 2: Dimension declarations (machine-readable)](https://github.com/adobe/spectrum-design-data/issues/746)

package/spec/evolution.md

@@ -0,0 +1,98 @@
+# Evolution
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the **evolution policy** for the Design Data Specification: how the spec, schemas, and token data change over time, with a focus on the token deprecation lifecycle and backward compatibility.
+
+## Token deprecation lifecycle
+
+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. |
+
+### 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
+
+When a token carries `replaced_by`:
+
+- 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.
+
+## 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.
+
+**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).
+
+## Change classification
+
+The specification follows [Semantic Versioning](https://semver.org/) for its published artifacts (schemas, rule catalog, spec documents).
+
+### Minor changes (backward compatible)
+
+- 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)
+- Rule severity relaxed (error → warning)
+- New enum values added to registries
+
+### Major changes (breaking)
+
+- Tokens removed from the dataset
+- Required fields added to token schema
+- Existing fields removed or type-changed
+- Rule severity tightened (warning → error)
+- Enum values removed from registries
+- Constraint tightening (e.g. stricter value validation)
+
+### Patch changes (clarifications)
+
+- Typo fixes in spec prose
+- Clarifications to normative text that do not change conformance behavior
+- Test fixture additions or corrections
+
+## Legacy format contract
+
+The `@adobe/spectrum-tokens` package continues to publish tokens in the **legacy format** (JSON object maps with `color-set`, `scale-set`, etc.) for backward compatibility with existing consumers.
+
+**NORMATIVE:** The legacy format output **MUST** be generated from the cascade-format authoritative source. It is a **derived artifact**, not independently authored.
+
+### 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)|
+
+### Coexistence during migration
+
+Both formats are published simultaneously. The cascade format is the source of truth; the legacy format is generated from it. This dual-format period continues until platform consumers have migrated to the cascade format or to platform SDKs that consume it.
+
+## References
+
+* [#623 — Token Lifecycle Metadata](https://github.com/adobe/spectrum-design-data/discussions/623)
+* [#735 — RFC: Versioning and Evolution](https://github.com/adobe/spectrum-design-data/discussions/735)
+* [#736 — Define spec evolution policy and migration contract](https://github.com/adobe/spectrum-design-data/issues/736)

package/spec/index.md

@@ -10,14 +10,13 @@ This document is the top-level overview for the **Design Data Specification**: a
 The specification defines:
 
 1. **Token format** — structured token identity (`name`), literal `value` or alias `$ref`, and lifecycle metadata ([Token format](token-format.md)).
-2. **Cascade and resolution** — layered data (foundation, platform, product), specificity, and how a context picks a winning value ([Cascade](cascade.md)).
-3. **Dimensions** — declared modes, defaults, and coverage expectations ([Dimensions](dimensions.md)).
-4. **Platform manifest** — how a platform repo pins foundation data, filters tokens, and applies typed overrides ([Manifest](manifest.md)).
-
-Out of scope for this draft (tracked elsewhere):
-
-* Exact query syntax for `include` / `exclude` in manifests (placeholder fields only).
-* Full evolution, migration windows, and SDK version negotiation — see [discussion #735](https://github.com/adobe/spectrum-design-data/discussions/735).
+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)).
 
 ## Conformance
 
@@ -54,9 +53,13 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 | 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. |
 
 ## JSON Schema `$id` and versioning
 

package/spec/manifest.md

@@ -38,6 +38,21 @@ Each override object **MUST** include enough information to identify a target to
 
 **RECOMMENDED:** `extensions` follows the same structural conventions as foundation token files (tokens, dimensions) and **SHOULD** be validated with the same Layer 1 and Layer 2 rules.
 
+#### `extensions.formatting`
+
+A platform **MAY** declare formatting rules that control how structured name objects are serialized into flat token name strings for that platform. See [Taxonomy — Platform formatting configuration](taxonomy.md#platform-formatting-configuration) for motivation and examples.
+
+| Field           | Type            | Description                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `conceptOrder`  | array of string | Ordered list of name object field names for serialization. Each entry **MUST** be a declared field name from the design system's [field catalog](../fields/) (see [Token format — Name object](token-format.md#name-object)). Omitted fields are appended in the default order defined by each field declaration's `serialization.position` (see [Taxonomy — Default serialization](taxonomy.md#default-serialization-legacy-format)). |
+| `casing`        | string          | One of: `kebab-case`, `camelCase`, `PascalCase`, `SCREAMING_SNAKE_CASE`. Default: `kebab-case`.                                                                                                                                                                                                                                                                                                                                        |
+| `delimiter`     | string          | Character(s) separating concepts in the serialized string (e.g. `-`, `_`, `.`, `/`). Default: `-`.                                                                                                                                                                                                                                                                                                                                     |
+| `abbreviations` | object          | Map of full term → abbreviated form (e.g. `{ "background": "bg" }`). Abbreviations are applied after concept ordering and before casing.                                                                                                                                                                                                                                                                                               |
+
+**NORMATIVE:** When `extensions.formatting` is absent, the default serialization defined in [Taxonomy](taxonomy.md#default-serialization-legacy-format) is used.
+
+**NORMATIVE:** A formatter applying `extensions.formatting` **MUST** produce deterministic output — the same name object and formatting configuration **MUST** always yield the same string.
+
 ## Validation
 
 **NORMATIVE:** Manifests **MUST** pass Layer 1 JSON Schema validation.

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,173 @@
+# 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 categories do and will exist for other token types (e.g. color, typography). The taxonomy is built to scale as new concepts and terms are identified.
+
+## 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