@adobe/design-data-spec 0.8.0 → 0.10.0

package/spec/index.md

@@ -3,7 +3,7 @@
 **Version:** `1.0.0-draft`\
 **Status:** Draft — normative text and schemas may change before `1.0.0`.
 
-This document is the top-level overview for the **Design Data Specification**: a machine-readable model for Spectrum design tokens, dimensions, platform manifests, and validation.
+This document is the top-level overview for the **Design Data Specification**: a machine-readable model for Spectrum design tokens, mode sets, platform manifests, and validation.
 
 ## Scope
 
@@ -12,14 +12,18 @@ 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. **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)).
+   * **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)).
+   * **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)).
+5. **Mode Sets** — declared modes, defaults, and coverage expectations ([Mode Sets](mode-sets.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)).
+9. **Accessibility** — component accessibility vocabulary: semantic role, interaction and keyboard intents, focus behavior, WCAG criteria, and state-level AT fields ([Accessibility](accessibility.md)).
+   * **Accessibility adapters** — informative platform adapter contracts: Web/ARIA, iOS UIAccessibility, Android AccessibilityNodeInfo, and voice/multimodal ([Accessibility adapters](accessibility-adapters.md)).
+10. **Document blocks** — typed prose blocks attachable to tokens, components, and anatomy parts; makes design guidance machine-readable and agent-queryable ([Document blocks](document-blocks.md)).
+11. **Agent-readable surface** — operations and transport contracts (CLI, MCP server, Agent Skill) for AI agents consuming spec-conformant design data; covers session primer, token resolution, validation, query, and component description ([Agent-readable surface](agent-surface.md)).
+12. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
 
 ## Conformance
 
@@ -53,27 +57,31 @@ 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.                                             |
-| [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.                                                       |
-| [Product context](product-context.md)   | Product-layer context document: rationale, overrides, and extensions.                                       |
-| [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.                                                                                        |
+| [Mode Sets](mode-sets.md)                           | Mode set declarations, built-in mode sets, coverage.                                                                              |
+| [Manifest](manifest.md)                             | Platform manifest fields and validation expectations.                                                                             |
+| [Product context](product-context.md)               | Product-layer context document: rationale, overrides, and extensions.                                                             |
+| [Diff](diff.md)                                     | Semantic diff change taxonomy, token identity, property changes.                                                                  |
+| [Query](query.md)                                   | Filter notation for selecting tokens by structured fields.                                                                        |
+| [Accessibility](accessibility.md)                   | Component accessibility vocabulary: role, intents, focusable, keyboardIntents, wcag, and state-level AT fields (SPEC-030/031).    |
+| [Accessibility adapters](accessibility-adapters.md) | Informative platform adapter contracts mapping foundation accessibility vocabulary to Web/ARIA, iOS, Android, and voice surfaces. |
+| [Document blocks](document-blocks.md)               | Typed prose blocks (purpose, guideline, accessibility, do-dont, examples) attachable to any entity.                               |
+| [Agent-readable surface](agent-surface.md)          | Transport contracts (CLI, MCP, Agent Skill) and operation catalog for AI agents consuming spec-conformant design data.            |
+| [Evolution](evolution.md)                           | Deprecation lifecycle, migration windows, change classification.                                                                  |
 
 ## JSON Schema `$id` and versioning
 
 **NORMATIVE:** Canonical schema documents use **versioned path** `$id` URIs so major revisions can coexist on the documentation host:
 
 * Base: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/`
-* Examples: `.../v0/token.schema.json`, `.../v0/dimension.schema.json`, `.../v0/manifest.schema.json`
+* Examples: `.../v0/token.schema.json`, `.../v0/mode-set.schema.json`, `.../v0/manifest.schema.json`
 
 The **`v0`** segment denotes the **draft / pre-1.0** schema family aligned with spec version `1.0.0-draft`. A future **1.0.0** stable release MAY introduce `v1` paths without reusing `v0` URLs for incompatible shapes.
 

package/spec/manifest.md

@@ -22,7 +22,7 @@ A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.sche
 | `include`    | array of string | Semantic **queries** selecting subsets of foundation tokens to materialize.      |
 | `exclude`    | array of string | Queries removing tokens from the included set.                                   |
 | `overrides`  | array of object | Typed overrides; each entry **MUST** preserve the target token’s **value type**. |
-| `extensions` | object          | New tokens or dimensions introduced at the platform layer.                       |
+| `extensions` | object          | New tokens or mode sets introduced at the platform layer.                        |
 
 ### `include` / `exclude`
 
@@ -38,7 +38,7 @@ Each override object **MUST** include enough information to identify a target to
 
 ### `extensions`
 
-**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.
+**RECOMMENDED:** `extensions` follows the same structural conventions as foundation token files (tokens, mode sets) and **SHOULD** be validated with the same Layer 1 and Layer 2 rules.
 
 #### `extensions.formatting`
 

package/spec/mode-sets.md

@@ -0,0 +1,64 @@
+# Mode Sets
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines how **mode sets** (axes such as color scheme, scale, contrast) are **declared**, assigned **defaults**, and validated for **coverage**.
+
+## Mode Set declaration
+
+A **mode set declaration** is a JSON object describing one axis of variation. It **MUST** conform to [`mode-set.schema.json`](../schemas/mode-set.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/mode-set.schema.json`).
+
+### Required fields
+
+| Field     | Description                                              |
+| --------- | -------------------------------------------------------- |
+| `name`    | Stable identifier for the mode set (e.g. `colorScheme`). |
+| `modes`   | Array of allowed mode values (strings).                  |
+| `default` | Default mode; **MUST** be a member of `modes`.           |
+
+### Optional fields
+
+| Field         | Description                          |
+| ------------- | ------------------------------------ |
+| `description` | Human-readable documentation.        |
+| `coverage`    | Rules for mode coverage (see below). |
+
+## Built-in mode sets
+
+These mode sets are declared in the `mode-sets/` catalog (see [Mode Set catalog](#mode-set-catalog)) and **SHOULD** be used consistently across Spectrum-compatible datasets:
+
+| `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.                                                     |
+
+## Mode Set catalog
+
+The Spectrum foundation publishes mode set declarations as JSON files under `packages/design-data-spec/mode-sets/`. Each file conforms to [`mode-set.schema.json`](../schemas/mode-set.schema.json).
+
+**NORMATIVE:** Tooling (validators, resolution engine) **MUST** load mode set declarations from the dataset's mode set catalog before performing specificity calculations or coverage validation.
+
+**RECOMMENDED:** The catalog directory is named `mode-sets/` and is co-located with the dataset's spec package or manifest.
+
+## Optional mode sets
+
+Additional mode sets (e.g. `language`, `motion`) **MAY** be declared in a dataset's mode set catalog. Token name objects **MAY** include keys matching declared mode set names.
+
+## Defaults and specificity
+
+**NORMATIVE:** A token name object **omitting** a mode set field implies the token applies under the mode set's **`default`** mode for specificity and matching purposes unless the spec for that mode set states otherwise.
+
+**NORMATIVE:** Only **non-default** mode set fields on the name object increase **semantic specificity** (see [Cascade](cascade.md)).
+
+## Coverage validation
+
+**RECOMMENDED:** If a mode set's `coverage` requires **peer modes** (e.g. defining `dark` requires `light`), validators implement rule **`SPEC-005`** (see `rules/rules.yaml`).
+
+**RECOMMENDED:** Explicit **combination** tokens are used for rare cross-mode-set cases instead of inferring Cartesian products.
+
+## References
+
+* [#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: Mode Set declarations (machine-readable)](https://github.com/adobe/spectrum-design-data/issues/746)

package/spec/query.md

@@ -8,29 +8,29 @@ This document defines the **query filter notation**: a concise syntax for select
 
 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.    |
+| 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).              |
+| 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 mode set value.        |
+| `scale`       | `name.scale`       | Scale mode set value.               |
+| `contrast`    | `name.contrast`    | Contrast mode set 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.
 

package/spec/taxonomy.md

@@ -139,15 +139,15 @@ Semantic fields describe identity, structure, and intent. They are used for quer
 
 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
+### Mode-set fields
 
-Dimension fields represent axes of variation that drive the [cascade](cascade.md) resolution algorithm and [specificity](cascade.md#semantic-specificity) calculation.
+Mode-set 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.
+**NORMATIVE:** Mode-set field values are validated against declared [mode set](mode-sets.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`.
+Mode-set fields are those declared with `kind: "mode-set"` in the field catalog, plus any additional mode set keys from the dataset's [mode set declarations](mode-sets.md). In Spectrum's foundation catalog, the standard mode-set fields are: `colorScheme`, `scale`, `contrast`.
 
-See [Dimensions](dimensions.md) for dimension declarations, modes, and defaults.
+See [Mode Sets](mode-sets.md) for mode set declarations, modes, and defaults.
 
 ## Default serialization (legacy format)
 

package/spec/token-format.md

@@ -35,7 +35,7 @@ A token's `name` field **MAY** be a non-empty plain string instead of a name obj
 
 **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).
+**NORMATIVE:** String-named tokens **MUST NOT** participate in name-object cascade mode-set 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.
 
@@ -45,9 +45,9 @@ 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.
+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 `mode-set`), 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.
+Fields are divided into **semantic fields** (identity, structure, intent) and **mode-set fields** (axes of variation for cascade resolution). The tables below list Spectrum's foundation-standard fields as declared in the catalog.
 
 #### Semantic fields
 
@@ -67,16 +67,16 @@ Fields are divided into **semantic fields** (identity, structure, intent) and **
 | `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
+#### Mode-set fields
 
-| Field           | Status   | Description                                                                                     |
-| --------------- | -------- | ----------------------------------------------------------------------------------------------- |
-| `colorScheme`   | OPTIONAL | Dimension: light / dark / wireframe / etc.                                                      |
-| `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)). |
+| Field           | Status   | Description                                                                                 |
+| --------------- | -------- | ------------------------------------------------------------------------------------------- |
+| `colorScheme`   | OPTIONAL | Mode set: light / dark / wireframe / etc.                                                   |
+| `scale`         | OPTIONAL | Mode set: platform density scale (e.g. `desktop`, `mobile`). Distinct from semantic `size`. |
+| `contrast`      | OPTIONAL | Mode set: contrast level (e.g. `regular`, `high`).                                          |
+| Additional keys | OPTIONAL | Other mode sets declared in the dataset’s mode set catalog (see [Mode Sets](mode-sets.md)). |
 
-**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).
+**NORMATIVE:** Each field is validated according to the `validation` severity declared in its field declaration. Semantic fields typically use **advisory** severity (warning); mode-set 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).
 
@@ -249,7 +249,7 @@ The current `@adobe/spectrum-tokens` JSON uses **sets** (`color-set`, `scale-set
 | ------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
 | 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                    |
+| Complexity tracking | `name.semanticComplexity` (stored on token)                                | Computed at validation time from mode set 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.
 

package/spec/dimensions.md

@@ -1,64 +0,0 @@
-# Dimensions
-
-**Spec version:** `1.0.0-draft` (see [Overview](index.md))
-
-This document defines how **dimensions** (modes such as color scheme, scale, contrast) are **declared**, assigned **defaults**, and validated for **coverage**.
-
-## Dimension declaration
-
-A **dimension declaration** is a JSON object describing one axis of variation. It **MUST** conform to [`dimension.schema.json`](../schemas/dimension.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/dimension.schema.json`).
-
-### Required fields
-
-| Field     | Description                                               |
-| --------- | --------------------------------------------------------- |
-| `name`    | Stable identifier for the dimension (e.g. `colorScheme`). |
-| `modes`   | Array of allowed mode values (strings).                   |
-| `default` | Default mode; **MUST** be a member of `modes`.            |
-
-### Optional fields
-
-| Field         | Description                          |
-| ------------- | ------------------------------------ |
-| `description` | Human-readable documentation.        |
-| `coverage`    | Rules for mode coverage (see below). |
-
-## Built-in dimensions
-
-These dimensions are declared in the `dimensions/` catalog (see [Dimension catalog](#dimension-catalog)) and **SHOULD** be used consistently across Spectrum-compatible datasets:
-
-| `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
-
-Additional dimensions (e.g. `language`, `motion`) **MAY** be declared in a dataset’s dimension catalog. Token name objects **MAY** include keys matching declared dimension names.
-
-## Defaults and specificity
-
-**NORMATIVE:** A token name object **omitting** a dimension field implies the token applies under the dimension’s **`default`** mode for specificity and matching purposes unless the spec for that dimension states otherwise.
-
-**NORMATIVE:** Only **non-default** dimension fields on the name object increase **semantic specificity** (see [Cascade](cascade.md)).
-
-## Coverage validation
-
-**RECOMMENDED:** If a dimension’s `coverage` requires **peer modes** (e.g. defining `dark` requires `light`), validators implement rule **`SPEC-005`** (see `rules/rules.yaml`).
-
-**RECOMMENDED:** Explicit **combination** tokens are used for rare cross-dimensional cases instead of inferring Cartesian products.
-
-## References
-
-* [#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/src/canonical.js

@@ -1,61 +0,0 @@
-/*
-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",
-]);

package/src/validate.js

@@ -1,190 +0,0 @@
-/*
-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.
-*/
-
-/**
- * Layer 2 cross-reference validator for design-data-spec.
- *
- * Implements SPEC-018 through SPEC-027: semantic rules that validate token
- * name-object fields against component declarations, validate component
- * declarations internally, and validate tokenBindings references.
- *
- * @see spec/component-format.md#spec-rules
- * @see spec/anatomy-format.md#spec-rules
- * @see spec/state-model.md#spec-rules
- */
-
-import {
-  CANONICAL_SLOTS,
-  CANONICAL_ANATOMY_PARTS,
-  CANONICAL_STATES,
-} from "./canonical.js";
-
-/**
- * @typedef {{ ruleId: string, severity: 'error'|'warning', message: string, tokenName?: string, componentName?: string }} Diagnostic
- * @typedef {{ name: string|object, [key: string]: unknown }} Token
- * @typedef {{ name: string, options?: object, anatomy?: Array<{name:string,description?:string}>, slots?: Array<{name:string,description?:string}>, states?: Array<{name:string,trigger?:string,precedence?:number,layered?:boolean,description?:string}> }} ComponentDeclaration
- * @typedef {{ tokens?: Token[], components?: ComponentDeclaration[] }} Dataset
- */
-
-/**
- * Validate a dataset for SPEC-018 through SPEC-024 compliance.
- *
- * @param {Dataset} dataset
- * @returns {Diagnostic[]}
- */
-export function validateDataset(dataset) {
-  const tokens = dataset.tokens ?? [];
-  const components = dataset.components ?? [];
-
-  // Build component lookup map keyed by name.
-  const componentMap = new Map(components.map((c) => [c.name, c]));
-
-  const diagnostics = [];
-
-  // --- Token cross-reference rules ---
-  for (const token of tokens) {
-    const name = token.name;
-    // String names (SPEC-017 escape hatch) skip cross-reference checks.
-    if (typeof name !== "object" || name === null) continue;
-
-    const tokenLabel = JSON.stringify(name);
-
-    if (name.component != null) {
-      // SPEC-018: component name must be declared
-      if (!componentMap.has(name.component)) {
-        diagnostics.push({
-          ruleId: "SPEC-018",
-          severity: "error",
-          message: `Token '${tokenLabel}' references undeclared component '${name.component}'`,
-          tokenName: tokenLabel,
-        });
-        // Can't validate further fields without a component declaration.
-        continue;
-      }
-
-      const component = componentMap.get(name.component);
-
-      // SPEC-019: variant must be in component's variant option enum
-      if (name.variant != null) {
-        const variantEnum = component.options?.variant?.enum;
-        if (Array.isArray(variantEnum) && !variantEnum.includes(name.variant)) {
-          diagnostics.push({
-            ruleId: "SPEC-019",
-            severity: "error",
-            message: `Token '${tokenLabel}' has variant '${name.variant}' which is not declared on component '${name.component}'`,
-            tokenName: tokenLabel,
-            componentName: name.component,
-          });
-        }
-      }
-
-      // SPEC-020: anatomy must match a declared anatomy part name
-      if (name.anatomy != null) {
-        const declaredParts = new Set(
-          (component.anatomy ?? []).map((p) => p.name),
-        );
-        if (declaredParts.size > 0 && !declaredParts.has(name.anatomy)) {
-          diagnostics.push({
-            ruleId: "SPEC-020",
-            severity: "error",
-            message: `Token '${tokenLabel}' references undeclared anatomy part '${name.anatomy}' on component '${name.component}'`,
-            tokenName: tokenLabel,
-            componentName: name.component,
-          });
-        }
-      }
-
-      // SPEC-022: state must match a declared state name (only when states are declared)
-      if (name.state != null) {
-        const declaredStates = new Set(
-          (component.states ?? []).map((s) => s.name),
-        );
-        if (declaredStates.size > 0 && !declaredStates.has(name.state)) {
-          diagnostics.push({
-            ruleId: "SPEC-022",
-            severity: "error",
-            message: `Token '${tokenLabel}' references undeclared state '${name.state}' on component '${name.component}'`,
-            tokenName: tokenLabel,
-            componentName: name.component,
-          });
-        }
-      }
-    }
-  }
-
-  // --- Component declaration internal rules ---
-  for (const component of components) {
-    const cName = component.name;
-
-    // SPEC-021: custom slot names should have descriptions
-    for (const slot of component.slots ?? []) {
-      if (!CANONICAL_SLOTS.has(slot.name) && !slot.description) {
-        diagnostics.push({
-          ruleId: "SPEC-021",
-          severity: "warning",
-          message: `Component '${cName}' has custom slot '${slot.name}' with no description — add a description or use a canonical slot name`,
-          componentName: cName,
-        });
-      }
-    }
-
-    // SPEC-023: custom anatomy part names should have descriptions
-    for (const part of component.anatomy ?? []) {
-      if (!CANONICAL_ANATOMY_PARTS.has(part.name) && !part.description) {
-        diagnostics.push({
-          ruleId: "SPEC-023",
-          severity: "warning",
-          message: `Component '${cName}' has custom anatomy part '${part.name}' with no description`,
-          componentName: cName,
-        });
-      }
-    }
-
-    // SPEC-024: custom state names should have descriptions
-    for (const state of component.states ?? []) {
-      if (!CANONICAL_STATES.has(state.name) && !state.description) {
-        diagnostics.push({
-          ruleId: "SPEC-024",
-          severity: "warning",
-          message: `Component '${cName}' has custom state '${state.name}' with no description`,
-          componentName: cName,
-        });
-      }
-    }
-  }
-
-  // --- Token binding rules ---
-
-  // SPEC-027: each tokenBindings[].token must resolve to a known token name.
-  // String-named tokens are matched directly. Name-object tokens are skipped
-  // here because tokenBindings always reference tokens by their string name.
-  const tokenNameSet = new Set(
-    tokens
-      .map((t) => (typeof t.name === "string" ? t.name : null))
-      .filter(Boolean),
-  );
-
-  for (const component of components) {
-    for (const binding of component.tokenBindings ?? []) {
-      if (!tokenNameSet.has(binding.token)) {
-        diagnostics.push({
-          ruleId: "SPEC-027",
-          severity: "error",
-          message: `Component '${component.name}' tokenBindings references unknown token '${binding.token}'`,
-          componentName: component.name,
-        });
-      }
-    }
-  }
-
-  return diagnostics;
-}