@adobe/design-data-spec 0.9.0 → 0.10.0

package/spec/accessibility-adapters.md

@@ -0,0 +1,219 @@
+# Accessibility adapters
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+> **This chapter is informative.** It provides guidance for platform adapter repos; it does not add normative constraints to the foundation spec.
+
+This chapter shows how the semantic accessibility vocabulary defined in [Accessibility](accessibility.md) maps to real platform APIs across web (ARIA), iOS (UIAccessibility), Android (AccessibilityNodeInfo), and voice/multimodal surfaces. Platform adapter repos use this as a translation contract when implementing accessibility support for Spectrum components. The foundation layer ships intent; adapters ship the platform binding.
+
+Scoped under planned RFC-B. See [rfc-coordination.md](../docs/rfc-coordination.md).
+
+## Adapter overview
+
+A platform adapter repo declares which foundation components it supports and implements a mapping layer that translates each component's `accessibility` declaration to the platform's native accessibility API. When a field is absent from a component's `accessibility` declaration, the adapter falls back to its own defaults or omits the attribute.
+
+Adapters are not required to implement every field — a minimal adapter might only handle `role` and `focusable`. The fields documented below describe what each foundation field means at the platform layer when the adapter chooses to implement it.
+
+## Web / ARIA
+
+ARIA (Accessible Rich Internet Applications) is the primary web accessibility API. Adapters set HTML `role` attributes and `aria-*` state properties on the root element or on relevant sub-elements.
+
+### `role`
+
+| Foundation `role` | ARIA / HTML equivalent                         |
+| ----------------- | ---------------------------------------------- |
+| `button`          | `<button>` or `role="button"`                  |
+| `checkbox`        | `<input type="checkbox">` or `role="checkbox"` |
+| `combobox`        | `role="combobox"`                              |
+| `dialog`          | `role="dialog"`                                |
+| `link`            | `<a href>` or `role="link"`                    |
+| `listbox`         | `role="listbox"`                               |
+| `menu`            | `role="menu"`                                  |
+| `menuitem`        | `role="menuitem"`                              |
+| `radio`           | `<input type="radio">` or `role="radio"`       |
+| `slider`          | `role="slider"`                                |
+| `spinbutton`      | `role="spinbutton"`                            |
+| `switch`          | `role="switch"`                                |
+| `tab`             | `role="tab"`                                   |
+| `textbox`         | `<input type="text">` or `role="textbox"`      |
+| `tooltip`         | `role="tooltip"`                               |
+| `tree`            | `role="tree"`                                  |
+
+### `intents`
+
+| Foundation intent | Web guidance                                                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------------- |
+| `trigger`         | Ensure the element has an accessible name via `aria-label`, `aria-labelledby`, or a visible label |
+| `select`          | Set `aria-selected` on child options; the container gets `role="listbox"` or `role="combobox"`    |
+| `navigate`        | Use `<a href>` or `role="link"`; ensure the destination is announced                              |
+| `expand`          | Set `aria-expanded="true"` / `"false"` on the trigger element                                     |
+| `collapse`        | Toggle `aria-expanded` to `"false"`                                                               |
+| `input`           | Associate a visible `<label>` or `aria-label`; use `aria-describedby` for hints                   |
+| `choose`          | Use `aria-valuenow`, `aria-valuemin`, `aria-valuemax` for range inputs                            |
+| `dismiss`         | Return focus to the trigger element on close; announce the closure if needed                      |
+
+### `focusable`
+
+* `true` → set `tabindex="0"` on the root element, or use a natively focusable HTML element.
+* `false` → set `tabindex="-1"` for elements that receive programmatic focus; use `aria-hidden="true"` for purely decorative elements. For roving-tabindex composites (radio groups, toolbars, tree views), the adapter manages which child holds `tabindex="0"`.
+
+### `keyboardIntents`
+
+| Foundation intent  | Conventional key binding              |
+| ------------------ | ------------------------------------- |
+| `activate`         | Enter, Space                          |
+| `expand`           | ArrowDown, Enter, Space               |
+| `collapse`         | Escape, ArrowUp                       |
+| `navigate-options` | ArrowUp, ArrowDown                    |
+| `navigate-items`   | ArrowLeft, ArrowRight                 |
+| `increment`        | ArrowUp, ArrowRight                   |
+| `decrement`        | ArrowDown, ArrowLeft                  |
+| `dismiss`          | Escape                                |
+| `select-all`       | Ctrl+A (Windows/Linux), Cmd+A (macOS) |
+
+Key bindings shown are conventional. Web adapters should follow the ARIA Authoring Practices Guide patterns for the component's `role`.
+
+### `wcag`
+
+The `wcag` array is developer guidance at the web layer, not an automated attribute. Web adapter implementations should:
+
+* Include listed criteria in component documentation.
+* Add automated accessibility tests (e.g., axe-core) that target listed criteria.
+* Flag in PR checklists when changes may affect listed criteria.
+
+### State fields
+
+* `announce` → set `aria-live="polite"` (or `"assertive"` for urgent transitions) on a live region element and inject the `announce` text on state entry.
+* `communicates` → map to the corresponding `aria-*` state attribute (e.g., `"expanded"` → `aria-expanded="true"`). See the `communicates` vocabulary table in [Accessibility](accessibility.md#communicates).
+* `blocksInteraction` → set `aria-disabled="true"` and `tabindex="-1"` on the root element; suppress pointer and keyboard events.
+
+## iOS / UIAccessibility
+
+iOS exposes accessibility semantics through `UIAccessibility` protocol properties on `UIView` (UIKit) and through accessibility modifiers in SwiftUI.
+
+### `role`
+
+| Foundation `role` | UIAccessibilityTraits / SwiftUI                                |
+| ----------------- | -------------------------------------------------------------- |
+| `button`          | `.button`                                                      |
+| `checkbox`        | `.button` with toggled state, or SwiftUI `Toggle`              |
+| `combobox`        | `.button` (picker-like behavior)                               |
+| `dialog`          | Presented as modal sheet; VoiceOver reads the accessible label |
+| `link`            | `.link`                                                        |
+| `listbox`         | Container view; children use `.button` or `.selected`          |
+| `menu`            | `.button` on trigger; menu items as `.button`                  |
+| `menuitem`        | `.button`                                                      |
+| `radio`           | `.button` with `.selected` when active                         |
+| `slider`          | `.adjustable`                                                  |
+| `spinbutton`      | `.adjustable`                                                  |
+| `switch`          | `.button` with `.selected` / SwiftUI `Toggle`                  |
+| `tab`             | `.button` with `.selected`                                     |
+| `textbox`         | `.keyboard` traits; `UITextField` or `UITextView`              |
+| `tooltip`         | `.staticText` on an overlay element                            |
+| `tree`            | Hierarchical cells with `accessibilityContainerType`           |
+
+### `intents`
+
+* `trigger` → provide `accessibilityLabel` describing the action the user will invoke.
+* `select` → set `accessibilityTraits` to include `.selected` when the item is in a selected state.
+* `expand` / `collapse` → update `accessibilityHint` or `accessibilityValue` to describe the current expanded/collapsed state.
+* `choose` → implement `accessibilityIncrement()` / `accessibilityDecrement()` with the `.adjustable` trait.
+* `dismiss` → handle `accessibilityPerformEscape()` to close the view and return focus.
+
+### `focusable`
+
+* `true` → `isAccessibilityElement = true`.
+* `false` → `isAccessibilityElement = false`. For composite views that manage focus internally (e.g., a radio group), set `accessibilityContainerType` and manage the focused child programmatically.
+
+### `keyboardIntents`
+
+Relevant for external keyboard support (iPad with Magic Keyboard, Bluetooth keyboard):
+
+* `activate` → register a `UIKeyCommand` for Return and Space.
+* `navigate-options` / `navigate-items` → register `UIKeyCommand` entries for arrow keys.
+* `dismiss` → register a `UIKeyCommand` for Escape.
+
+### `wcag`
+
+Include WCAG criteria in component documentation and Accessibility Inspector audits. The `wcag` array has no automatic mapping at the iOS layer.
+
+### State fields
+
+* `announce` → call `UIAccessibility.post(notification: .announcement, argument: announceText)` on state entry. In SwiftUI, use `AccessibilityNotification.Announcement`.
+* `communicates` → set the corresponding trait or value (e.g., `"expanded"` → set `accessibilityValue = "expanded"` / `"collapsed"`; `"disabled"` → add `.notEnabled`; `"busy"` → add `.causesPageTurn` or a custom announcement).
+* `blocksInteraction` → add `.notEnabled` trait; set `isAccessibilityElement = false` on interactive children.
+
+## Android / AccessibilityNodeInfo
+
+Android exposes accessibility semantics via `AccessibilityNodeInfo` populated through `ViewCompat.setAccessibilityDelegate()` or Jetpack Compose `Modifier.semantics {}`.
+
+### `role`
+
+| Foundation `role` | Android mapping                                             |
+| ----------------- | ----------------------------------------------------------- |
+| `button`          | `Button` widget or `setRoleDescription("button")`           |
+| `checkbox`        | `CheckBox` widget or `setCheckable(true)`                   |
+| `combobox`        | `Spinner` widget or `setRoleDescription("combobox")`        |
+| `dialog`          | Dialog window; `setDismissable(true)`                       |
+| `link`            | `setRoleDescription("link")`; add `ACTION_CLICK`            |
+| `listbox`         | `RecyclerView` with `setCollectionInfo`                     |
+| `menu`            | `setRoleDescription("menu")` on the container               |
+| `menuitem`        | `setRoleDescription("menu item")`                           |
+| `radio`           | `RadioButton` widget or `setCheckable(true)` + `setChecked` |
+| `slider`          | `SeekBar` widget or `RangeSemantics` in Compose             |
+| `spinbutton`      | `setRoleDescription("spin button")`                         |
+| `switch`          | `Switch` widget or `setRoleDescription("switch")`           |
+| `tab`             | `TabLayout` tab item; `setSelected(true)` when active       |
+| `textbox`         | `EditText` widget or `TextField` in Compose                 |
+| `tooltip`         | `setTooltipText(text)`                                      |
+| `tree`            | `setCollectionInfo` with hierarchical structure             |
+
+### `intents`
+
+* `trigger` → set `setContentDescription()` describing the action.
+* `select` → call `setSelected(true)` on selection.
+* `expand` / `collapse` → call `setExpandable(true)` and `setExpanded(true/false)`.
+* `choose` → add `ACTION_SCROLL_FORWARD` / `ACTION_SCROLL_BACKWARD` actions.
+* `dismiss` → call `setDismissable(true)`; handle `ACTION_DISMISS`.
+
+### `focusable`
+
+* `true` → `setFocusable(true)` and `setImportantForAccessibility(IMPORTANT_FOR_ACCESSIBILITY_YES)`.
+* `false` → `setImportantForAccessibility(IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS)` for decorative views. For composite views, manage focus via `performAccessibilityAction(ACTION_ACCESSIBILITY_FOCUS, ...)`.
+
+### `keyboardIntents`
+
+Relevant for physical keyboard input (Chromebook, external keyboard):
+
+* `activate` → handle `KeyEvent.KEYCODE_ENTER` / `KEYCODE_SPACE`.
+* `navigate-options` / `navigate-items` → handle arrow key `KeyEvent`s.
+* `dismiss` → handle `KeyEvent.KEYCODE_ESCAPE` or `KEYCODE_BACK`.
+
+### `wcag`
+
+Include criteria in component documentation and Accessibility Scanner audits. No automatic mapping.
+
+### State fields
+
+* `announce` → call `ViewCompat.announceForAccessibility(view, announceText)` or send `AccessibilityEvent.TYPE_ANNOUNCEMENT`. In Compose, use `LocalAccessibilityManager.current?.announce(...)`.
+* `communicates` → set the corresponding node property (e.g., `"expanded"` → call `setExpandable(true)` then `setExpanded(true)`; `"checked"` → `setChecked(true)`; `"disabled"` → `setEnabled(false)`).
+* `blocksInteraction` → call `setEnabled(false)` on the root view. Use `IMPORTANT_FOR_ACCESSIBILITY_YES` to keep the element discoverable by AT as disabled; use `IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS` to hide the element and its subtree from AT entirely.
+
+## Voice and multimodal
+
+> **Informative sketch.** The following mapping is exploratory. Platform-specific voice adapter specs are deferred.
+
+For voice interfaces (Alexa, Google Assistant, Siri Shortcuts) and future multimodal surfaces, the foundation vocabulary maps conceptually as follows:
+
+| Foundation field  | Voice / multimodal mapping                                            |
+| ----------------- | --------------------------------------------------------------------- |
+| `role`            | Utterance type in a voice schema (e.g., `button` → invocable command) |
+| `intents`         | Action category exposed in a voice intent catalog                     |
+| `announce`        | Spoken response on state transition                                   |
+| `communicates`    | State value spoken when the user queries component status             |
+| `focusable`       | Not applicable for purely voice surfaces                              |
+| `keyboardIntents` | Not applicable for purely voice surfaces                              |
+
+### `wcag`
+
+WCAG 2.x success criteria apply at the web layer. For voice and multimodal surfaces, WCAG is not directly applicable; accessibility requirements for these surfaces are deferred to platform-specific adapter specs.

package/spec/agent-surface.md

@@ -9,7 +9,7 @@ This document defines the **agent-readable surface**: the contract an external A
 
 The surface targets three consumer shapes:
 
-1. **Authoring an external system.** A non-Spectrum design system being constructed inside an AI tool (e.g. a finance-dashboard prototype tool) wants to produce spec-conformant tokens, dimensions, and components without re-deriving the format from prose.
+1. **Authoring an external system.** A non-Spectrum design system being constructed inside an AI tool (e.g. a finance-dashboard prototype tool) wants to produce spec-conformant tokens, mode sets, and components without re-deriving the format from prose.
 2. **Extending Spectrum.** A product or platform team adds tokens, components, or overrides on top of the published Spectrum foundation and needs to validate that the additions cascade and resolve correctly.
 3. **Adhering to Spectrum.** A prototyping tool generates UI that should match Spectrum even where no bound component exists (e.g. CSS for a custom card). The agent needs to look up tokens by intent, validate proposed property values against the foundation, and report drift.
 
@@ -27,7 +27,7 @@ The surface targets three consumer shapes:
 
 | Operation            | Reads                                                  | Returns                                                                                                                                                                                   | Backed by                                                 |
 | -------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| `resolve_token`      | property + dimension context                           | winning token (literal or resolved alias) with file/UUID/specificity                                                                                                                      | `cascade::resolve`                                        |
+| `resolve_token`      | property + mode set context                            | winning token (literal or resolved alias) with file/UUID/specificity                                                                                                                      | `cascade::resolve`                                        |
 | `query_tokens`       | filter expression (see [Query](query.md))              | matching token list                                                                                                                                                                       | `query::filter`                                           |
 | `validate_usage`     | candidate token document or fragment                   | `ValidationReport` (Layer 1 + Layer 2 diagnostics)                                                                                                                                        | `validate::validate_*`                                    |
 | `describe_component` | component identifier                                   | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape) | (Phase 6 contract)                                        |
@@ -51,7 +51,7 @@ An agent loop benefits from a small, structural overview at session start so tha
 | ---------------- | -------------- | ----------------------------------------------------------------- |
 | `specVersion`    | string         | The spec version the dataset declares (see [Overview](index.md)). |
 | `manifest`       | object \| null | Resolved platform manifest, if any (see [Manifest](manifest.md)). |
-| `dimensions`     | array          | Declared dimensions with modes and defaults.                      |
+| `modeSets`       | array          | Declared mode sets with modes and defaults.                       |
 | `components`     | array          | Component identifiers exposed by the dataset (post Phase 6).      |
 | `taxonomyFields` | array          | Active name-object fields and their declared vocabulary.          |
 | `tokenCount`     | integer        | Total tokens in the merged cascade.                               |
@@ -130,7 +130,7 @@ The `describe_component` tool returns the component declaration object as stored
 
 The following sketch shows an agent loop that adheres-to-Spectrum while authoring a non-bound component.
 
-1. Agent calls `primer ./spectrum-data` and learns that `colorScheme` and `scale` are the active dimensions and that `button`, `picker`, and `card` are exposed components.
+1. Agent calls `primer ./spectrum-data` and learns that `colorScheme` and `scale` are the active mode sets and that `button`, `picker`, and `card` are exposed components.
 2. User asks for a "subtle hover background for a card on dark mode".
 3. Agent calls `suggest_token "subtle hover background for card" --property background-color`.
 4. Surface returns a ranked list including `background-color-hover` from Spectrum foundation and `background-color-card-hover` from a card component group.

package/spec/cascade.md

@@ -20,9 +20,9 @@ Design data is organized in three layers, ordered from lowest to highest precede
 
 ## Semantic specificity
 
-**Specificity** counts how many **non-default** dimension fields in the token’s **name object** are set for the dimensions declared in the dataset.
+**Specificity** counts how many **non-default** mode set fields in the token’s **name object** are set for the mode sets declared in the dataset.
 
-**NORMATIVE:** Default dimension values (see [Dimensions](dimensions.md)) **MUST NOT** contribute to specificity.
+**NORMATIVE:** Default mode set values (see [Mode Sets](mode-sets.md)) **MUST NOT** contribute to specificity.
 
 **NORMATIVE:** When two candidates from the **same layer** match the context, the candidate with **higher** specificity **MUST** win.
 
@@ -35,20 +35,20 @@ Design data is organized in three layers, ordered from lowest to highest precede
 
 ## Context
 
-A **resolution context** is a set of dimension key/value pairs (e.g. `colorScheme: dark`, `scale: medium`, `contrast: regular`) plus the **target layer** being resolved (usually product → platform → foundation).
+A **resolution context** is a set of mode set key/value pairs (e.g. `colorScheme: dark`, `scale: medium`, `contrast: regular`) plus the **target layer** being resolved (usually product → platform → foundation).
 
 ## Resolution algorithm (informative outline)
 
 The following outline is **RECOMMENDED** for conforming resolvers:
 
-1. Collect all token candidates whose name object **matches** the context (every specified dimension in the context equals the name object’s dimension field, or the name object omits that dimension where omission means “matches any” per dimension rules).
+1. Collect all token candidates whose name object **matches** the context (every specified mode set in the context equals the name object’s mode set field, or the name object omits that mode set where omission means “matches any” per mode set rules).
 2. Filter to candidates at or below the requested layer.
 3. Select the maximum **layer** precedence.
 4. Within that layer, select the maximum **specificity**.
 5. Break remaining ties by document order (earlier in file wins; lexicographically earlier file path wins across files). Emit SPEC-006 warning.
 6. If the winning candidate is an alias (`$ref`), **resolve the alias chain** to a literal value (see [Alias resolution](#alias-resolution)).
 
-Exact matching rules for omitted dimensions are defined alongside dimension declarations in [Dimensions](dimensions.md).
+Exact matching rules for omitted mode sets are defined alongside mode set declarations in [Mode Sets](mode-sets.md).
 
 ## Alias resolution
 
@@ -58,9 +58,9 @@ Exact matching rules for omitted dimensions are defined alongside dimension decl
 
 **RATIONALE:** Aliases participate in cascade as opaque references — their target values are not examined during specificity calculation or layer comparison. This keeps resolution deterministic and allows aliases to be valid candidates at any specificity level.
 
-## Cross-dimensional overrides
+## Cross-mode-set overrides
 
-**NORMATIVE:** Overrides that combine multiple dimensions in a way not expressible by a single name object alone **MUST** use **explicit combination tokens** (tokens whose name object sets multiple non-default dimensions) as defined in the dataset; magic merging of unrelated tokens is **NOT** allowed.
+**NORMATIVE:** Overrides that combine multiple mode sets in a way not expressible by a single name object alone **MUST** use **explicit combination tokens** (tokens whose name object sets multiple non-default mode sets) as defined in the dataset; magic merging of unrelated tokens is **NOT** allowed.
 
 ## References
 

package/spec/component-format.md

@@ -40,6 +40,7 @@ A component declaration **MUST** contain:
 | `lifecycle`      | object | Version lifecycle metadata — see [Lifecycle](#lifecycle).                                                                                  |
 | `tokenBindings`  | array  | Tokens this component uses — see [Token bindings](#token-bindings) (Phase 6.7).                                                            |
 | `documentBlocks` | array  | Typed prose blocks for this component — see [Document blocks](#document-blocks) (Phase 9).                                                 |
+| `accessibility`  | object | Semantic accessibility vocabulary — see [Accessibility](accessibility.md) (Phase 7).                                                       |
 
 **NORMATIVE:** No properties beyond those listed above are permitted at the top level of a component declaration. Additional fields **MUST** cause a Layer 1 schema error.
 
@@ -351,6 +352,37 @@ A complete button component declaration:
 }
 ```
 
+## Accessibility
+
+**Phase 7.** Component declarations MAY carry an `accessibility` object at the top level. State declarations MAY carry `announce`, `communicates`, and `blocksInteraction` fields. See [spec/accessibility.md](accessibility.md) for the full vocabulary, SPEC rules, and examples.
+
+```json
+{
+  "name": "button",
+  "displayName": "Button",
+  "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
+  "accessibility": {
+    "role": "button",
+    "intents": ["trigger"],
+    "focusable": true,
+    "keyboardIntents": ["activate"],
+    "wcag": [
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+    ]
+  },
+  "states": [
+    {
+      "name": "disabled",
+      "trigger": "prop",
+      "precedence": 100,
+      "announce": "Button disabled",
+      "communicates": "disabled",
+      "blocksInteraction": true
+    }
+  ]
+}
+```
+
 ## Document blocks
 
 **Phase 9.** Component declarations MAY carry a `documentBlocks` array at the top level, and individual anatomy parts MAY carry their own `documentBlocks` arrays. See [spec/document-blocks.md](document-blocks.md) for the full block schema, type vocabulary, and SPEC rules.

package/spec/document-blocks.md

@@ -67,7 +67,7 @@ Accessibility notes specific to this entity — contrast behavior, screen reader
 ```json
 {
   "type": "accessibility",
-  "content": "Accent background tokens must maintain a minimum 3:1 contrast ratio against the surface they sit on in both light and dark schemes. The high-contrast dimension variant provides an alternative that meets 4.5:1."
+  "content": "Accent background tokens must maintain a minimum 3:1 contrast ratio against the surface they sit on in both light and dark schemes. The high-contrast mode-set variant provides an alternative that meets 4.5:1."
 }
 ```
 

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
 
@@ -15,11 +15,12 @@ The specification defines:
    * **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. **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)).
@@ -56,30 +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.                                                                     |
-| [Accessibility](accessibility.md)          | Component accessibility vocabulary: role, intents, focusable, keyboardIntents, wcag, and state-level AT fields (SPEC-030/031). |
-| [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.                                                               |
+| 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)