@adobe/design-data-spec 0.8.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/accessibility.md

@@ -0,0 +1,219 @@
+# Accessibility
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This chapter defines the **semantic accessibility vocabulary** that component declarations carry at the foundation layer. A component's accessibility declaration expresses intent — its semantic role, interaction purposes, focus behavior, and applicable WCAG criteria — without encoding platform-specific APIs. Platform adapter repos translate this vocabulary to ARIA attributes, iOS UIAccessibility traits, Android AccessibilityNodeInfo properties, and other platform contracts.
+
+This mirrors how the cascade defines foundation→platform layering for tokens: the spec ships the vocabulary; platform repos ship the mapping.
+
+Scoped under planned RFC-B. See [rfc-coordination.md](../docs/rfc-coordination.md).
+
+## Accessibility declaration
+
+The `accessibility` object is an optional top-level field on a [component declaration](component-format.md). When present, it MUST conform to [`accessibility.schema.json`](../schemas/accessibility.schema.json) (schema added in Phase 7.3).
+
+### Fields
+
+| Field             | Type      | Required | Description                                              |
+| ----------------- | --------- | -------- | -------------------------------------------------------- |
+| `role`            | string    | No       | Semantic role from the canonical role vocabulary         |
+| `intents`         | string\[] | No       | Semantic interaction intents                             |
+| `focusable`       | boolean   | No       | Whether the component receives keyboard focus by default |
+| `keyboardIntents` | string\[] | No       | Keyboard interaction intents when focused                |
+| `wcag`            | object\[] | No       | Applicable WCAG 2.x success criteria                     |
+
+**NORMATIVE:** An `accessibility` object SHOULD contain at least one field. An empty `accessibility` object provides no semantic value.
+
+> **Note:** Anatomy parts (see [Anatomy format](anatomy-format.md)) do not carry an
+> `accessibility` field at this spec version. Component-level accessibility applies to the
+> component as a whole. Per-part accessibility semantics are deferred to Phase 7.3.
+
+### `role`
+
+The `role` field names the semantic role of the component. It maps conceptually to ARIA widget and landmark roles, iOS `UIAccessibilityTraits`, Android role descriptions, and equivalent constructs on other platforms — but it is **not** a direct ARIA attribute. Platform adapters perform the translation.
+
+**NORMATIVE:** Custom values (outside the canonical vocabulary below) are permitted. When using a custom value, the component SHOULD include a `description` field that documents the role's semantics.
+
+**Canonical role vocabulary:**
+
+| Value        | Semantic meaning                                    |
+| ------------ | --------------------------------------------------- |
+| `button`     | Triggers a discrete action                          |
+| `checkbox`   | Binary on/off selection                             |
+| `combobox`   | Combined text input with a selectable option list   |
+| `dialog`     | Modal overlay requiring a user response             |
+| `link`       | Navigates the user to another context               |
+| `listbox`    | Selectable list of options                          |
+| `menu`       | List of commands or options                         |
+| `menuitem`   | Individual item within a menu                       |
+| `radio`      | Single-select option within a group                 |
+| `slider`     | Range input with a continuous value                 |
+| `spinbutton` | Numeric input with increment and decrement controls |
+| `switch`     | Toggles between two states (on/off)                 |
+| `tab`        | Selects a panel within a tabbed interface           |
+| `textbox`    | Accepts free-form text input                        |
+| `tooltip`    | Contextual information overlay; not interactive     |
+| `tree`       | Hierarchical navigable list                         |
+
+### `intents`
+
+The `intents` array lists the semantic interaction purposes the component supports. Multiple intents are permitted — a combobox, for example, both accepts text input and selects from a list.
+
+Platform adapters use `intents` to determine which ARIA properties, traits, or accessibility attributes to apply.
+
+**Canonical intent vocabulary:**
+
+| Value      | Meaning                                    |
+| ---------- | ------------------------------------------ |
+| `trigger`  | Activates or invokes an action             |
+| `select`   | Selects from a set of options              |
+| `navigate` | Moves the user to another context          |
+| `expand`   | Reveals additional content                 |
+| `collapse` | Conceals content                           |
+| `input`    | Accepts user-typed text                    |
+| `choose`   | Picks a value from a range or discrete set |
+| `dismiss`  | Closes or removes an element               |
+
+### `focusable`
+
+The `focusable` boolean declares whether the component receives keyboard focus via the Tab key by default.
+
+* `true` — the component is in the tab order; platform adapters set `tabindex="0"` or the platform equivalent.
+* `false` — the component is not in the tab order; child elements may still be individually
+  focusable. Components that manage focus internally (radio groups, toolbars, tree views)
+  use the roving `tabindex` pattern — one child is focusable at a time. For these, set
+  `focusable: false`; the platform adapter manages which child holds `tabindex="0"`.
+* When absent, focus behavior is unspecified at the foundation layer.
+
+### `keyboardIntents`
+
+The `keyboardIntents` array lists the keyboard interaction intents the component responds to when focused. Platform adapters use this to bind keyboard event handlers.
+
+**RECOMMENDED:** Where a `keyboardIntents` value has a direct semantic equivalent in `intents`,
+both SHOULD be declared. For example, a component with `expand` in `intents` SHOULD also include
+`expand` in `keyboardIntents`. Keyboard-specific intents such as `activate`, `navigate-options`,
+and `navigate-items` have no `intents` counterpart and are keyboard-only.
+
+**Canonical keyboard intent vocabulary:**
+
+| Value              | Default key(s)          | Meaning                                                 |
+| ------------------ | ----------------------- | ------------------------------------------------------- |
+| `activate`         | Enter, Space            | Triggers the component's primary action                 |
+| `expand`           | Space, Enter, ArrowDown | Reveals associated content                              |
+| `collapse`         | Escape, ArrowUp         | Conceals associated content                             |
+| `navigate-options` | ArrowUp, ArrowDown      | Moves focus through a list of options                   |
+| `navigate-items`   | ArrowLeft, ArrowRight   | Moves focus between peer elements (tabs, toolbar items) |
+| `increment`        | ArrowUp, ArrowRight     | Increases a numeric or ranged value                     |
+| `decrement`        | ArrowDown, ArrowLeft    | Decreases a numeric or ranged value                     |
+| `dismiss`          | Escape                  | Closes or cancels                                       |
+| `select-all`       | Ctrl+A                  | Selects all items in a collection                       |
+
+The "Default key(s)" column is informative. Platform adapters determine actual key bindings; the foundation layer declares intent only.
+
+### `wcag`
+
+The `wcag` array lists the WCAG 2.x success criteria applicable to this component. Entries are objects with the following fields:
+
+| Field       | Type   | Required | Description                                  |
+| ----------- | ------ | -------- | -------------------------------------------- |
+| `criterion` | string | Yes      | WCAG criterion number, e.g. `"1.3.1"`        |
+| `level`     | string | Yes      | Conformance level: `"A"`, `"AA"`, or `"AAA"` |
+| `title`     | string | No       | Human-readable criterion title               |
+
+**NORMATIVE:** `criterion` MUST be a valid WCAG 2.x criterion number in
+`"<principle>.<guideline>.<criterion>"` format, where `<principle>` is 1–4 (matching WCAG 2.x
+principles: Perceivable, Operable, Understandable, Robust). `level` MUST be one of `"A"`,
+`"AA"`, or `"AAA"`.
+
+Example `wcag` entry:
+
+```json
+{ "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+```
+
+## State-level accessibility fields
+
+State declarations (see [State model](state-model.md)) MAY carry the following additional fields that describe how assistive technology responds to state transitions. These fields extend the base state declaration object defined in `spec/state-model.md`.
+
+| Field               | Type    | Required | Description                                               |
+| ------------------- | ------- | -------- | --------------------------------------------------------- |
+| `announce`          | string  | No       | Screen-reader announcement hint for this state transition |
+| `communicates`      | string  | No       | Semantic meaning conveyed to AT when this state is active |
+| `blocksInteraction` | boolean | No       | Whether this state prevents all user interaction          |
+
+### `announce`
+
+A hint string used by platform adapters to populate ARIA live regions or post accessibility notifications when the state is entered. The text is a template hint, not a final user-facing string — platform implementations localize and adapt it.
+
+**RECOMMENDED:** Phrasing SHOULD be concise (under 10 words) and describe the transition, not the resulting state. Prefer `"Dialog opened"` over `"The dialog is now open"`.
+
+### `communicates`
+
+A string describing the semantic state the component is in after the transition. Platform adapters use this to set `aria-*` state attributes or equivalent:
+
+| Example value | ARIA equivalent        |
+| ------------- | ---------------------- |
+| `"selected"`  | `aria-selected="true"` |
+| `"expanded"`  | `aria-expanded="true"` |
+| `"checked"`   | `aria-checked="true"`  |
+| `"invalid"`   | `aria-invalid="true"`  |
+| `"required"`  | `aria-required="true"` |
+| `"busy"`      | `aria-busy="true"`     |
+| `"pressed"`   | `aria-pressed="true"`  |
+| `"disabled"`  | `aria-disabled="true"` |
+
+The ARIA mapping column is informative; the foundation layer declares semantic meaning only.
+
+### `blocksInteraction`
+
+A boolean declaring whether this state prevents all user interaction with the component.
+
+* `true` — the component cannot be interacted with while in this state (e.g., `disabled`, `loading`); platform adapters SHOULD set `aria-disabled` or equivalent.
+* `false` or absent — user interaction is not blocked by this state.
+
+## Example
+
+A `button` component with a complete accessibility declaration and two states carrying state-level accessibility fields:
+
+```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" },
+      { "criterion": "1.4.3", "level": "AA", "title": "Contrast (Minimum)" }
+    ]
+  },
+  "states": [
+    {
+      "name": "disabled",
+      "trigger": { "type": "prop", "prop": "disabled" },
+      "announce": "Button disabled",
+      "communicates": "disabled",
+      "blocksInteraction": true
+    },
+    {
+      "name": "loading",
+      "trigger": { "type": "prop", "prop": "pending" },
+      "announce": "Loading",
+      "communicates": "busy",
+      "blocksInteraction": true
+    }
+  ]
+}
+```
+
+## SPEC rules
+
+| Rule ID  | Severity | Name                       | Assert                                                                                 |
+| -------- | -------- | -------------------------- | -------------------------------------------------------------------------------------- |
+| SPEC-030 | warning  | accessibility-empty        | When `accessibility` is declared with no fields, the object provides no semantic value |
+| SPEC-031 | warning  | accessibility-wcag-missing | When `accessibility` is declared, `wcag` SHOULD list at least one criterion            |
+
+Both rules are `warning` severity — they do not block validation. Rules are defined in `rules/rules.yaml` and implemented in the SDK in Phase 7.4.

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."
 }
 ```