Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

test(a11y): reusable switch-pattern accessibility contract, bound to Switch (#6115)

Cindy Zhangd41bbfa92726
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 45f040c4bb..8430331389 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -163,7 +163,15 @@ jobs:
fi
FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
CHANGED=$(printf '%s\n' "$FILES" | grep -E '^packages/(core|lab)/src/' | grep -v -E '(hooks|theme|utils|i18n|__tests__)/' | head -1 || true)
- echo "has_components=$( [ -n "$CHANGED" ] && echo true || echo false )" >> "$GITHUB_OUTPUT"
+ # The shared accessibility spec-test contracts gate inside pr-a11y,
+ # and their component bindings live under `__tests__/` — which the
+ # filter above deliberately excludes. Without this the contract could
+ # be changed, or a binding broken, with the only job that runs it
+ # skipped. Stories are in scope too: the Chromium bindings drive
+ # checked-in stories by id, so renaming or deleting one breaks the
+ # contract run and nothing else would notice.
+ A11Y=$(printf '%s\n' "$FILES" | grep -E '^internal/a11y-spec/|^packages/[^/]+/src/.*\.a11y\.|^apps/storybook/stories/|^playwright\.config\.ts$' | head -1 || true)
+ echo "has_components=$( { [ -n "$CHANGED" ] || [ -n "$A11Y" ]; } && echo true || echo false )" >> "$GITHUB_OUTPUT"
# One classifier owns the release-channel rule. It reads each
# package's `astryx.canaryOnly` metadata rather than hard-coding
@@ -384,6 +392,13 @@ jobs:
if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true'
run: pnpm -F @astryxdesign/core typecheck
+ # The accessibility spec-test contracts are consumed as TypeScript source
+ # by Vitest and Playwright, and neither runner typechecks. This is the
+ # only gate over them.
+ - name: Typecheck accessibility spec-test contracts
+ if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true'
+ run: pnpm -F @astryxdesign/a11y-spec typecheck
+
- name: Build Storybook
if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true'
run: pnpm -F @astryxdesign/storybook build
@@ -668,6 +683,16 @@ jobs:
- name: Run story play guard
run: node .github/scripts/story-play-guard.js --storybook-dir apps/storybook/dist
+ # The reusable accessibility spec-test contracts (internal/a11y-spec) and
+ # the component bindings that adopt them. jsdom cannot compute a role or
+ # an accessible name, resolve a real tab sequence, or turn a key press
+ # into an activation, so those expectations are reported `unrun` in the
+ # unit lane and proven here or not at all. Hosted with the sibling
+ # Chromium guards for the same reason they are: pr-a11y is the blocking
+ # job that runs whenever components change.
+ - name: Run accessibility spec-test contracts
+ run: pnpm test:a11y-contract
+
# The layer order Astryx promises is Astryx < theme < product, and which
# declaration paints is a cascade fact no jsdom test can settle: the build has
# been wrong in both directions inside one week — unsplit, so StyleX outranked
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 46f983675b..32797bd17a 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -159,6 +159,12 @@ jobs:
- name: Typecheck core (including tests)
run: pnpm -F @astryxdesign/core typecheck
+ # The accessibility spec-test contracts are consumed as TypeScript source
+ # by Vitest and Playwright, and neither runner typechecks. This is the
+ # only gate over them.
+ - name: Typecheck accessibility spec-test contracts
+ run: pnpm -F @astryxdesign/a11y-spec typecheck
+
# Historical job name, kept because `deploy` gates the publish on
# `needs.test.result == 'success'`. Every lane must pass for that to hold, so
# this asserts all three rather than merely depending on them.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 85936031a4..bb26b499fc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -448,6 +448,32 @@ When the audit reports baseline entries as "resolved", delete them from
> component is accessible — keyboard flows, focus order, screen-reader
> semantics, and contrast in context still need manual checks.
+### Accessibility spec-test contracts
+
+axe finds broad markup violations; it does not know that a switch has to turn
+back off. The reusable **accessibility spec tests** in
+[`internal/a11y-spec/`](internal/a11y-spec/README.md) encode one adopted
+WAI-ARIA APG pattern as a standards-traceable contract, and components bind to
+it. Each expectation names the WCAG success criterion or APG requirement it
+comes from, the evidence layer that can observe it, and whether it gates.
+
+They run in two lanes, and the split is the point: jsdom proves DOM-layer facts
+in `pnpm test`, and everything that needs a computed accessibility tree, real
+focus, or real activation is reported `unrun` there and proven in Chromium.
+
+```bash
+# One-time setup
+pnpm storybook:build
+npx playwright install chromium
+
+pnpm test:a11y-contract # the Chromium lane (also runs inside pr-a11y)
+```
+
+Adopting the pattern in a new component means binding to the existing contract,
+not copying its assertions — see the package README and
+[`docs/specs/AST-020`](docs/specs/AST-020/spec.md) /
+[`docs/specs/AST-021`](docs/specs/AST-021/spec.md).
+
### RTL audits
PRs that touch components also run an RTL audit (`pr-rtl`), scoped to the
diff --git a/apps/storybook/stories/Switch.stories.tsx b/apps/storybook/stories/Switch.stories.tsx
index 704d0c04f0..969345273a 100644
--- a/apps/storybook/stories/Switch.stories.tsx
+++ b/apps/storybook/stories/Switch.stories.tsx
@@ -568,3 +568,55 @@ export const DisabledWithMessage: Story = {
disabledMessage: 'Notifications are turned off org-wide',
},
};
+
+// The owner changes the value, not the user. A settings page does this when a
+// saved value arrives, or when another control implies this one. The switch
+// still reports the new state, and is still operable afterwards.
+export const ControlledUpdate: Story = {
+ render: args => {
+ const [value, setValue] = useState(false);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'flex-start',
+ gap: '12px',
+ }}>
+ <Switch
+ {...restArgs}
+ value={value}
+ onChange={checked => setValue(checked)}
+ />
+ <button type="button" onClick={() => setValue(true)}>
+ Turn on remotely
+ </button>
+ </div>
+ );
+ },
+ args: {
+ label: 'Sync photos',
+ },
+};
+
+// Waiting on the change it just started. The switch stays focusable and reports
+// itself busy, and activation is blocked until the change settles, so a second
+// press cannot queue a second change.
+export const Loading: Story = {
+ render: args => {
+ const [value, setValue] = useState(args.value ?? false);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <Switch
+ {...restArgs}
+ value={value}
+ onChange={checked => setValue(checked)}
+ />
+ );
+ },
+ args: {
+ label: 'Sync photos',
+ isLoading: true,
+ },
+};
diff --git a/internal/README.md b/internal/README.md
index 5a16cd38c1..101fd8b07c 100644
--- a/internal/README.md
+++ b/internal/README.md
@@ -4,8 +4,9 @@ Internal tooling packages not published to npm.
<!-- SYNC: When files in this directory change, update this document. -->
-| Directory | Role | Purpose |
-| ------------- | ------- | ------------------------------------------------------------ |
-| `scripts/` | Tooling | One-off automation scripts (Crowdin screenshot upload, etc.) |
-| `test-utils/` | Testing | Shared testing utilities and setup for Vitest |
-| `vibe-tests/` | Testing | LLM vibeability test harness for component system |
+| Directory | Role | Purpose |
+| ------------- | ------- | ----------------------------------------------------------------------- |
+| `a11y-spec/` | Testing | Reusable accessibility spec-test contracts and their evidence harnesses |
+| `scripts/` | Tooling | One-off automation scripts (Crowdin screenshot upload, etc.) |
+| `test-utils/` | Testing | Shared testing utilities and setup for Vitest |
+| `vibe-tests/` | Testing | LLM vibeability test harness for component system |
diff --git a/internal/a11y-spec/README.md b/internal/a11y-spec/README.md
new file mode 100644
index 0000000000..fdeded284b
--- /dev/null
+++ b/internal/a11y-spec/README.md
@@ -0,0 +1,157 @@
+# @astryxdesign/a11y-spec
+
+Reusable accessibility spec tests: one standards-traceable contract per adopted
+widget pattern, bound to the components that implement it. **Internal and
+unpublished.**
+
+Authored under [`docs/specs/AST-020`](../../docs/specs/AST-020/spec.md)
+(how a contract is written) and
+[`docs/specs/AST-021`](../../docs/specs/AST-021/spec.md)
+(how existing component tests migrate into one). Read those first; this file
+explains the code that implements them.
+
+## Why a contract instead of more component tests
+
+Every component that adopts the APG switch pattern owes the same things: the
+control is reported as a switch, it has a name that does not change when the
+state does, its on/off state is exposed and matches what is rendered, pointer
+and keyboard both turn it on and back off, a press slid off and released
+elsewhere is taken back, focus stays put when the state changes, and focus can
+reach the control and leave it. Writing that per component means reinterpreting
+WCAG and the APG each time, and the interpretations drift.
+
+So the pattern is written once, as data, and components bind to it. A binding
+says which states it has and what each state is supposed to be; the contract
+asks the browser what it actually exposes.
+
+## Shape
+
+```
+src/
+├── contract.ts Expectation, PatternContract, definePattern (the schema gate)
+├── checklist.ts the completeness dimensions every pattern must answer
+├── harness.ts the Harness/Subject seam and the evidence-layer vocabulary
+├── run.ts runBinding — applicability, unrun layers, known failures
+├── report.ts separate facts, and the gate over them
+├── harness/
+│ ├── jsdom.ts observes unit + DOM. Refuses everything above.
+│ └── chromium.ts observes DOM + accessibility tree + real browser.
+├── storybook.ts a static server over a built Storybook, for the browser lane
+└── patterns/
+ ├── switch.ts the switch pattern
+ ├── switch.fixtures.ts conforming + deliberately violating fixtures
+ ├── switch.jsdom.test.ts the contract's own proof, DOM layer
+ └── switch.chromium.spec.ts the same proof in a real engine
+```
+
+## Evidence layers are the load-bearing idea
+
+An expectation names the layer that characterizes its claim, plus — in
+`alsoNeeds` — any further layer its own body reads. An interaction expectation
+is the usual case: "clicking turns it on" is a real-browser claim, but reading
+the resulting state is an accessibility-tree observation, so it needs both. A
+harness declares which layers it can observe, and the runner will not run an
+expectation whose layers a harness cannot all see — it reports `unrun`, naming
+the ones that were out of reach.
+
+That is why the jsdom lane is small. jsdom renders markup; it does not compute
+an accessibility tree, resolve a real tab sequence, or turn a key press into an
+activation. Reporting those as passes because the attributes look right is the
+exact failure [`AST-009`](../../docs/specs/AST-009/spec.md) is written against,
+so this package reports them as unrun instead and proves them in Chromium.
+
+| Status | Meaning | Gates |
+| ----------------- | ----------------------------------------------------- | ---------------------------------- |
+| `pass` | the outcome was observed | — |
+| `fail` | the outcome was absent | when the expectation is `required` |
+| `known-failure` | the exact recorded historical failure, still failing | no |
+| `unexpected-pass` | a recorded failure that now passes; delete the record | yes |
+| `not-applicable` | this state cannot exercise the outcome | — |
+| `unrun` | a layer this expectation reads was out of reach here | — |
+
+No status is averaged into another, and there is no score. A pattern with one
+required failure is not "mostly conformant" (AST-021 FR11).
+
+## Authoring a pattern
+
+1. Read the APG pattern and the WCAG success criteria it supports.
+2. Write the expectations. Each needs a stable id, a user outcome in plain
+ language, exact sources, an applicability condition, an evidence layer (plus
+ `alsoNeeds` for any further layer its body reads), and an enforcement class.
+ `definePattern` refuses anything less.
+3. Answer every completeness dimension in `checklist.ts` — either an expectation
+ names it in `covers`, or the pattern exempts it with an owner, a verification
+ method, and a real reason. A criterion the pattern owns only part of takes
+ both: the expectation, plus an exemption marked `coversRemainderOnly` naming
+ who holds the rest, so the encoded half never implies the whole. Reports
+ print those as `part-encoded … — remainder → owner`, distinct from a plain
+ `exempt`. `unansweredDimensions` lists what is left, and the pattern's suite
+ asserts that list is empty.
+
+ Applicability is normally declared, in `appliesWhen`, where a reader can see
+ it. When it can only be discovered from the page — 2.5.3 has nothing to
+ compare when nothing is rendered visibly — call `notApplicable(reason)` from
+ the run. It reports `not-applicable` with that reason; returning early would
+ report a pass, which claims an outcome was observed.
+
+4. Write a conforming fixture per state and a violating fixture per expectation,
+ then prove each expectation fails against its own violation. An expectation
+ nobody has watched fail is a claim, not a check (AST-020 FR11).
+
+`required` is earned by a directly applicable WCAG 2.2 A/AA criterion, or by a
+current Astryx record adopting the outcome — never by how easy the check was to
+write. "Directly applicable" means the criterion is the expectation's PRIMARY
+source: a supporting citation further down the list is not adoption, or any
+expectation could buy a gate by appending a plausible criterion. Everything else
+is `advisory` and has to say why.
+
+## Binding a component
+
+A binding lives with the component:
+
+```
+packages/core/src/Switch/__tests__/
+├── Switch.a11y.states.ts which states exist and what each declares
+├── Switch.a11y.known-failures.ts what does not work yet, exactly
+├── Switch.a11y.test.tsx the jsdom lane
+└── Switch.a11y.chromium.spec.ts the Chromium lane, over checked-in stories
+```
+
+The binding designates its own subject — by role for a conforming component, by
+a fixture-owned hook for a deliberately violating fixture — so a mutation flips
+exactly the expectation under test instead of making the subject unfindable.
+
+Component-specific behaviour does not move: callbacks, form data, composition,
+and styling stay in the component's own suite (AST-021 FR5).
+
+## Known failures
+
+A known failure names one expectation, one binding, one state, one evidence
+layer, the user impact, a public issue, and why the migration is not the place
+to fix it. It still runs, it still fails, and it is reported as debt. A
+different message, another state, or a wider failure fails the build anyway, and
+an expectation that starts passing is reported as an unexpected pass so the
+stale record is deleted (AST-021 FR8–FR10).
+
+## Running
+
+```bash
+# jsdom lane — part of `pnpm test`
+pnpm vitest run --project node internal/a11y-spec
+pnpm vitest run --project ui packages/core/src/Switch
+
+# Chromium lane — needs a browser and a built Storybook
+pnpm storybook:build
+npx playwright install chromium
+pnpm test:a11y-contract
+```
+
+## What this package does not claim
+
+It does not report what an assistive technology says. Speech, braille,
+announcement timing and order, virtual-cursor entry, and known AT/browser
+divergence are the real-AT layer, and they are governed by
+[`AST-009`](../../docs/specs/AST-009/spec.md), not by anything here. It also
+does not replace axe, the visual gate, or manual review: contrast, target size,
+forced colors, and motion are measured from pixels, and every pattern records
+who owns them instead of pretending otherwise.
diff --git a/internal/a11y-spec/package.json b/internal/a11y-spec/package.json
new file mode 100644
index 0000000000..782bed6ed8
--- /dev/null
+++ b/internal/a11y-spec/package.json
@@ -0,0 +1,21 @@
+{
+ "name": "@astryxdesign/a11y-spec",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "description": "Internal: reusable accessibility spec-test contracts and their evidence harnesses. Never published.",
+ "main": "./src/index.ts",
+ "exports": {
+ ".": "./src/index.ts",
+ "./chromium": "./src/harness/chromium.ts",
+ "./storybook": "./src/storybook.ts"
+ },
+ "scripts": {
+ "typecheck": "tsc --project tsconfig.json --noEmit"
+ },
+ "devDependencies": {
+ "@playwright/test": "^1.61.1",
+ "typescript": "^6.0.3",
+ "vitest": "^4.1.9"
+ }
+}
diff --git a/internal/a11y-spec/src/checklist.ts b/internal/a11y-spec/src/checklist.ts
new file mode 100644
index 0000000000..4c3e8f0082
--- /dev/null
+++ b/internal/a11y-spec/src/checklist.ts
@@ -0,0 +1,245 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file checklist.ts
+ * @input None (pure declarations)
+ * @output CHECKLIST_DIMENSIONS — the completeness review every pattern answers
+ * in full — and the disposition shape a pattern answers it with.
+ * @position Consumed by ./contract.ts, which refuses a pattern that leaves a
+ * dimension unanswered.
+ *
+ * The rows are the source map in `docs/specs/AST-020/spec.md` FR10, plus the
+ * component-owned outcomes that record tells an author to add on top of it:
+ * forced colors, reduced motion, the adopted APG interaction set, and the
+ * assistive-technology-facing strings the public Accessibility Checklist asks
+ * for.
+ *
+ * A dimension is answered in exactly one of two ways (FR5):
+ *
+ * - encoded — one or more expectations name it in their `covers` list; or
+ * - exempt — this pattern does not own it, and the answer names who does and
+ * how it is actually verified.
+ *
+ * "Not applicable" on its own is not an answer, and neither is leaving a row
+ * out. That is the failure mode the record is written against: a dimension that
+ * disappears silently reads, later, exactly like one that was considered.
+ *
+ * SYNC: When a dimension is added here, every pattern contract must answer it —
+ * `definePattern` will fail until it does.
+ */
+
+/**
+ * A dimension this pattern does not own. An exemption is an answer, so it has
+ * to say who does own the outcome and how that owner actually verifies it.
+ */
+export interface ChecklistExemption {
+ /** Who owns the outcome instead — a record id, a component, or a role. */
+ readonly owner: string;
+ /** How it is actually verified. A method, not a promise. */
+ readonly verifiedBy: string;
+ /** Why this pattern is not the owner. */
+ readonly reason: string;
+ /**
+ * Set when an expectation encodes PART of this dimension and the owner named
+ * here holds the rest. Without it a dimension has exactly one answer; with
+ * it, the encoded part and the unowned part are both visible instead of the
+ * encoding quietly implying the whole criterion is covered.
+ */
+ readonly coversRemainderOnly?: boolean;
+}
+
+export interface ChecklistDimension {
+ readonly id: string;
+ /** The normative source the row comes from. */
+ readonly source: string;
+ /** The outcome to consider. */
+ readonly outcome: string;
+ /** Where ownership usually sits. */
+ readonly usualOwnership: string;
+}
+
+export const CHECKLIST_DIMENSIONS = [
+ {
+ id: '1.1.1-non-text-content',
+ source: 'WCAG 2.2 1.1.1 Non-text Content (A)',
+ outcome:
+ 'Informative non-text content has an equivalent alternative; decorative content is ignored.',
+ usualOwnership: 'Component or content',
+ },
+ {
+ id: '1.3.1-info-and-relationships',
+ source: 'WCAG 2.2 1.3.1 Info and Relationships (A)',
+ outcome:
+ 'Visual structure and relationships are programmatically available.',
+ usualOwnership: 'Component or composition',
+ },
+ {
+ id: '1.3.2-meaningful-sequence',
+ source: 'WCAG 2.2 1.3.2 Meaningful Sequence (A)',
+ outcome: 'Programmatic reading sequence preserves meaning.',
+ usualOwnership: 'Component or composition',
+ },
+ {
+ id: '1.4.1-use-of-color',
+ source: 'WCAG 2.2 1.4.1 Use of Color (A)',
+ outcome: 'Color is not the only way to convey information or state.',
+ usualOwnership: 'Component, theme, and caller content',
+ },
+ {
+ id: '1.4.3-contrast-minimum',
+ source: 'WCAG 2.2 1.4.3 Contrast (Minimum) (AA)',
+ outcome: 'Text and images of text meet the required contrast.',
+ usualOwnership: 'Component and theme',
+ },
+ {
+ id: '1.4.11-non-text-contrast',
+ source: 'WCAG 2.2 1.4.11 Non-text Contrast (AA)',
+ outcome:
+ 'Controls, states, and meaningful graphics meet non-text contrast.',
+ usualOwnership: 'Component and theme',
+ },
+ {
+ id: '2.1.1-keyboard',
+ source: 'WCAG 2.2 2.1.1 Keyboard (A)',
+ outcome: 'Every component-owned function is operable by keyboard.',
+ usualOwnership: 'Component',
+ },
+ {
+ id: '2.1.2-no-keyboard-trap',
+ source: 'WCAG 2.2 2.1.2 No Keyboard Trap (A)',
+ outcome:
+ 'Keyboard focus can leave any component unless the user has a documented exit.',
+ usualOwnership: 'Component or composition',
+ },
+ {
+ id: '2.4.2-page-titled',
+ source: 'WCAG 2.2 2.4.2 Page Titled (A)',
+ outcome: 'A page has a descriptive title.',
+ usualOwnership: 'Page only',
+ },
+ {
+ id: '2.4.3-focus-order',
+ source: 'WCAG 2.2 2.4.3 Focus Order (A)',
+ outcome: 'Sequential focus preserves meaning and operation.',
+ usualOwnership: 'Component or composition',
+ },
+ {
+ id: '2.4.4-link-purpose',
+ source: 'WCAG 2.2 2.4.4 Link Purpose (In Context) (A)',
+ outcome: "A link's purpose is determinable.",
+ usualOwnership: 'Component and caller content',
+ },
+ {
+ id: '2.4.6-headings-and-labels',
+ source: 'WCAG 2.2 2.4.6 Headings and Labels (AA)',
+ outcome: 'Headings and labels describe their topic or purpose.',
+ usualOwnership: 'Component and caller content',
+ },
+ {
+ id: '2.4.7-focus-visible',
+ source: 'WCAG 2.2 2.4.7 Focus Visible (AA)',
+ outcome: 'Keyboard focus has a visible indicator.',
+ usualOwnership: 'Component and theme',
+ },
+ {
+ id: '2.4.11-focus-not-obscured',
+ source: 'WCAG 2.2 2.4.11 Focus Not Obscured (Minimum) (AA)',
+ outcome:
+ 'Focused content is not entirely hidden by author-created content.',
+ usualOwnership: 'Component or composition',
+ },
+ {
+ id: '2.5.2-pointer-cancellation',
+ source: 'WCAG 2.2 2.5.2 Pointer Cancellation (A)',
+ outcome:
+ 'A single-pointer function does not complete on the down-event, or the press can be aborted or undone.',
+ usualOwnership: 'Component',
+ },
+ {
+ id: '2.5.3-label-in-name',
+ source: 'WCAG 2.2 2.5.3 Label in Name (A)',
+ outcome:
+ 'The accessible name contains the text of the visible label, so speech input and speech output agree.',
+ usualOwnership: 'Component and caller content',
+ },
+ {
+ id: '2.5.8-target-size',
+ source: 'WCAG 2.2 2.5.8 Target Size (Minimum) (AA)',
+ outcome: 'Pointer targets meet the minimum size or an allowed exception.',
+ usualOwnership: 'Component or composition',
+ },
+ {
+ id: '3.1.1-language-of-page',
+ source: 'WCAG 2.2 3.1.1 Language of Page (A)',
+ outcome: 'The page language is programmatically available.',
+ usualOwnership: 'Page only',
+ },
+ {
+ id: '3.2.2-on-input',
+ source: 'WCAG 2.2 3.2.2 On Input (A)',
+ outcome:
+ 'Changing a control’s setting does not automatically change the context unless the user was told it would.',
+ usualOwnership: 'Component and caller content',
+ },
+ {
+ id: '3.2.4-consistent-identification',
+ source: 'WCAG 2.2 3.2.4 Consistent Identification (AA)',
+ outcome: 'Repeated functions are identified consistently.',
+ usualOwnership: 'System, component, and caller content',
+ },
+ {
+ id: '3.3.1-error-identification',
+ source: 'WCAG 2.2 3.3.1 Error Identification (A)',
+ outcome:
+ 'An automatically detected input error is identified, and the error is described to the user in text.',
+ usualOwnership: 'Component and composition',
+ },
+ {
+ id: '3.3.2-labels-or-instructions',
+ source: 'WCAG 2.2 3.3.2 Labels or Instructions (A)',
+ outcome: 'Inputs have persistent labels or needed instructions.',
+ usualOwnership: 'Component and caller content',
+ },
+ {
+ id: '4.1.2-name-role-value',
+ source: 'WCAG 2.2 4.1.2 Name, Role, Value (A)',
+ outcome:
+ 'Name, role, state, value, and changes are programmatically available.',
+ usualOwnership: 'Component',
+ },
+ {
+ id: '4.1.3-status-messages',
+ source: 'WCAG 2.2 4.1.3 Status Messages (AA)',
+ outcome: 'Status changes are exposed without moving focus.',
+ usualOwnership: 'Component or composition',
+ },
+ {
+ id: 'apg-interaction',
+ source: 'The adopted WAI-ARIA APG pattern',
+ outcome:
+ "The pattern's roles, states, properties, and keyboard interaction are implemented as adopted.",
+ usualOwnership: 'Component',
+ },
+ {
+ id: 'forced-colors',
+ source: 'Astryx Accessibility Checklist — Forced colors',
+ outcome:
+ 'Painted state survives `forced-colors: active` through system-colour fallbacks.',
+ usualOwnership: 'Component and theme',
+ },
+ {
+ id: 'reduced-motion',
+ source: 'Astryx Accessibility Checklist — Reduced motion',
+ outcome: 'Entry/exit motion is guarded by `prefers-reduced-motion`.',
+ usualOwnership: 'Component and theme',
+ },
+ {
+ id: 'at-facing-strings',
+ source: 'Astryx Accessibility Checklist — i18n',
+ outcome:
+ 'Every assistive-technology-facing string is translated like visible text.',
+ usualOwnership: 'Component',
+ },
+] as const satisfies readonly ChecklistDimension[];
+
+export type ChecklistDimensionId = (typeof CHECKLIST_DIMENSIONS)[number]['id'];
diff --git a/internal/a11y-spec/src/contract.test.ts b/internal/a11y-spec/src/contract.test.ts
new file mode 100644
index 0000000000..d88ebc608a
--- /dev/null
+++ b/internal/a11y-spec/src/contract.test.ts
@@ -0,0 +1,292 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contract.test.ts
+ * @input Uses ./contract and ./checklist
+ * @output Proof that `definePattern` refuses a contract nobody could audit.
+ * @position Schema self-test. Each case here is a way an expectation could look
+ * finished and prove nothing.
+ *
+ * `docs/specs/AST-020/spec.md` FR4, FR5, FR6, and FR9. The record's own failure
+ * expectation is "a check lacks a source or layer, passes from an unsupported
+ * harness, depends on private markup, or one-way behavior hides a reverse-path
+ * failure" — the first two are refused here at construction.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+ definePattern,
+ unansweredDimensions,
+ type Expectation,
+ type PatternContract,
+} from './contract';
+import {CHECKLIST_DIMENSIONS} from './checklist';
+import type {EvidenceLayer} from './harness';
+
+const WCAG_4_1_2 = {
+ standard: 'wcag',
+ id: '4.1.2',
+ name: 'Name, Role, Value',
+ level: 'A',
+ url: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+} as const;
+
+const APG_SOMETHING = {
+ standard: 'apg',
+ pattern: 'probe',
+ requirement: 'The probe does the probe thing.',
+ url: 'https://example.invalid/probe',
+} as const;
+
+function expectation(
+ overrides: Partial<Expectation<unknown>> = {},
+): Expectation<unknown> {
+ return {
+ id: 'probe.outcome.observed',
+ outcome: 'The probe outcome happens.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {condition: 'always', test: () => true},
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async () => {},
+ ...overrides,
+ };
+}
+
+function pattern(
+ overrides: Partial<PatternContract<unknown>> = {},
+): () => PatternContract<unknown> {
+ return () =>
+ definePattern<unknown>({
+ pattern: 'probe',
+ url: 'https://example.invalid/probe',
+ scope: 'A stub pattern.',
+ expectations: [expectation()],
+ exemptions: {},
+ ...overrides,
+ });
+}
+
+describe('definePattern', () => {
+ it('accepts a traceable, applicable, layered, enforceable expectation', () => {
+ expect(pattern()).not.toThrow();
+ });
+
+ it('refuses an expectation with no user outcome', () => {
+ expect(pattern({expectations: [expectation({outcome: ' '})]})).toThrow(
+ /states no user outcome/,
+ );
+ });
+
+ it('refuses an expectation that cites nothing', () => {
+ expect(
+ pattern({
+ expectations: [
+ expectation({
+ sources: [] as unknown as Expectation<unknown>['sources'],
+ }),
+ ],
+ }),
+ ).toThrow(/cites no normative source/);
+ });
+
+ it('refuses an APG-primary expectation that names no WCAG outcome', () => {
+ expect(
+ pattern({expectations: [expectation({sources: [APG_SOMETHING]})]}),
+ ).toThrow(/must name the WCAG 2.2 outcome it supports/);
+ });
+
+ it('accepts an APG-primary expectation that names the WCAG outcome and reports', () => {
+ expect(
+ pattern({
+ expectations: [
+ expectation({
+ sources: [APG_SOMETHING, WCAG_4_1_2],
+ wcagOutcome: 'The probe state is programmatically available.',
+ enforcement: 'advisory',
+ advisoryBecause: 'Nothing current adopts the probe outcome.',
+ }),
+ ],
+ }),
+ ).not.toThrow();
+ });
+
+ it('refuses to gate on an APG requirement propped up by a supporting citation', () => {
+ // FR9 wants a DIRECTLY applicable criterion. Without this, any expectation
+ // could buy `required` by appending a plausible criterion to its list.
+ expect(
+ pattern({
+ expectations: [
+ expectation({
+ sources: [APG_SOMETHING, WCAG_4_1_2],
+ wcagOutcome: 'The probe state is programmatically available.',
+ enforcement: 'required',
+ }),
+ ],
+ }),
+ ).toThrow(/its primary source is neither/);
+ });
+
+ it('refuses an expectation with no applicability condition', () => {
+ expect(
+ pattern({
+ expectations: [
+ expectation({appliesWhen: {condition: '', test: () => true}}),
+ ],
+ }),
+ ).toThrow(/states no applicability condition/);
+ });
+
+ it('refuses an unknown evidence layer', () => {
+ expect(
+ pattern({
+ expectations: [
+ expectation({
+ evidenceLayer: 'vibes' as Expectation<unknown>['evidenceLayer'],
+ }),
+ ],
+ }),
+ ).toThrow(/unknown evidence layer/);
+ });
+
+ it('refuses an unknown layer in alsoNeeds', () => {
+ expect(
+ pattern({
+ expectations: [
+ expectation({
+ alsoNeeds: ['vibes'] as unknown as readonly EvidenceLayer[],
+ }),
+ ],
+ }),
+ ).toThrow(/names an unknown evidence layer "vibes"/);
+ });
+
+ it("refuses alsoNeeds that repeats the expectation's own layer", () => {
+ expect(
+ pattern({expectations: [expectation({alsoNeeds: ['dom']})]}),
+ ).toThrow(/repeats its own evidence layer/);
+ });
+
+ it('refuses a required expectation nothing has adopted', () => {
+ expect(
+ pattern({
+ expectations: [
+ expectation({
+ sources: [APG_SOMETHING],
+ wcagOutcome: 'The probe state is programmatically available.',
+ enforcement: 'required',
+ }),
+ ],
+ }),
+ ).toThrow(/its primary source is neither/);
+ });
+
+ it('refuses an advisory expectation that does not say why it is advisory', () => {
+ expect(
+ pattern({expectations: [expectation({enforcement: 'advisory'})]}),
+ ).toThrow(/does not say why the outcome is not adopted as a gate/);
+ });
+
+ it('refuses an expectation that carries no completeness dimension', () => {
+ expect(pattern({expectations: [expectation({covers: []})]})).toThrow(
+ /carries no completeness dimension/,
+ );
+ });
+
+ it('refuses a dimension that is claimed twice', () => {
+ expect(
+ pattern({
+ exemptions: {
+ '4.1.2-name-role-value': {
+ owner: 'someone else',
+ verifiedBy: 'a different suite',
+ reason: 'Because the other suite already reads it.',
+ },
+ },
+ }),
+ ).toThrow(/both encoded by probe.outcome.observed and exempted/);
+ });
+
+ it('lets a dimension be part-encoded when the exemption owns the remainder', () => {
+ expect(
+ pattern({
+ exemptions: {
+ '4.1.2-name-role-value': {
+ owner: 'the caller',
+ verifiedBy: 'integration review',
+ reason: 'Half of this criterion is not visible to one component.',
+ coversRemainderOnly: true,
+ },
+ },
+ }),
+ ).not.toThrow();
+ });
+
+ it('refuses a remainder-only exemption when nothing encodes the rest', () => {
+ expect(
+ pattern({
+ expectations: [expectation({covers: ['2.1.1-keyboard']})],
+ exemptions: {
+ '4.1.2-name-role-value': {
+ owner: 'the caller',
+ verifiedBy: 'integration review',
+ reason: 'Half of this criterion is not visible to one component.',
+ coversRemainderOnly: true,
+ },
+ },
+ }),
+ ).toThrow(/no expectation encodes any of it/);
+ });
+
+ it('refuses an exemption with no owner', () => {
+ expect(
+ pattern({
+ expectations: [expectation({covers: ['2.1.1-keyboard']})],
+ exemptions: {
+ '4.1.2-name-role-value': {
+ owner: '',
+ verifiedBy: 'a different suite',
+ reason: 'Because the other suite already reads it.',
+ },
+ },
+ }),
+ ).toThrow(/names no owner/);
+ });
+
+ it('refuses "not applicable" as an exemption reason', () => {
+ expect(
+ pattern({
+ expectations: [expectation({covers: ['2.1.1-keyboard']})],
+ exemptions: {
+ '4.1.2-name-role-value': {
+ owner: 'someone else',
+ verifiedBy: 'a different suite',
+ reason: 'N/A',
+ },
+ },
+ }),
+ ).toThrow(/FR5 forbids a generic escape hatch/);
+ });
+
+ it('refuses a duplicate expectation id', () => {
+ expect(pattern({expectations: [expectation(), expectation()]})).toThrow(
+ /duplicate expectation id/,
+ );
+ });
+
+ it('refuses an id that does not belong to the pattern', () => {
+ expect(
+ pattern({expectations: [expectation({id: 'other.outcome.observed'})]}),
+ ).toThrow(/does not belong to pattern probe/);
+ });
+});
+
+describe('unansweredDimensions', () => {
+ it('lists every dimension the pattern has neither encoded nor exempted', () => {
+ const contract = pattern()();
+ const unanswered = unansweredDimensions(contract);
+ expect(unanswered).not.toContain('4.1.2-name-role-value');
+ expect(unanswered).toHaveLength(CHECKLIST_DIMENSIONS.length - 1);
+ });
+});
diff --git a/internal/a11y-spec/src/contract.ts b/internal/a11y-spec/src/contract.ts
new file mode 100644
index 0000000000..c639f262aa
--- /dev/null
+++ b/internal/a11y-spec/src/contract.ts
@@ -0,0 +1,392 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contract.ts
+ * @input Uses ./checklist (completeness dimensions) and ./harness (evidence layers)
+ * @output The accessibility spec-test contract vocabulary — NormativeSource,
+ * Expectation, PatternContract — plus `definePattern`, the constructor that
+ * refuses a contract which is not traceable, applicable, layered, and
+ * enforceable, and `unansweredDimensions`, the completeness check.
+ * @position Foundation of @astryxdesign/a11y-spec. Every pattern, binding,
+ * runner, and report is expressed in these types.
+ *
+ * The rules encoded here come from the accepted accessibility spec-test
+ * authoring record, `docs/specs/AST-020/spec.md`:
+ *
+ * - FR1 a WCAG 2.2 A/AA criterion is the conformance basis; an APG-primary
+ * expectation must still name the WCAG outcome it supports.
+ * - FR4 every expectation carries a stable id, a user outcome, an exact
+ * normative source, applicability, an evidence layer, and enforcement,
+ * and exposes its id and source in test names and failure output.
+ * - FR5 every checklist dimension is either encoded or exempted with a named
+ * owner; silence is not an exemption and neither is "not applicable".
+ * - FR6 evidence layers keep distinct proof boundaries.
+ * - FR9 enforcement is separate from severity and from tool coverage.
+ * - FR14 ids survive refactors.
+ *
+ * FR5 is split across two places on purpose. The half a single expectation can
+ * break — an unknown dimension, an exemption with no owner, a dimension claimed
+ * twice — is refused here, at construction. Whether the pattern as a whole has
+ * answered every dimension is `unansweredDimensions`, asserted by the pattern's
+ * own suite: a contract under construction is incomplete by definition, and a
+ * constructor that throws on it cannot be developed one expectation at a time.
+ *
+ * SYNC: When the shape of an expectation changes, update
+ * - /internal/a11y-spec/README.md (the authoring guide)
+ * - /internal/a11y-spec/src/patterns/switch.ts (the reference pattern)
+ */
+
+import {
+ CHECKLIST_DIMENSIONS,
+ type ChecklistDimensionId,
+ type ChecklistExemption,
+} from './checklist';
+import {EVIDENCE_LAYERS, type EvidenceLayer, type Harness} from './harness';
+
+/** How a failing expectation is treated by a gate (AST-020 FR9). */
+export type Enforcement = 'required' | 'advisory';
+
+/** A WCAG 2.2 success criterion. */
+export interface WcagCriterion {
+ readonly standard: 'wcag';
+ /** Success-criterion number, e.g. `4.1.2`. */
+ readonly id: string;
+ /** Short name, e.g. `Name, Role, Value`. */
+ readonly name: string;
+ readonly level: 'A' | 'AA' | 'AAA';
+ readonly url: string;
+}
+
+/** An exact requirement quoted from a WAI-ARIA APG pattern. */
+export interface ApgRequirement {
+ readonly standard: 'apg';
+ /** APG pattern slug, e.g. `switch`. */
+ readonly pattern: string;
+ /** The requirement, quoted closely enough to find on the page. */
+ readonly requirement: string;
+ readonly url: string;
+}
+
+/** A current Astryx knowledge record that adopts an outcome. */
+export interface AstryxRecord {
+ readonly standard: 'astryx';
+ /** Record id, e.g. `spec:AST-013`. */
+ readonly id: string;
+ readonly url: string;
+}
+
+export type NormativeSource = WcagCriterion | ApgRequirement | AstryxRecord;
+
+/** One-line citation, used in test names and failure output (AST-020 FR4). */
+export function citeSource(source: NormativeSource): string {
+ switch (source.standard) {
+ case 'wcag':
+ return `WCAG 2.2 ${source.id} ${source.name} (${source.level})`;
+ case 'apg':
+ return `APG ${source.pattern}: ${source.requirement}`;
+ case 'astryx':
+ return `Astryx ${source.id}`;
+ }
+}
+
+/**
+ * When an expectation applies to a binding's state. Both halves are required:
+ * the prose is what a reader sees on a `not-applicable` result, the predicate
+ * is what the runner obeys (AST-020 FR4, FR5).
+ */
+export interface Applicability<Facts> {
+ readonly condition: string;
+ readonly test: (facts: Facts) => boolean;
+}
+
+/**
+ * Thrown by an expectation that can only discover it does not apply once it has
+ * looked at the page. Prefer `appliesWhen`, which is declared and readable; use
+ * this only when the condition is itself an observation.
+ *
+ * The runner turns it into `not-applicable`, never into a pass. That is the
+ * whole point: an expectation that returned early would report `pass`, and a
+ * pass is a claim that the outcome was observed.
+ */
+export class NotApplicableHere extends Error {
+ constructor(reason: string) {
+ super(reason);
+ this.name = 'NotApplicableHere';
+ }
+}
+
+/** What an expectation is handed when it runs. */
+export interface ExpectationContext<Facts> {
+ readonly harness: Harness;
+ /** The element the binding designates as the pattern's control. */
+ readonly subject: Awaited<ReturnType<Harness['subject']>>;
+ /** What the binding declares this state is supposed to be. */
+ readonly facts: Facts;
+ /**
+ * Declare, mid-run, that this state cannot exercise the outcome — the page
+ * turned out not to have what the expectation is about. The result is
+ * `not-applicable` with this reason, and the run is over.
+ *
+ * Every use is visible in the report, so an expectation cannot quietly
+ * excuse itself: a reader sees which states did not exercise it.
+ */
+ readonly notApplicable: (reason: string) => never;
+}
+
+export interface Expectation<Facts> {
+ /**
+ * Stable id, `<pattern>.<area>.<outcome>`. Ids survive refactors; splitting,
+ * combining, or narrowing one is a contract change with a migration for every
+ * binding and known-failure record that names it (AST-020 FR14).
+ */
+ readonly id: string;
+ /** The user outcome, in one plain-language line. */
+ readonly outcome: string;
+ /** Exact normative sources. The first is primary and names the test. */
+ readonly sources: readonly [NormativeSource, ...NormativeSource[]];
+ /**
+ * The WCAG 2.2 user outcome an APG-primary expectation supports. Required
+ * when the primary source is APG, so an APG mechanic is never presented as a
+ * success criterion of its own (AST-020 FR1).
+ */
+ readonly wcagOutcome?: string;
+ /** The completeness dimensions this expectation carries (AST-020 FR5, FR10). */
+ readonly covers: readonly ChecklistDimensionId[];
+ readonly appliesWhen: Applicability<Facts>;
+ /**
+ * The layer that characterizes this expectation's claim. It names the
+ * expectation in reports, and a known-failure record must match it.
+ */
+ readonly evidenceLayer: EvidenceLayer;
+ /**
+ * Any further layer the expectation's own body reads. An interaction
+ * expectation is the usual case: the claim is a real-browser one — clicking
+ * turns the switch on — but reading the resulting state is an
+ * accessibility-tree observation, so the expectation cannot run without both.
+ * A harness missing any of these reports `unrun`; it must not fail as though
+ * the outcome were absent (AST-020 platform support).
+ */
+ readonly alsoNeeds?: readonly EvidenceLayer[];
+ readonly enforcement: Enforcement;
+ /**
+ * Why an `advisory` expectation does not gate. Required for every advisory
+ * expectation, so "advisory" is a recorded judgement about adoption rather
+ * than a quiet way to stop a check from mattering (AST-020 FR9).
+ */
+ readonly advisoryBecause?: string;
+ /** Throws (or rejects) with a reader-legible message when the outcome is absent. */
+ readonly run: (context: ExpectationContext<Facts>) => Promise<void>;
+}
+
+export interface PatternContract<Facts> {
+ /** APG pattern slug this contract adopts. */
+ readonly pattern: string;
+ /** The adopted pattern's canonical URL. */
+ readonly url: string;
+ /** What the pattern owns, in one line, for report headers. */
+ readonly scope: string;
+ readonly expectations: readonly Expectation<Facts>[];
+ /** Dimensions this pattern does not own, each naming who does (AST-020 FR5). */
+ readonly exemptions: Readonly<
+ Partial<Record<ChecklistDimensionId, ChecklistExemption>>
+ >;
+}
+
+/**
+ * Every layer an expectation needs before it can run: the one that
+ * characterizes its claim, plus any further layer its body reads.
+ */
+export function requiredLayers<Facts>(
+ expectation: Expectation<Facts>,
+): readonly EvidenceLayer[] {
+ return [expectation.evidenceLayer, ...(expectation.alsoNeeds ?? [])];
+}
+
+/** Test name and failure prefix. Carries the id and the source (AST-020 FR4). */
+export function describeExpectation<Facts>(
+ expectation: Expectation<Facts>,
+): string {
+ return `${expectation.id} [${citeSource(expectation.sources[0])}] ${expectation.outcome}`;
+}
+
+/** The dimensions at least one expectation carries. */
+function coveredDimensions<Facts>(
+ contract: PatternContract<Facts>,
+): readonly ChecklistDimensionId[] {
+ return [
+ ...new Set(
+ contract.expectations.flatMap(expectation => expectation.covers),
+ ),
+ ].sort();
+}
+
+/**
+ * The completeness dimensions this pattern has neither encoded nor exempted.
+ * A finished pattern returns an empty list; anything else is a dimension that
+ * would otherwise disappear silently (AST-020 FR5, FR10, FR12).
+ */
+export function unansweredDimensions<Facts>(
+ contract: PatternContract<Facts>,
+): readonly ChecklistDimensionId[] {
+ const covered = new Set(coveredDimensions(contract));
+ return CHECKLIST_DIMENSIONS.map(dimension => dimension.id).filter(
+ id => !covered.has(id) && contract.exemptions[id] == null,
+ );
+}
+
+const ID_SHAPE = /^[a-z][a-z0-9]*(\.[a-z0-9-]+)+$/;
+const EMPTY_EXEMPTION =
+ /^(n\/?a|not applicable|none|unknown|tbd|does not apply)\.?$/i;
+const DIMENSION_IDS: readonly string[] = CHECKLIST_DIMENSIONS.map(
+ dimension => dimension.id,
+);
+
+/**
+ * Build a pattern contract, refusing one that cannot be audited.
+ *
+ * A contract that omits a source, an evidence layer, an applicability
+ * condition, or an exemption's owner is not "less complete" — it is rejected.
+ * Silence is the failure mode AST-020 is written against, so it is the one this
+ * constructor makes impossible.
+ */
+export function definePattern<Facts>(
+ contract: PatternContract<Facts>,
+): PatternContract<Facts> {
+ const problems: string[] = [];
+ const seen = new Set<string>();
+
+ for (const expectation of contract.expectations) {
+ const {id} = expectation;
+ if (!ID_SHAPE.test(id)) {
+ problems.push(
+ `expectation id ${JSON.stringify(id)} must look like "pattern.area.outcome"`,
+ );
+ }
+ if (!id.startsWith(`${contract.pattern}.`)) {
+ problems.push(
+ `expectation ${id} does not belong to pattern ${contract.pattern}`,
+ );
+ }
+ if (seen.has(id)) {
+ problems.push(`duplicate expectation id ${id}`);
+ }
+ seen.add(id);
+
+ if (expectation.outcome.trim() === '') {
+ problems.push(`${id} states no user outcome`);
+ }
+ if (expectation.sources.length === 0) {
+ problems.push(`${id} cites no normative source`);
+ }
+ if (
+ expectation.sources[0]?.standard === 'apg' &&
+ (expectation.wcagOutcome ?? '').trim() === ''
+ ) {
+ problems.push(
+ `${id} is APG-primary, so it must name the WCAG 2.2 outcome it supports (AST-020 FR1)`,
+ );
+ }
+ if (expectation.covers.length === 0) {
+ problems.push(`${id} carries no completeness dimension (AST-020 FR5)`);
+ }
+ for (const dimension of expectation.covers) {
+ if (!DIMENSION_IDS.includes(dimension)) {
+ problems.push(
+ `${id} claims unknown completeness dimension "${dimension}"`,
+ );
+ }
+ const exemption = contract.exemptions[dimension];
+ if (exemption != null && exemption.coversRemainderOnly !== true) {
+ problems.push(
+ `"${dimension}" is both encoded by ${id} and exempted; a dimension has one answer, unless the exemption sets coversRemainderOnly (AST-020 FR5)`,
+ );
+ }
+ }
+ if (expectation.appliesWhen.condition.trim() === '') {
+ problems.push(`${id} states no applicability condition`);
+ }
+ for (const layer of requiredLayers(expectation)) {
+ if (!EVIDENCE_LAYERS.includes(layer)) {
+ problems.push(`${id} names an unknown evidence layer "${layer}"`);
+ }
+ }
+ if ((expectation.alsoNeeds ?? []).includes(expectation.evidenceLayer)) {
+ problems.push(
+ `${id} repeats its own evidence layer in alsoNeeds; list only the further layers it reads`,
+ );
+ }
+
+ // FR9: `required` is earned by a DIRECTLY APPLICABLE WCAG A/AA criterion or
+ // by a current Astryx record that adopts the outcome — never by how easy
+ // the check is to automate.
+ //
+ // "Directly applicable" is read here as: the criterion is the
+ // expectation's PRIMARY source, the one that names it. A supporting
+ // citation further down the list is not adoption — an APG-primary
+ // expectation that also mentions 4.1.2 for context is still an APG
+ // requirement, and gating on it would let any expectation buy `required`
+ // by adding a plausible criterion to the end of its list.
+ const primary = expectation.sources[0];
+ const adopted =
+ primary != null &&
+ ((primary.standard === 'wcag' &&
+ (primary.level === 'A' || primary.level === 'AA')) ||
+ primary.standard === 'astryx');
+ if (expectation.enforcement === 'required' && !adopted) {
+ problems.push(
+ `${id} is required, but its primary source is neither a WCAG 2.2 A/AA criterion nor a current Astryx record (AST-020 FR9)`,
+ );
+ }
+ if (
+ expectation.enforcement === 'advisory' &&
+ (expectation.advisoryBecause ?? '').trim() === ''
+ ) {
+ problems.push(
+ `${id} is advisory but does not say why the outcome is not adopted as a gate (AST-020 FR9)`,
+ );
+ }
+ }
+
+ for (const [dimension, exemption] of Object.entries(contract.exemptions)) {
+ if (!DIMENSION_IDS.includes(dimension)) {
+ problems.push(`exemption "${dimension}" is not a completeness dimension`);
+ continue;
+ }
+ if (exemption == null) {
+ continue;
+ }
+ if (exemption.owner.trim() === '') {
+ problems.push(
+ `"${dimension}" is exempt but names no owner (AST-020 FR5)`,
+ );
+ }
+ if (exemption.verifiedBy.trim() === '') {
+ problems.push(
+ `"${dimension}" is exempt but names no verification method (AST-020 FR5)`,
+ );
+ }
+ if (
+ exemption.coversRemainderOnly === true &&
+ !contract.expectations.some(expectation =>
+ expectation.covers.includes(dimension as ChecklistDimensionId),
+ )
+ ) {
+ problems.push(
+ `"${dimension}" claims to exempt only the remainder, but no expectation encodes any of it`,
+ );
+ }
+ if (EMPTY_EXEMPTION.test(exemption.reason.trim())) {
+ problems.push(
+ `"${dimension}" uses "${exemption.reason}" as its exemption reason; FR5 forbids a generic escape hatch`,
+ );
+ }
+ }
+
+ if (problems.length > 0) {
+ throw new Error(
+ `Pattern "${contract.pattern}" is not auditable:\n - ${problems.join('\n - ')}`,
+ );
+ }
+
+ return contract;
+}
diff --git a/internal/a11y-spec/src/harness.ts b/internal/a11y-spec/src/harness.ts
new file mode 100644
index 0000000000..f99cfba89f
--- /dev/null
+++ b/internal/a11y-spec/src/harness.ts
@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file harness.ts
+ * @input None (pure declarations)
+ * @output The evidence-layer vocabulary and the Harness/Subject seam every
+ * expectation is written against.
+ * @position The runtime seam of @astryxdesign/a11y-spec. One contract, many
+ * harnesses: a harness declares which evidence layers it can observe, and the
+ * runner refuses to run an expectation the harness cannot see.
+ *
+ * The layers and their boundaries are the ones in the accepted records:
+ * `docs/specs/AST-020/spec.md` FR6 lists them; `docs/specs/AST-009/spec.md`
+ * bounds what each one proves. The rule that makes them worth having is that a
+ * lower layer may not claim a result only a higher layer observes — so jsdom
+ * never reports a computed accessible name, and no automated layer ever reports
+ * what a screen reader says.
+ *
+ * SYNC: A new harness implements this file and updates
+ * - /internal/a11y-spec/README.md
+ */
+
+export const EVIDENCE_LAYERS = [
+ 'unit',
+ 'dom',
+ 'accessibility-tree',
+ 'axe',
+ 'real-browser',
+ 'visual',
+ 'lint',
+ 'manual',
+ 'real-at',
+] as const;
+
+export type EvidenceLayer = (typeof EVIDENCE_LAYERS)[number];
+
+/**
+ * What the browser computes for a node. Only an engine can answer this.
+ *
+ * Requiredness is deliberately absent: Chromium's protocol does not emit a
+ * `required` property for a checkbox, so putting one here would be a field this
+ * package could only ever fill with a guess. The switch contract reads that
+ * declaration at the DOM layer instead.
+ */
+export interface ComputedNode {
+ /** Computed role, e.g. `switch`. */
+ readonly role: string | null;
+ /** Computed accessible name. */
+ readonly name: string;
+ /** Computed accessible description. */
+ readonly description: string;
+ /** Computed checked state, or null when the node exposes none. */
+ readonly checked: 'true' | 'false' | 'mixed' | null;
+ readonly disabled: boolean;
+ readonly invalid: boolean;
+}
+
+/** The element a binding designates as the pattern's control. */
+export interface Subject {
+ /** DOM layer: an attribute exactly as authored. */
+ attribute(name: string): Promise<string | null>;
+ /**
+ * DOM layer: resolve an id-list attribute (`aria-describedby`,
+ * `aria-labelledby`) to the text of each referenced element. A `null` entry
+ * is an id that resolves to nothing — a description the user never gets.
+ */
+ idReferences(attribute: string): Promise<readonly (string | null)[]>;
+ /** Accessibility-tree layer: what the engine computes for this node. */
+ computed(): Promise<ComputedNode>;
+ /**
+ * Real-browser layer: the text of this control's label as a sighted person
+ * actually sees it, or null when nothing is visibly rendered.
+ *
+ * Bounded on purpose: it reads the label the platform ASSOCIATES with the
+ * control. WCAG 2.5.3's visible label need not be associated — an adjacent
+ * unlinked `<span>` can label a control to the eye — and no generic rule can
+ * tell that span from neighbouring prose. A pattern that needs that case
+ * covered gives the binding an explicit hidden-label state to verify.
+ *
+ * Deciding what is *visible* takes layout, which is why this is a
+ * real-browser observation and not a DOM one: markup alone cannot tell a
+ * rendered label from a visually-hidden one. Resolution follows the platform's
+ * own labelling — `aria-labelledby`, then a `for=`/wrapping `<label>` — never
+ * a design system's private structure.
+ */
+ visibleLabelText(): Promise<string | null>;
+ /** Real-browser layer: whether this node currently holds focus. */
+ isFocused(): Promise<boolean>;
+ /** Real-browser layer: move focus here the way a user's Tab would leave it. */
+ focus(): Promise<void>;
+}
+
+/** A key an expectation can send. Spelled by intent, not by engine syntax. */
+export type Key = 'Space' | 'Tab';
+
+/**
+ * A mounted binding, observed at whatever layers this runtime can honestly see.
+ */
+export interface Harness {
+ /** Short runtime name, e.g. `jsdom` or `chromium`. Appears in every report row. */
+ readonly name: string;
+ /** The layers this harness can observe. Anything else is reported `unrun`. */
+ readonly observes: readonly EvidenceLayer[];
+ /** The element the binding designates as the pattern's control. */
+ subject(): Promise<Subject>;
+ /**
+ * Real-browser layer: click the subject the way a pointer user would,
+ * including the browser's own judgement that the control is there to be
+ * clicked. `ignoreAvailability` drops that judgement, and exists for the one
+ * case that needs it: proving a control the browser considers unavailable
+ * still does not change when someone clicks it anyway.
+ */
+ click(
+ subject: Subject,
+ options?: {ignoreAvailability?: boolean},
+ ): Promise<void>;
+ /**
+ * Real-browser layer: begin a pointer press on the subject and release it
+ * somewhere else, the way a person takes back a press they did not mean —
+ * press, slide off, let go.
+ */
+ abortedPress(subject: Subject): Promise<void>;
+ /** Real-browser layer: send a key to whatever currently holds focus. */
+ press(key: Key): Promise<void>;
+ /** Real-browser layer: park focus at the document body, before the content. */
+ resetFocus(): Promise<void>;
+}
+
+/**
+ * Thrown when something asks a harness for an observation it cannot make. The
+ * runner prevents this by checking `observes` first; the guard exists so a
+ * harness can never quietly answer with a substitute from a lower layer.
+ */
+export class UnobservableError extends Error {
+ constructor(harness: string, layer: EvidenceLayer, what: string) {
+ super(
+ `The ${harness} harness cannot observe the ${layer} layer, so it cannot report ${what}.`,
+ );
+ this.name = 'UnobservableError';
+ }
+}
diff --git a/internal/a11y-spec/src/harness/chromium.ts b/internal/a11y-spec/src/harness/chromium.ts
new file mode 100644
index 0000000000..f27c47cc8d
--- /dev/null
+++ b/internal/a11y-spec/src/harness/chromium.ts
@@ -0,0 +1,374 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file chromium.ts
+ * @input Uses a Playwright `Page` and a `Locator` for the subject, and the
+ * Chrome DevTools Protocol accessibility domain behind them
+ * @output `createChromiumHarness` — a harness that observes the DOM,
+ * accessibility-tree, and real-browser layers of a page rendered by a real
+ * shipping engine — plus `holdMotionStill`, the page setup its specs share.
+ * @position The high-fidelity lane. Imported only from the Playwright specs, so
+ * the jsdom lane never loads Playwright: this file is the package's separate
+ * `@astryxdesign/a11y-spec/chromium` entry point, never re-exported from
+ * ../index.ts.
+ *
+ * The accessibility tree here is the ENGINE's, read through
+ * `Accessibility.getPartialAXTree`, not a DOM approximation. That is the whole
+ * reason this harness exists: `docs/specs/AST-009/spec.md` bounds the DOM layer
+ * to "author-supplied ARIA relationships" and reserves computed role, name,
+ * description, and state for the accessibility-tree layer. Chromium is where
+ * Astryx can actually observe them.
+ *
+ * What it still does NOT prove is what an assistive technology says. Speech,
+ * braille, announcement timing, and virtual-cursor entry are the real-AT layer,
+ * and no harness in this package reports them.
+ *
+ * SYNC: Keep the observed-layer list honest, and keep the method surface equal
+ * to ../harness/jsdom.ts — both implement Harness in ../harness.ts.
+ */
+
+import type {CDPSession, Locator, Page} from '@playwright/test';
+import {
+ type ComputedNode,
+ type EvidenceLayer,
+ type Harness,
+ type Key,
+ type Subject,
+} from '../harness';
+
+/** What this harness can observe. Exported so a suite need not restate it. */
+export const CHROMIUM_OBSERVES: readonly EvidenceLayer[] = [
+ 'unit',
+ 'dom',
+ 'accessibility-tree',
+ 'real-browser',
+];
+
+const KEYS: Record<Key, string> = {
+ Space: ' ',
+ Tab: 'Tab',
+};
+
+interface AxValue {
+ readonly value?: unknown;
+}
+
+interface AxProperty {
+ readonly name: string;
+ readonly value?: AxValue;
+}
+
+interface AxNode {
+ readonly ignored?: boolean;
+ readonly role?: AxValue;
+ readonly name?: AxValue;
+ readonly description?: AxValue;
+ readonly backendDOMNodeId?: number;
+ readonly properties?: readonly AxProperty[];
+}
+
+function text(value: AxValue | undefined): string {
+ return typeof value?.value === 'string' ? value.value : '';
+}
+
+function property(node: AxNode, name: string): unknown {
+ return node.properties?.find(candidate => candidate.name === name)?.value
+ ?.value;
+}
+
+function flag(node: AxNode, name: string): boolean {
+ const value = property(node, name);
+ // The protocol is not consistent about booleans across property names, so
+ // accept every spelling of true rather than silently reading a set flag as
+ // unset.
+ return value === true || value === 'true' || value === 1;
+}
+
+const AX_TARGET_ATTRIBUTE = 'data-a11y-spec-ax-target';
+
+/**
+ * The engine's own accessibility node for the subject.
+ *
+ * Playwright's `ariaSnapshot` renders role and name, but not the invalid state
+ * a field contract needs, so this reads the protocol directly. The protocol addresses DOM nodes by id, and the page is on the far
+ * side of the bridge, so the subject is marked with a data attribute for the
+ * length of the query and unmarked afterwards. A data attribute takes no part
+ * in accessibility computation, so marking it cannot change the answer.
+ *
+ * An element the engine leaves out of the tree comes back `ignored`, and is
+ * reported as exposing nothing rather than as absent state.
+ */
+async function computedNode(
+ cdp: CDPSession,
+ locator: Locator,
+): Promise<ComputedNode> {
+ await locator.evaluate(
+ (element, attribute) => element.setAttribute(attribute, ''),
+ AX_TARGET_ATTRIBUTE,
+ );
+ try {
+ const {root} = (await cdp.send('DOM.getDocument', {
+ depth: 0,
+ })) as unknown as {
+ root: {nodeId: number};
+ };
+ const {nodeId} = (await cdp.send('DOM.querySelector', {
+ nodeId: root.nodeId,
+ selector: `[${AX_TARGET_ATTRIBUTE}]`,
+ })) as unknown as {nodeId: number};
+
+ if (nodeId === 0) {
+ throw new Error('the subject is not in the document');
+ }
+
+ const {nodes} = (await cdp.send('Accessibility.getPartialAXTree', {
+ nodeId,
+ fetchRelatives: false,
+ })) as unknown as {nodes: readonly AxNode[]};
+
+ const node = nodes[0];
+
+ if (node == null || node.ignored === true) {
+ return {
+ role: null,
+ name: '',
+ description: '',
+ checked: null,
+ disabled: false,
+ invalid: false,
+ };
+ }
+
+ const checked = property(node, 'checked');
+ const invalid = property(node, 'invalid');
+
+ return {
+ role: text(node.role) === '' ? null : text(node.role),
+ name: text(node.name),
+ description: text(node.description),
+ checked:
+ checked === 'true' || checked === true
+ ? 'true'
+ : checked === 'false' || checked === false
+ ? 'false'
+ : checked === 'mixed'
+ ? 'mixed'
+ : null,
+ disabled: flag(node, 'disabled'),
+ invalid: invalid != null && invalid !== 'false' && invalid !== false,
+ };
+ } finally {
+ await locator.evaluate(
+ (element, attribute) => element.removeAttribute(attribute),
+ AX_TARGET_ATTRIBUTE,
+ );
+ }
+}
+
+/**
+ * Stop transitions before an expectation reads state, so nothing measures a
+ * frame the animation happens to be showing.
+ *
+ * This is a page call rather than configuration on purpose. Playwright's
+ * `use: {reducedMotion: 'reduce'}` and Chromium's own
+ * `--force-prefers-reduced-motion` flag both leave
+ * `matchMedia('(prefers-reduced-motion: reduce)')` FALSE in this version —
+ * measured, not assumed — so either one would read like a safeguard while doing
+ * nothing. `emulateMedia` takes effect immediately and can be checked.
+ */
+export async function holdMotionStill(page: Page): Promise<void> {
+ await page.emulateMedia({reducedMotion: 'reduce'});
+}
+
+export interface ChromiumHarnessOptions {
+ readonly page: Page;
+ /**
+ * The element the binding designates as the pattern's control. The binding
+ * resolves it — by role for a conforming component, or by a fixture-owned
+ * hook for a deliberately violating fixture, so a mutation flips exactly the
+ * expectation under test.
+ */
+ readonly subject: Locator;
+ /** A CDP session on `page`, reused across expectations. */
+ readonly cdp: CDPSession;
+}
+
+export function createChromiumHarness(
+ options: ChromiumHarnessOptions,
+): Harness {
+ const {page, subject: locator, cdp} = options;
+
+ const subject: Subject = {
+ attribute: name => locator.getAttribute(name),
+ idReferences: attribute =>
+ // The same walk exists in the jsdom harness. It is not shared: Playwright
+ // serializes this function into the page, so it cannot close over an
+ // import from this package.
+ locator.evaluate(
+ (element, name) =>
+ (element.getAttribute(name) ?? '')
+ .split(/\s+/)
+ .filter(Boolean)
+ .map(id => {
+ const target = element.ownerDocument.getElementById(id);
+ return target == null ? null : (target.textContent ?? '').trim();
+ }),
+ attribute,
+ ),
+ computed: () => computedNode(cdp, locator),
+ visibleLabelText: () =>
+ locator.evaluate(element => {
+ // Whether a person can actually read this text.
+ //
+ // Two questions, because no single API answers both.
+ //
+ // `checkVisibility` is the platform's own answer to "is this rendered
+ // at all", and it walks ancestors — so a label inside a
+ // `visibility: hidden`, `opacity: 0`, or `display: none` wrapper is
+ // correctly invisible without this code reimplementing the cascade.
+ //
+ // What it cannot answer is whether anything of the element actually
+ // lands on screen: every sr-only recipe stays "visible" to it. So the
+ // element is sampled — if a point over it resolves to the element, to
+ // something inside it, or to something COVERING it, the element paints
+ // there. If every sample resolves to one of the element's own
+ // ancestors, nothing of it paints: it is clipped away, whatever its box
+ // says. If a sample resolves to nothing at all, that point is outside
+ // the viewport.
+ //
+ // Occlusion is deliberately not hiding: a label under an overlay is
+ // still a label a person can read when the overlay moves, and treating
+ // it as hidden would silently switch off the criterion that reads it.
+ const paints = (node: Element): boolean => {
+ if (
+ !node.checkVisibility({
+ visibilityProperty: true,
+ opacityProperty: true,
+ contentVisibilityAuto: true,
+ })
+ ) {
+ return false;
+ }
+ const box = node.getBoundingClientRect();
+ const samples: ReadonlyArray<readonly [number, number]> = [
+ [box.x + box.width / 2, box.y + box.height / 2],
+ [box.x + 1, box.y + box.height / 2],
+ [box.right - 1, box.y + box.height / 2],
+ ];
+ return samples.some(([x, y]) => {
+ const at = node.ownerDocument.elementFromPoint(x, y);
+ if (at == null) {
+ // Outside the viewport, so nothing is there to read.
+ return false;
+ }
+ return at === node || node.contains(at) || !at.contains(node);
+ });
+ };
+ const textOf = (node: Element): string | null => {
+ const text = (node.textContent ?? '').replace(/\s+/g, ' ').trim();
+ return text !== '' && paints(node) ? text : null;
+ };
+
+ // The platform's own labelling order, not any design system's.
+ const labelledBy = element.getAttribute('aria-labelledby');
+ if (labelledBy != null && labelledBy.trim() !== '') {
+ const parts = labelledBy
+ .split(/\s+/)
+ .filter(Boolean)
+ .map(id => element.ownerDocument.getElementById(id))
+ .flatMap(target => (target == null ? [] : [textOf(target)]))
+ .filter((text): text is string => text != null);
+ return parts.length === 0 ? null : parts.join(' ');
+ }
+ const id = element.getAttribute('id');
+ const associated =
+ id == null || id === ''
+ ? null
+ : element.ownerDocument.querySelector(
+ // An id is author-supplied and need not be a bare identifier.
+ `label[for="${CSS.escape(id)}"]`,
+ );
+ const wrapping = element.closest('label');
+ for (const label of [associated, wrapping]) {
+ if (label != null) {
+ const text = textOf(label);
+ if (text != null) {
+ return text;
+ }
+ }
+ }
+ // A control that labels itself, e.g. a div with role=switch.
+ return textOf(element);
+ }),
+ isFocused: () =>
+ locator.evaluate(
+ element => element.ownerDocument.activeElement === element,
+ ),
+ focus: () => locator.focus(),
+ };
+
+ return {
+ name: 'chromium',
+ observes: CHROMIUM_OBSERVES,
+ subject: async () => subject,
+ click: async (_subject, options) => {
+ // Without `force`, Playwright first satisfies itself that the control is
+ // visible, stable, enabled, and actually receives pointer events — so an
+ // ordinary click here also proves a pointer could reach the switch.
+ // `ignoreAvailability` skips that judgement, which is the only way to ask
+ // a control the browser calls unavailable what it does when clicked
+ // anyway.
+ await locator.click({force: options?.ignoreAvailability === true});
+ },
+ abortedPress: async () => {
+ const box = await locator.boundingBox();
+ if (box == null) {
+ throw new Error('the subject has no box to press on');
+ }
+ const viewport = await page.evaluate(() => ({
+ width: window.innerWidth,
+ height: window.innerHeight,
+ }));
+ // Release clear of the control but still inside the viewport: a gesture
+ // that ends out of bounds is not one the browser reports. Which way to
+ // go is decided per axis by whichever side has more room, so a control
+ // flush against an edge does not push the release back INSIDE its own box
+ // — which would be a completed click, and would fail a switch that is
+ // behaving correctly.
+ const away = (start: number, end: number, limit: number): number => {
+ const before = start;
+ const after = limit - end;
+ return before > after
+ ? Math.max(1, start - 200)
+ : Math.min(limit - 1, end + 200);
+ };
+ const releaseX = away(box.x, box.x + box.width, viewport.width);
+ const releaseY = away(box.y, box.y + box.height, viewport.height);
+ const insideTheControl =
+ releaseX >= box.x &&
+ releaseX <= box.x + box.width &&
+ releaseY >= box.y &&
+ releaseY <= box.y + box.height;
+ if (insideTheControl) {
+ throw new Error(
+ 'the viewport leaves nowhere to release a press outside this control, so an aborted press cannot be performed here',
+ );
+ }
+ await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+ await page.mouse.down();
+ await page.mouse.move(releaseX, releaseY);
+ await page.mouse.up();
+ },
+ press: async key => {
+ await page.keyboard.press(KEYS[key]);
+ },
+ resetFocus: async () => {
+ await page.evaluate(() => {
+ const active = document.activeElement;
+ if (active instanceof HTMLElement) {
+ active.blur();
+ }
+ });
+ },
+ };
+}
diff --git a/internal/a11y-spec/src/harness/jsdom.ts b/internal/a11y-spec/src/harness/jsdom.ts
new file mode 100644
index 0000000000..89616ef6b2
--- /dev/null
+++ b/internal/a11y-spec/src/harness/jsdom.ts
@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file jsdom.ts
+ * @input Uses ../harness (the seam) and a DOM element the binding designates
+ * @output `createJsdomHarness` — a harness that observes the unit and DOM
+ * layers, and honestly refuses everything above them.
+ * @position Fast lane. Runs inside the existing Vitest `ui` project, so a DOM
+ * regression is caught on every pull request without a browser.
+ *
+ * What this harness will NOT do is the point of it. jsdom renders markup; it
+ * does not compute an accessibility tree, it does not resolve a real focus
+ * order, and it does not dispatch the activation a browser derives from a key.
+ * Every one of those is a higher layer (`docs/specs/AST-009/spec.md`), so this
+ * harness declares that it cannot see them and the runner reports `unrun`
+ * instead of quietly answering from the markup.
+ *
+ * SYNC: Keep the observed-layer list honest. Adding a layer here is a claim
+ * that jsdom can actually observe it.
+ */
+
+import {
+ UnobservableError,
+ type Harness,
+ type Subject,
+ type EvidenceLayer,
+} from '../harness';
+
+/** What this harness can observe. Exported so a suite need not restate it. */
+export const JSDOM_OBSERVES: readonly EvidenceLayer[] = ['unit', 'dom'];
+
+const HARNESS = 'jsdom';
+
+function unobservable(layer: EvidenceLayer, what: string): never {
+ throw new UnobservableError(HARNESS, layer, what);
+}
+
+function createSubject(element: Element): Subject {
+ return {
+ attribute: async name => element.getAttribute(name),
+ idReferences: async attribute => {
+ // The same walk exists in the Chromium harness. It is not shared: that
+ // copy is serialized into the page by Playwright, so it cannot close over
+ // an import from this package.
+ const value = element.getAttribute(attribute);
+ if (value == null || value.trim() === '') {
+ return [];
+ }
+ return value
+ .split(/\s+/)
+ .filter(Boolean)
+ .map(id => {
+ const target = element.ownerDocument.getElementById(id);
+ return target == null ? null : (target.textContent ?? '').trim();
+ });
+ },
+ computed: async () =>
+ unobservable('accessibility-tree', 'a computed accessibility node'),
+ visibleLabelText: async () =>
+ unobservable('real-browser', 'what a label actually renders as'),
+ isFocused: async () => unobservable('real-browser', 'real focus'),
+ focus: async () => unobservable('real-browser', 'real focus'),
+ };
+}
+
+export interface JsdomHarnessOptions {
+ /**
+ * The element the binding designates as the pattern's control. The binding
+ * resolves it — by role for a conforming component, or by a fixture-owned
+ * hook for a deliberately violating fixture, so that a mutation flips exactly
+ * the expectation under test instead of making the subject unfindable.
+ */
+ readonly subject: Element;
+}
+
+export function createJsdomHarness(options: JsdomHarnessOptions): Harness {
+ const subject = createSubject(options.subject);
+ return {
+ name: HARNESS,
+ observes: JSDOM_OBSERVES,
+ subject: async () => subject,
+ click: async () =>
+ unobservable('real-browser', 'a real pointer activation'),
+ abortedPress: async () =>
+ unobservable('real-browser', 'a real pointer press'),
+ press: async () => unobservable('real-browser', 'a real key press'),
+ resetFocus: async () => unobservable('real-browser', 'real focus'),
+ };
+}
diff --git a/internal/a11y-spec/src/index.ts b/internal/a11y-spec/src/index.ts
new file mode 100644
index 0000000000..de2129cc96
--- /dev/null
+++ b/internal/a11y-spec/src/index.ts
@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Re-exports the browser-free surface of @astryxdesign/a11y-spec
+ * @output Contract vocabulary, completeness checklist, harness seam, runner,
+ * report, the jsdom harness, and the authored pattern contracts. A pattern
+ * exports a helper here only when a BINDING needs it — a helper the contract
+ * uses internally stays module-private.
+ * @position Package entry point. The Chromium harness is deliberately NOT here:
+ * it imports Playwright, and the jsdom lane must never drag a browser in. It
+ * is a separate entry, `@astryxdesign/a11y-spec/chromium`.
+ *
+ * SYNC: When a pattern is authored, export it here and list it in README.md
+ */
+
+export {
+ NotApplicableHere,
+ citeSource,
+ definePattern,
+ describeExpectation,
+ requiredLayers,
+ unansweredDimensions,
+ type ApgRequirement,
+ type Applicability,
+ type AstryxRecord,
+ type Enforcement,
+ type Expectation,
+ type ExpectationContext,
+ type NormativeSource,
+ type PatternContract,
+ type WcagCriterion,
+} from './contract';
+
+export {
+ CHECKLIST_DIMENSIONS,
+ type ChecklistDimension,
+ type ChecklistDimensionId,
+ type ChecklistExemption,
+} from './checklist';
+
+export {
+ EVIDENCE_LAYERS,
+ UnobservableError,
+ type ComputedNode,
+ type EvidenceLayer,
+ type Harness,
+ type Key,
+ type Subject,
+} from './harness';
+
+export {
+ runBinding,
+ type BindingResult,
+ type ExpectationResult,
+ type KnownFailure,
+ type ResultStatus,
+ type RunBindingOptions,
+} from './run';
+
+export {
+ blockingResults,
+ formatFailures,
+ neverExercised,
+ formatReport,
+ summarize,
+ type Report,
+ type ReportCounts,
+} from './report';
+
+export {createJsdomHarness, type JsdomHarnessOptions} from './harness/jsdom';
+
+export {
+ SWITCH_PATTERN,
+ spokenWords,
+ type SwitchStateFacts,
+} from './patterns/switch';
diff --git a/internal/a11y-spec/src/patterns/switch.chromium.spec.ts b/internal/a11y-spec/src/patterns/switch.chromium.spec.ts
new file mode 100644
index 0000000000..3cea1cb12f
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/switch.chromium.spec.ts
@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file switch.chromium.spec.ts
+ * @input Uses @playwright/test, ./switch (the contract), ./switch.fixtures,
+ * ../harness/chromium, ../run
+ * @output The contract's own proof in a real engine: every expectation passes
+ * against a conforming fixture and fails against each fixture that removes
+ * its outcome.
+ * @position Self-test, the Chromium half of ./switch.jsdom.test.ts. Both halves
+ * read the same fixtures, so the same positive and negative proof runs at
+ * every layer that can see it.
+ *
+ * The fixtures are hand-written HTML with no Astryx in them, because what is
+ * under test here is the CONTRACT — whether an expectation can actually fail.
+ * A component binding proves the different claim that the component delivers
+ * the outcome.
+ *
+ * SYNC: Fixtures and mutations live in ./switch.fixtures.ts, shared with the
+ * jsdom half.
+ */
+
+import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {describeExpectation, requiredLayers} from '../contract';
+import {
+ CHROMIUM_OBSERVES,
+ createChromiumHarness,
+ holdMotionStill,
+} from '../harness/chromium';
+import {runBinding, type ExpectationResult} from '../run';
+import {SWITCH_PATTERN} from './switch';
+import {
+ CONFORMING_FIXTURES,
+ SUBJECT_SELECTOR,
+ SWITCH_MUTATIONS,
+ fixture,
+ type SwitchFixture,
+} from './switch.fixtures';
+
+/**
+ * A tab stop after the switch, so "focus can leave it" has somewhere to go.
+ * Without it the browser moves focus to its own chrome and the fixture could
+ * not tell an escape from a trap.
+ */
+function fixturePage(html: string): string {
+ return `<!doctype html><html lang="en"><body>${html}<button type="button" id="after">after</button></body></html>`;
+}
+
+async function results(
+ page: Page,
+ cdp: CDPSession,
+ target: SwitchFixture,
+ only?: readonly string[],
+): Promise<readonly ExpectationResult[]> {
+ const run = await runBinding({
+ contract: SWITCH_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ only,
+ mount: async () => {
+ await page.setContent(fixturePage(target.html));
+ await holdMotionStill(page);
+ return createChromiumHarness({
+ page,
+ subject: page.locator(SUBJECT_SELECTOR),
+ cdp,
+ });
+ },
+ });
+ return run.results;
+}
+
+test.describe('switch contract — conforming fixtures', () => {
+ for (const id of CONFORMING_FIXTURES) {
+ test(`${id}: every applicable expectation passes`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const observed = await results(page, cdp, fixture(id));
+ const notPassing = observed.filter(
+ result =>
+ result.status !== 'pass' && result.status !== 'not-applicable',
+ );
+ expect(
+ notPassing.map(
+ result => `${result.expectation}: ${result.detail ?? ''}`,
+ ),
+ ).toEqual([]);
+ });
+ }
+});
+
+test.describe('switch contract — deliberately violating fixtures', () => {
+ for (const expectation of SWITCH_PATTERN.expectations) {
+ if (
+ !requiredLayers(expectation).every(layer =>
+ CHROMIUM_OBSERVES.includes(layer),
+ )
+ ) {
+ continue;
+ }
+ for (const fixtureId of SWITCH_MUTATIONS[expectation.id] ?? []) {
+ test(`${describeExpectation(expectation)} — fails against ${fixtureId}`, async ({
+ page,
+ }) => {
+ const cdp = await page.context().newCDPSession(page);
+ const [result] = await results(page, cdp, fixture(fixtureId), [
+ expectation.id,
+ ]);
+ expect(result?.status, result?.detail ?? 'no result').toBe('fail');
+ expect(result?.detail ?? '').not.toBe('');
+ });
+ }
+ }
+});
diff --git a/internal/a11y-spec/src/patterns/switch.fixtures.ts b/internal/a11y-spec/src/patterns/switch.fixtures.ts
new file mode 100644
index 0000000000..2a475594f3
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/switch.fixtures.ts
@@ -0,0 +1,349 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file switch.fixtures.ts
+ * @input Uses ./switch (SwitchStateFacts)
+ * @output SWITCH_FIXTURES — hand-written switches, one conforming per state and
+ * one deliberately violating per expectation — and SWITCH_MUTATIONS, which
+ * says which fixture each expectation must fail against.
+ * @position The contract's own proof (AST-020 FR11). Used by the jsdom self-test
+ * and by the Chromium self-test, so the same positive and negative fixtures
+ * run at both layers.
+ *
+ * These are plain HTML on purpose. They prove the CONTRACT — that each
+ * expectation passes when the outcome is present and fails when it is removed —
+ * so they must not depend on any Astryx component. A component binding proves
+ * something different: that the component delivers the outcome.
+ *
+ * Each fixture marks its control with `data-a11y-subject`. A binding designates
+ * its subject rather than the contract hunting for one by role, so removing the
+ * role flips exactly the role expectation instead of making every expectation
+ * fail at once (which would prove nothing about any of them).
+ *
+ * SYNC: A new expectation in ./switch.ts needs a row in SWITCH_MUTATIONS, and
+ * the self-tests fail until it has one.
+ */
+
+import type {SwitchStateFacts} from './switch';
+
+/** The attribute a fixture marks its control with. */
+const SUBJECT_ATTRIBUTE = 'data-a11y-subject';
+
+/** How a lane finds the control a fixture designates. */
+export const SUBJECT_SELECTOR = `[${SUBJECT_ATTRIBUTE}]`;
+
+export interface SwitchFixture {
+ readonly id: string;
+ /** What this fixture is, in one line, for the test name. */
+ readonly summary: string;
+ /** What the fixture declares itself to be. */
+ readonly facts: SwitchStateFacts;
+ readonly html: string;
+}
+
+const CONFORMING_FACTS: SwitchStateFacts = {
+ checked: false,
+ operable: true,
+ focusable: true,
+ disabled: false,
+ described: false,
+ required: false,
+ invalid: false,
+};
+
+function facts(overrides: Partial<SwitchStateFacts> = {}): SwitchStateFacts {
+ return {...CONFORMING_FACTS, ...overrides};
+}
+
+/** A native checkbox promoted to a switch — the APG's own HTML-checkbox example. */
+function nativeSwitch(attributes = ''): string {
+ return (
+ '<label for="fx">Notifications</label>' +
+ `<input id="fx" ${SUBJECT_ATTRIBUTE} type="checkbox" role="switch"${attributes ? ` ${attributes}` : ''}>`
+ );
+}
+
+/** A div-based switch, so a fixture can withhold behaviour a native input has. */
+function divSwitch(attributes: string, body = 'Notifications'): string {
+ return `<div ${SUBJECT_ATTRIBUTE} role="switch" ${attributes}>${body}</div>`;
+}
+
+const TOGGLE_ON_CLICK = `onclick="this.setAttribute('aria-checked', this.getAttribute('aria-checked') === 'true' ? 'false' : 'true')"`;
+const TOGGLE_ON_SPACE = `onkeydown="if (event.key === ' ') { event.preventDefault(); this.setAttribute('aria-checked', this.getAttribute('aria-checked') === 'true' ? 'false' : 'true'); }"`;
+/** Changes on the way down, where a press can no longer be taken back. */
+const TOGGLE_ON_POINTER_DOWN = `onpointerdown="this.setAttribute('aria-checked', this.getAttribute('aria-checked') === 'true' ? 'false' : 'true')"`;
+
+export const SWITCH_FIXTURES: readonly SwitchFixture[] = [
+ // ---- conforming, one per representative state ---------------------------
+ {
+ id: 'conforming-off',
+ summary: 'a labelled native checkbox promoted to a switch, off',
+ facts: facts(),
+ html: nativeSwitch(),
+ },
+ {
+ id: 'conforming-on',
+ summary: 'the same switch, on',
+ facts: facts({checked: true}),
+ html: nativeSwitch('checked'),
+ },
+ {
+ id: 'conforming-described',
+ summary: 'a switch with supporting text attached as its description',
+ facts: facts({described: true}),
+ html:
+ '<p id="hint">Sends a notification for every mention.</p>' +
+ nativeSwitch('aria-describedby="hint"'),
+ },
+ {
+ id: 'conforming-label-hidden',
+ summary:
+ 'a switch named for assistive technology with nothing rendered visibly',
+ facts: facts(),
+ html: `<input ${SUBJECT_ATTRIBUTE} type="checkbox" role="switch" aria-label="Notifications">`,
+ },
+ {
+ id: 'conforming-label-sr-only',
+ summary:
+ 'a switch whose label is present but clipped away by the sr-only recipe',
+ facts: facts(),
+ html:
+ '<label for="fx" style="position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap">Notifications</label>' +
+ `<input id="fx" ${SUBJECT_ATTRIBUTE} type="checkbox" role="switch" aria-label="Notifications">`,
+ },
+ {
+ id: 'conforming-label-decoratively-clipped',
+ summary:
+ 'a readable label that happens to carry a decorative clip-path — visible, and it must not read as hidden',
+ facts: facts(),
+ html:
+ '<label for="fx" style="clip-path:circle(60%)">Notifications</label>' +
+ `<input id="fx" ${SUBJECT_ATTRIBUTE} type="checkbox" role="switch">`,
+ },
+ {
+ id: 'conforming-label-hidden-by-ancestor',
+ summary:
+ 'a label inside a hidden wrapper: nothing is readable, and the name comes from aria-label',
+ facts: facts(),
+ html:
+ '<div style="visibility:hidden"><label for="fx">Notifications</label></div>' +
+ `<input id="fx" ${SUBJECT_ATTRIBUTE} type="checkbox" role="switch" aria-label="Notifications">`,
+ },
+ {
+ id: 'conforming-disabled',
+ summary: 'a natively disabled switch',
+ facts: facts({disabled: true, operable: false, focusable: false}),
+ html: nativeSwitch('disabled'),
+ },
+ {
+ id: 'conforming-pending',
+ summary:
+ 'a switch that refuses its own change without being disabled — the case where "cannot be changed" and "reported disabled" come apart',
+ facts: facts({operable: false}),
+ html: nativeSwitch(
+ `onclick="event.preventDefault()" onkeydown="if (event.key === ' ') { event.preventDefault(); }"`,
+ ),
+ },
+ {
+ id: 'conforming-required',
+ summary: 'a required switch',
+ facts: facts({required: true}),
+ html: nativeSwitch('required'),
+ },
+ {
+ id: 'conforming-invalid',
+ summary: 'a switch reported as being in error',
+ facts: facts({invalid: true}),
+ html: nativeSwitch('aria-invalid="true"'),
+ },
+
+ // ---- one deliberate violation per expectation ---------------------------
+ {
+ id: 'violating-unnamed',
+ summary: 'a switch with no label at all',
+ facts: facts(),
+ html: `<input ${SUBJECT_ATTRIBUTE} type="checkbox" role="switch">`,
+ },
+ {
+ id: 'violating-name-mismatch',
+ summary: 'a switch whose aria-label replaces the visible label',
+ facts: facts(),
+ html: nativeSwitch('aria-label="Toggle"'),
+ },
+ {
+ id: 'violating-label-changes',
+ summary:
+ 'a switch whose label reads as the action, so it flips when the state does',
+ facts: facts(),
+ html: divSwitch(
+ `tabindex="0" aria-checked="false" onclick="const on = this.getAttribute('aria-checked') !== 'true'; this.setAttribute('aria-checked', String(on)); this.textContent = on ? 'Turn off notifications' : 'Turn on notifications';" onkeydown="if (event.key === ' ') { event.preventDefault(); this.click(); }"`,
+ 'Turn on notifications',
+ ),
+ },
+ {
+ id: 'violating-down-event-toggle',
+ summary:
+ 'a switch that changes on the way down, so a slip cannot be taken back',
+ facts: facts(),
+ html: divSwitch(
+ `tabindex="0" aria-checked="false" ${TOGGLE_ON_POINTER_DOWN} ${TOGGLE_ON_SPACE}`,
+ ),
+ },
+ {
+ id: 'violating-focus-moves-on-change',
+ summary:
+ 'a switch that throws focus somewhere else the moment it is changed',
+ facts: facts(),
+ html: nativeSwitch(`onchange="document.getElementById('after').focus()"`),
+ },
+ {
+ id: 'violating-checkbox-role',
+ summary: 'a checkbox that was never promoted to a switch',
+ facts: facts(),
+ html:
+ '<label for="fx">Notifications</label>' +
+ `<input id="fx" ${SUBJECT_ATTRIBUTE} type="checkbox">`,
+ },
+ {
+ id: 'violating-generic-element',
+ summary: 'a plain element with neither the role nor any state',
+ facts: facts({operable: false, focusable: false}),
+ html: `<div ${SUBJECT_ATTRIBUTE} tabindex="0">Notifications</div>`,
+ },
+ {
+ id: 'violating-state-mismatch',
+ summary: 'a switch rendered on while reporting itself off',
+ facts: facts({checked: true, operable: false, focusable: false}),
+ html: divSwitch('tabindex="0" aria-checked="false"'),
+ },
+ {
+ id: 'violating-dangling-description',
+ summary: 'a switch described by an id that resolves to nothing',
+ facts: facts({described: true}),
+ html: nativeSwitch('aria-describedby="hint"'),
+ },
+ {
+ id: 'violating-empty-description',
+ summary: 'a switch described by an element that renders no text',
+ facts: facts({described: true}),
+ html: '<p id="hint"></p>' + nativeSwitch('aria-describedby="hint"'),
+ },
+ {
+ id: 'violating-inert',
+ summary: 'a switch that never changes state',
+ // Same markup as violating-state-mismatch, different declaration: there,
+ // the binding says the switch renders ON and the markup says off, which is
+ // an exposure failure. Here it says off and means off, so the failure is
+ // that pressing it does nothing. One inert control, two separate outcomes.
+ facts: facts(),
+ html: divSwitch('tabindex="0" aria-checked="false"'),
+ },
+ {
+ id: 'violating-one-way',
+ summary: 'a switch that turns on and cannot be turned back off',
+ facts: facts(),
+ html: divSwitch(
+ `tabindex="0" aria-checked="false" onclick="this.setAttribute('aria-checked', 'true')" onkeydown="if (event.key === ' ') { event.preventDefault(); this.setAttribute('aria-checked', 'true'); }"`,
+ ),
+ },
+ {
+ id: 'violating-pointer-only',
+ summary: 'a switch that answers a pointer but ignores the keyboard',
+ facts: facts(),
+ html: divSwitch(`tabindex="0" aria-checked="false" ${TOGGLE_ON_CLICK}`),
+ },
+ {
+ id: 'violating-unreachable',
+ summary: 'a switch that is not in the tab sequence',
+ facts: facts(),
+ html: divSwitch(
+ `aria-checked="false" ${TOGGLE_ON_CLICK} ${TOGGLE_ON_SPACE}`,
+ ),
+ },
+ {
+ id: 'violating-keyboard-trap',
+ summary: 'a switch that swallows the Tab that would leave it',
+ facts: facts(),
+ html: nativeSwitch(
+ `onkeydown="if (event.key === 'Tab') { event.preventDefault(); }"`,
+ ),
+ },
+ {
+ id: 'violating-disabled-unexposed',
+ summary:
+ 'a switch that blocks its own change without saying it is disabled',
+ facts: facts({disabled: true, operable: false}),
+ html: nativeSwitch(`onclick="event.preventDefault()"`),
+ },
+ {
+ id: 'violating-disabled-operable',
+ summary: 'a switch marked disabled that still changes state',
+ facts: facts({disabled: true, operable: false}),
+ html: nativeSwitch('aria-disabled="true"'),
+ },
+ {
+ id: 'violating-required-unexposed',
+ summary: 'a switch that must be on but never says so',
+ facts: facts({required: true}),
+ html: nativeSwitch(),
+ },
+ {
+ id: 'violating-invalid-unexposed',
+ summary: 'a switch in error that never says so',
+ facts: facts({invalid: true}),
+ html: nativeSwitch(),
+ },
+];
+
+export function fixture(id: string): SwitchFixture {
+ const found = SWITCH_FIXTURES.find(candidate => candidate.id === id);
+ if (found == null) {
+ throw new Error(`unknown switch fixture "${id}"`);
+ }
+ return found;
+}
+
+/** The conforming fixtures every expectation must pass against (AST-020 FR11). */
+export const CONFORMING_FIXTURES: readonly string[] = SWITCH_FIXTURES.filter(
+ candidate => candidate.id.startsWith('conforming-'),
+).map(candidate => candidate.id);
+
+/**
+ * For each expectation, the fixtures that remove its outcome. Every expectation
+ * needs at least one, and the self-tests fail when one is missing — that is how
+ * "the contract can actually fail" stops being a claim (AST-020 FR11).
+ */
+export const SWITCH_MUTATIONS: Readonly<Record<string, readonly string[]>> = {
+ 'switch.description.resolvable': ['violating-dangling-description'],
+ 'switch.role.exposed': [
+ 'violating-checkbox-role',
+ 'violating-generic-element',
+ ],
+ 'switch.name.exposed': ['violating-unnamed'],
+ 'switch.state.exposed': [
+ 'violating-state-mismatch',
+ 'violating-generic-element',
+ ],
+ 'switch.description.exposed': ['violating-empty-description'],
+ 'switch.disabled.exposed': ['violating-disabled-unexposed'],
+ 'switch.required.declared': ['violating-required-unexposed'],
+ 'switch.invalid.exposed': ['violating-invalid-unexposed'],
+ 'switch.name.stable-across-change': ['violating-label-changes'],
+ 'switch.name.matches-visible-label': ['violating-name-mismatch'],
+ 'switch.state.survives-an-aborted-press': ['violating-down-event-toggle'],
+ 'switch.state.keeps-focus-on-change': [
+ 'violating-focus-moves-on-change',
+ // A switch that never changes cannot show that focus survives a change.
+ 'violating-inert',
+ ],
+ 'switch.state.pointer-round-trip': ['violating-inert', 'violating-one-way'],
+ 'switch.state.space-round-trip': [
+ 'violating-pointer-only',
+ 'violating-one-way',
+ ],
+ 'switch.focus.reachable-and-escapable': [
+ 'violating-unreachable',
+ 'violating-keyboard-trap',
+ ],
+ 'switch.state.inoperable': ['violating-disabled-operable'],
+};
diff --git a/internal/a11y-spec/src/patterns/switch.jsdom.test.ts b/internal/a11y-spec/src/patterns/switch.jsdom.test.ts
new file mode 100644
index 0000000000..b1fa474580
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/switch.jsdom.test.ts
@@ -0,0 +1,169 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file switch.jsdom.test.ts
+ * @input Uses ./switch (the contract), ./switch.fixtures (conforming and
+ * violating fixtures), ../harness/jsdom, ../run
+ * @output The contract's own proof at the DOM layer: every expectation passes
+ * against a conforming fixture, fails against a fixture that removes its
+ * outcome, and reports `unrun` when this harness cannot observe its layer.
+ * @position Self-test. Proves the CONTRACT, not any component — the fixtures are
+ * hand-written HTML with no Astryx in them.
+ *
+ * `docs/specs/AST-020/spec.md` FR11: each expectation must pass against a
+ * minimally conforming fixture and fail when its required outcome is
+ * deliberately removed, and the suite must tell a real violation apart from an
+ * unsupported harness operation.
+ *
+ * SYNC: The Chromium half of this proof is ./switch.chromium.spec.ts. Both read
+ * the same fixtures, so a new fixture is covered at whichever layers can see it.
+ */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {
+ citeSource,
+ describeExpectation,
+ requiredLayers,
+ unansweredDimensions,
+} from '../contract';
+import {JSDOM_OBSERVES, createJsdomHarness} from '../harness/jsdom';
+import {runBinding, type ExpectationResult} from '../run';
+import {SWITCH_PATTERN} from './switch';
+import {
+ CONFORMING_FIXTURES,
+ SUBJECT_SELECTOR,
+ SWITCH_MUTATIONS,
+ fixture,
+ type SwitchFixture,
+} from './switch.fixtures';
+
+const observableHere = SWITCH_PATTERN.expectations.filter(expectation =>
+ requiredLayers(expectation).every(layer => JSDOM_OBSERVES.includes(layer)),
+);
+
+afterEach(() => {
+ document.body.replaceChildren();
+});
+
+async function resultsFor(target: SwitchFixture) {
+ const container = document.createElement('div');
+ document.body.append(container);
+ const result = await runBinding({
+ contract: SWITCH_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ mount: async () => {
+ container.innerHTML = target.html;
+ const subject = container.querySelector(SUBJECT_SELECTOR);
+ if (subject == null) {
+ throw new Error(`fixture "${target.id}" marks no subject element`);
+ }
+ return createJsdomHarness({subject});
+ },
+ unmount: () => {
+ container.innerHTML = '';
+ },
+ });
+ return result.results;
+}
+
+function resultFor(
+ results: readonly ExpectationResult[],
+ id: string,
+): ExpectationResult {
+ const found = results.find(result => result.expectation === id);
+ if (found == null) {
+ throw new Error(`no result for ${id}`);
+ }
+ return found;
+}
+
+describe('switch contract — completeness', () => {
+ it('answers every completeness dimension', () => {
+ expect(unansweredDimensions(SWITCH_PATTERN)).toEqual([]);
+ });
+
+ it('gives every expectation at least one deliberately violating fixture', () => {
+ const missing = SWITCH_PATTERN.expectations
+ .filter(
+ expectation => (SWITCH_MUTATIONS[expectation.id] ?? []).length === 0,
+ )
+ .map(expectation => expectation.id);
+ expect(missing).toEqual([]);
+ });
+
+ it('has an expectation for every violating fixture it records', () => {
+ const ids = new Set(
+ SWITCH_PATTERN.expectations.map(expectation => expectation.id),
+ );
+ const orphans = Object.keys(SWITCH_MUTATIONS).filter(id => !ids.has(id));
+ expect(orphans).toEqual([]);
+ });
+
+ it('names every fixture it records a mutation against', () => {
+ for (const fixtures of Object.values(SWITCH_MUTATIONS)) {
+ for (const id of fixtures) {
+ expect(() => fixture(id)).not.toThrow();
+ }
+ }
+ });
+});
+
+describe('switch contract — the jsdom harness reports what it cannot see', () => {
+ it('reports an expectation above the DOM layer as unrun, never as a pass', async () => {
+ const results = await resultsFor(fixture('conforming-off'));
+ const above = results.filter(result => result.status === 'unrun');
+ // There is at least one, or the contract would be provable without a browser.
+ expect(above.length).toBeGreaterThan(0);
+ for (const result of above) {
+ expect(
+ ['unrun', 'not-applicable'],
+ `${result.expectation} in jsdom`,
+ ).toContain(result.status);
+ }
+ });
+});
+
+describe.each(observableHere.map(expectation => [expectation.id] as const))(
+ '%s',
+ id => {
+ const expectation = SWITCH_PATTERN.expectations.find(
+ candidate => candidate.id === id,
+ )!;
+
+ it.each(CONFORMING_FIXTURES.map(name => [name] as const))(
+ 'passes against %s (or does not apply to it)',
+ async name => {
+ const target = fixture(name);
+ const result = resultFor(await resultsFor(target), id);
+ expect(
+ ['pass', 'not-applicable'],
+ `${id} against ${name}: ${result.detail ?? ''}`,
+ ).toContain(result.status);
+ },
+ );
+
+ it.each((SWITCH_MUTATIONS[id] ?? []).map(name => [name] as const))(
+ 'fails against %s, which removes its outcome',
+ async name => {
+ const target = fixture(name);
+ const result = resultFor(await resultsFor(target), id);
+ expect(result.status, `${id} against ${name}`).toBe('fail');
+ expect(result.detail ?? '').not.toBe('');
+ },
+ );
+
+ it('carries its id and its normative source into every failure it reports', async () => {
+ const [violating] = SWITCH_MUTATIONS[id] ?? [];
+ const target = fixture(violating ?? CONFORMING_FIXTURES[0]!);
+ const result = resultFor(await resultsFor(target), id);
+ // AST-020 FR4: a failure has to be understandable without opening the
+ // runner, so the id and the citation travel with the result.
+ expect(result.description).toContain(id);
+ expect(result.description).toContain(citeSource(expectation.sources[0]));
+ expect(describeExpectation(expectation)).toBe(result.description);
+ });
+ },
+);
diff --git a/internal/a11y-spec/src/patterns/switch.ts b/internal/a11y-spec/src/patterns/switch.ts
new file mode 100644
index 0000000000..a480275253
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/switch.ts
@@ -0,0 +1,875 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file switch.ts
+ * @input Uses ../contract (definePattern and the expectation vocabulary)
+ * @output SWITCH_PATTERN — the adopted WAI-ARIA APG "switch" pattern as a
+ * reusable contract — and SwitchStateFacts, what a binding declares each of
+ * its states is supposed to be.
+ * @position The first authored pattern. Every later pattern is modelled on it.
+ *
+ * Adopted pattern: https://www.w3.org/WAI/ARIA/apg/patterns/switch/
+ *
+ * What this contract owns is the part of "is it a switch" that is the same for
+ * every component that adopts the pattern: the control is reported as a switch,
+ * it is named, its on/off state is exposed and matches what is rendered, the
+ * user can turn it on and back off with pointer and keyboard, focus can reach
+ * it and leave it, and a switch that cannot be operated says so. Everything
+ * that varies per component — callbacks, form participation, tooltip
+ * composition, styling — stays with the component (`docs/specs/AST-021/spec.md`
+ * FR5).
+ *
+ * SYNC: When an expectation changes, update
+ * - /internal/a11y-spec/README.md
+ * - /packages/core/src/Switch/__tests__/Switch.a11y.test.tsx (the jsdom binding)
+ * - /packages/core/src/Switch/__tests__/Switch.a11y.chromium.spec.ts (the Chromium binding)
+ */
+
+import {
+ definePattern,
+ type ApgRequirement,
+ type PatternContract,
+ type WcagCriterion,
+} from '../contract';
+
+const APG_URL = 'https://www.w3.org/WAI/ARIA/apg/patterns/switch/';
+const UNDERSTANDING = 'https://www.w3.org/WAI/WCAG22/Understanding';
+
+const WCAG_1_3_1: WcagCriterion = {
+ standard: 'wcag',
+ id: '1.3.1',
+ name: 'Info and Relationships',
+ level: 'A',
+ url: `${UNDERSTANDING}/info-and-relationships.html`,
+};
+const WCAG_2_1_1: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.1.1',
+ name: 'Keyboard',
+ level: 'A',
+ url: `${UNDERSTANDING}/keyboard.html`,
+};
+const WCAG_2_1_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.1.2',
+ name: 'No Keyboard Trap',
+ level: 'A',
+ url: `${UNDERSTANDING}/no-keyboard-trap.html`,
+};
+const WCAG_2_5_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.5.2',
+ name: 'Pointer Cancellation',
+ level: 'A',
+ url: `${UNDERSTANDING}/pointer-cancellation.html`,
+};
+const WCAG_3_2_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '3.2.2',
+ name: 'On Input',
+ level: 'A',
+ url: `${UNDERSTANDING}/on-input.html`,
+};
+const WCAG_2_5_3: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.5.3',
+ name: 'Label in Name',
+ level: 'A',
+ url: `${UNDERSTANDING}/label-in-name.html`,
+};
+const WCAG_3_3_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '3.3.2',
+ name: 'Labels or Instructions',
+ level: 'A',
+ url: `${UNDERSTANDING}/labels-or-instructions.html`,
+};
+const WCAG_4_1_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '4.1.2',
+ name: 'Name, Role, Value',
+ level: 'A',
+ url: `${UNDERSTANDING}/name-role-value.html`,
+};
+
+const APG_ROLE: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'switch',
+ requirement: 'The switch has role switch.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+const APG_LABEL: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'switch',
+ requirement:
+ 'The switch has an accessible label provided by visible text content, aria-labelledby, or aria-label.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+const APG_STATE: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'switch',
+ requirement:
+ 'When on, the switch has state aria-checked set to true; when off, false. An HTML input[type="checkbox"] uses the HTML checked attribute instead.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+const APG_DESCRIBEDBY: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'switch',
+ requirement:
+ 'If the presentation includes additional descriptive static text relevant to a switch, the switch has aria-describedby set to the id of the element containing the description.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+const APG_STABLE_LABEL: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'switch',
+ requirement:
+ 'It is critical the label on a switch does not change when its state changes.',
+ url: `${APG_URL}#aboutthispattern`,
+};
+const APG_SPACE: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'switch',
+ requirement: 'Space: when focus is on the switch, changes its state.',
+ url: `${APG_URL}#keyboardinteraction`,
+};
+
+/**
+ * How many Tab presses count as "reachable". Ten is generous for one control
+ * on a fixture page and short enough that an unreachable switch fails fast
+ * instead of hanging the run.
+ */
+const TAB_BUDGET = 10;
+
+/**
+ * An interaction expectation's claim is a real-browser one — pressing this
+ * turns it on — but the answer is read out of the accessibility tree, so it
+ * cannot run without both.
+ */
+const READS_THE_TREE = ['accessibility-tree'] as const;
+
+/** Applies to every state; the outcome never stops mattering. */
+const ALWAYS = {
+ condition: 'the binding renders the pattern at all',
+ test: () => true,
+};
+
+/**
+ * What a binding declares one of its states is supposed to be. The contract
+ * asks the browser what it actually exposes and compares it against this — so a
+ * binding cannot pass by being consistently wrong, and an expectation knows
+ * which states it applies to (AST-020 FR5, AST-021 FR4).
+ */
+export interface SwitchStateFacts {
+ /** Whether this state renders as on. */
+ readonly checked: boolean;
+ /** Whether the user is meant to be able to change it. */
+ readonly operable: boolean;
+ /** Whether it is meant to be reachable in the tab sequence. */
+ readonly focusable: boolean;
+ /** Whether it is meant to be exposed as unavailable. */
+ readonly disabled: boolean;
+ /** Whether supporting text is meant to be attached as a description. */
+ readonly described: boolean;
+ /** Whether it is meant to be exposed as required. */
+ readonly required: boolean;
+ /** Whether it is meant to be exposed as being in error. */
+ readonly invalid: boolean;
+}
+
+function onOff(checked: 'true' | 'false' | 'mixed' | null): string {
+ switch (checked) {
+ case 'true':
+ return 'on';
+ case 'false':
+ return 'off';
+ case 'mixed':
+ return 'partly on';
+ default:
+ return 'neither on nor off';
+ }
+}
+
+function collapse(value: string): string {
+ return value.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * The words of a label, as a speech-input user would say them.
+ *
+ * Exported: a binding comparing its own state inventory against the page needs
+ * the same notion of "the label's words" this contract uses, or the two would
+ * disagree about a label the component renders with a decorative separator.
+ *
+ * WCAG 2.5.3 is about words: its Understanding text asks that "the words which
+ * visually label a component are also the words associated with the component
+ * programmatically". Punctuation is not spoken, and Astryx renders a required
+ * marker as "Label ∙ Required" visually while the name computes as "Label
+ * Required" — the same words, one decorative separator apart. Comparing raw
+ * strings would report that as a failure, which would be wrong.
+ */
+export function spokenWords(value: string): readonly string[] {
+ return collapse(value)
+ .replace(/[^\p{L}\p{N}]+/gu, ' ')
+ .split(' ')
+ .filter(word => word !== '');
+}
+
+/**
+ * Whether `whole` says `part`'s words, in order and unbroken.
+ *
+ * A substring test would be wrong here: "Sync" is a substring of "Syncing
+ * photos" but a speech-input user saying "Sync" is not saying the label. Words
+ * are compared whole, and their order is kept.
+ *
+ */
+function saysInOrder(
+ whole: readonly string[],
+ part: readonly string[],
+): boolean {
+ if (part.length === 0) {
+ return true;
+ }
+ return whole.some((_, index) =>
+ part.every((word, offset) => whole[index + offset] === word),
+ );
+}
+
+/**
+ * Turn the switch and turn it back, checking the exposed state after each move.
+ * Half a round trip is not the outcome: a control that turns on and cannot turn
+ * off has failed the person using it just as completely as one that never
+ * turned on (AST-020 FR8).
+ */
+async function roundTrip(
+ start: boolean,
+ activate: () => Promise<void>,
+ read: () => Promise<'true' | 'false' | 'mixed' | null>,
+ how: string,
+): Promise<void> {
+ const from = start ? 'true' : 'false';
+ const to = start ? 'false' : 'true';
+ await activate();
+ const after = await read();
+ // The opposite value, not merely a different one: a switch that answers a
+ // press by reporting `mixed`, or by dropping its state entirely, has not
+ // been turned anywhere the user asked for.
+ if (after !== to) {
+ throw new Error(
+ `${how} left the switch ${onOff(after)}: it cannot be turned ${start ? 'off' : 'on'}`,
+ );
+ }
+ await activate();
+ const back = await read();
+ if (back !== from) {
+ throw new Error(
+ `${how} turned the switch ${onOff(after)}, but doing it again left it ${onOff(back)} instead of returning it to ${onOff(from)}: the change only goes one way`,
+ );
+ }
+}
+
+export const SWITCH_PATTERN: PatternContract<SwitchStateFacts> =
+ definePattern<SwitchStateFacts>({
+ pattern: 'switch',
+ url: 'https://www.w3.org/WAI/ARIA/apg/patterns/switch/',
+ scope:
+ 'One binary control that is reported as a switch, named, state-exposed, and operable by pointer and keyboard in both directions.',
+
+ expectations: [
+ {
+ id: 'switch.role.exposed',
+ outcome:
+ 'Assistive technology reports the control as a switch, so the user hears "on" and "off" rather than "checked" or nothing at all.',
+ sources: [WCAG_4_1_2, APG_ROLE],
+ covers: ['4.1.2-name-role-value', 'apg-interaction'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {role} = await subject.computed();
+ if (role !== 'switch') {
+ throw new Error(
+ role == null
+ ? 'the browser exposes no role for this control — it is not in the accessibility tree at all, so assistive technology cannot announce it'
+ : `the browser reports this control as "${role}", not as a switch`,
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.name.exposed',
+ outcome:
+ 'The switch has an accessible name, so the user knows which setting they are turning on or off.',
+ sources: [WCAG_4_1_2, WCAG_3_3_2, APG_LABEL],
+ covers: ['4.1.2-name-role-value', '3.3.2-labels-or-instructions'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {name} = await subject.computed();
+ if (name.trim() === '') {
+ throw new Error(
+ 'the browser computes no accessible name for this switch, so it is announced as an unlabelled control',
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.name.matches-visible-label',
+ outcome:
+ 'The accessible name contains the visible label, so someone using speech input can say what they can read.',
+ sources: [WCAG_2_5_3, APG_LABEL],
+ covers: ['2.5.3-label-in-name'],
+ // Applies to every state, and reads BOTH sides off the rendered page.
+ // Nothing here consults the binding: a criterion a binding could switch
+ // off by declaring something about itself would not be a criterion.
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'accessibility-tree',
+ alsoNeeds: ['real-browser'],
+ enforcement: 'required',
+ run: async ({subject, notApplicable}) => {
+ const visible = await subject.visibleLabelText();
+ if (visible == null) {
+ // Nothing is presented visually, so there is nothing for a speech
+ // user to say: 2.5.3 applies to "user interface components with
+ // labels that include text or images of text". Reported as such
+ // rather than returning — a silent return would read as a pass, and
+ // this state never exercised the outcome.
+ // `return` so the compiler follows the control flow; the call
+ // itself never returns.
+ return notApplicable(
+ 'this state renders no label where a person can read it, so there are no visible words for a speech-input user to say',
+ );
+ }
+ const {name} = await subject.computed();
+ if (!saysInOrder(spokenWords(name), spokenWords(visible))) {
+ throw new Error(
+ `the visible label reads "${visible}" but the browser computes the accessible name as "${name}", so speaking the visible label does not reach this control`,
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.state.exposed',
+ outcome:
+ 'The on/off state is exposed and matches what is rendered, so what the user hears is what they see.',
+ sources: [WCAG_4_1_2, APG_STATE],
+ covers: ['4.1.2-name-role-value', 'apg-interaction'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {checked} = await subject.computed();
+ if (checked == null) {
+ throw new Error(
+ 'the browser exposes no on/off state for this switch, so assistive technology cannot say whether the setting is on',
+ );
+ }
+ const expected = facts.checked ? 'true' : 'false';
+ if (checked !== expected) {
+ throw new Error(
+ `this state renders ${onOff(expected)} but the browser reports it as ${onOff(checked)}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.description.resolvable',
+ outcome:
+ 'Every piece of supporting text the switch points at exists, so none of the explanation is silently dropped.',
+ sources: [WCAG_1_3_1, APG_DESCRIBEDBY],
+ covers: ['1.3.1-info-and-relationships'],
+ appliesWhen: {
+ condition: 'the binding renders supporting text for this state',
+ test: facts => facts.described,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const attribute = await subject.attribute('aria-describedby');
+ const ids = (attribute ?? '').split(/\s+/).filter(Boolean);
+ if (ids.length === 0) {
+ throw new Error(
+ 'the binding renders supporting text for this state, but the switch has no aria-describedby, so the text is never attached to the control',
+ );
+ }
+ const targets = await subject.idReferences('aria-describedby');
+ const dangling = ids.filter((_, index) => targets[index] == null);
+ if (dangling.length > 0) {
+ throw new Error(
+ `aria-describedby points at ${dangling.map(id => `"${id}"`).join(', ')}, which ${dangling.length === 1 ? 'resolves' : 'resolve'} to nothing; that description never reaches anyone`,
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.description.exposed',
+ outcome:
+ 'The supporting text reaches the user as the control’s description, not just as nearby markup.',
+ sources: [WCAG_4_1_2, APG_DESCRIBEDBY],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding renders supporting text for this state',
+ test: facts => facts.described,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {description} = await subject.computed();
+ if (description.trim() === '') {
+ throw new Error(
+ 'the binding renders supporting text for this state, but the browser computes no accessible description, so the explanation is never announced with the control',
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.disabled.exposed',
+ outcome:
+ 'A switch the binding marks unavailable is reported as unavailable, instead of looking available and doing nothing.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding declares this state unavailable',
+ test: facts => facts.disabled,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {disabled} = await subject.computed();
+ if (!disabled) {
+ throw new Error(
+ 'the binding declares this state unavailable, but the browser reports the switch as available, so the user is invited to change something that will not change',
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.required.declared',
+ outcome:
+ 'A switch that has to be on declares it, so the obligation reaches assistive technology before the user submits.',
+ sources: [WCAG_3_3_2, WCAG_4_1_2],
+ covers: ['3.3.2-labels-or-instructions'],
+ appliesWhen: {
+ condition: 'this state is required',
+ test: facts => facts.required,
+ },
+ // The accessibility-tree layer would be the stronger place for this, but
+ // Chromium's protocol does not emit a `required` property for a checkbox
+ // (it reports the resulting constraint-validation `invalid` instead), so
+ // the honest layer for the claim is the declaration itself.
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const native = await subject.attribute('required');
+ const aria = await subject.attribute('aria-required');
+ if (native == null && aria !== 'true') {
+ throw new Error(
+ 'this state is required, but the switch declares neither the native required attribute nor aria-required="true", so nothing tells assistive technology the setting must be on',
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.invalid.exposed',
+ outcome:
+ 'A switch in error is reported as being in error, so the user can find what needs fixing.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'this state is in error',
+ test: facts => facts.invalid,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {invalid} = await subject.computed();
+ if (!invalid) {
+ throw new Error(
+ 'this state is in error, but the browser does not report the switch as invalid, so the error is only visible to people who can see the message',
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.state.pointer-round-trip',
+ outcome:
+ 'A pointer turns the switch on and back off, and the exposed state follows both ways.',
+ sources: [WCAG_4_1_2, APG_STATE],
+ covers: ['4.1.2-name-role-value', 'apg-interaction'],
+ appliesWhen: {
+ condition: 'the user is meant to be able to change this state',
+ test: facts => facts.operable,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: READS_THE_TREE,
+ enforcement: 'required',
+ run: async ({harness, subject, facts}) => {
+ await roundTrip(
+ facts.checked,
+ () => harness.click(subject),
+ async () => (await subject.computed()).checked,
+ 'clicking the switch',
+ );
+ },
+ },
+ {
+ id: 'switch.state.space-round-trip',
+ outcome:
+ 'With focus on the switch, Space turns it on and back off — the keyboard reaches the same function the pointer does.',
+ sources: [WCAG_2_1_1, APG_SPACE],
+ covers: ['2.1.1-keyboard', 'apg-interaction'],
+ appliesWhen: {
+ condition:
+ 'the user is meant to be able to change this state and to focus it',
+ test: facts => facts.operable && facts.focusable,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: READS_THE_TREE,
+ enforcement: 'required',
+ run: async ({harness, subject, facts}) => {
+ await subject.focus();
+ if (!(await subject.isFocused())) {
+ throw new Error(
+ 'the switch did not take focus, so Space never reaches it',
+ );
+ }
+ await roundTrip(
+ facts.checked,
+ () => harness.press('Space'),
+ async () => (await subject.computed()).checked,
+ 'pressing Space on the focused switch',
+ );
+ },
+ },
+ {
+ id: 'switch.name.stable-across-change',
+ outcome:
+ 'The name stays the same when the switch is turned on and off, so it keeps identifying the setting instead of describing the next action.',
+ sources: [APG_STABLE_LABEL, WCAG_4_1_2],
+ wcagOutcome:
+ 'The name in 4.1.2 identifies which setting this is; a name that flips with the state describes an action instead, and a screen-reader user hears the new name announced together with the state it contradicts.',
+ covers: ['apg-interaction'],
+ appliesWhen: {
+ condition: 'the user is meant to be able to change this state',
+ test: facts => facts.operable,
+ },
+ evidenceLayer: 'accessibility-tree',
+ alsoNeeds: ['real-browser'],
+ // The APG is emphatic about this ("it is critical"), but it is an APG
+ // requirement with no WCAG success criterion behind it, and no current
+ // Astryx record adopts label stability as a contract. Under AST-020 FR9
+ // that makes it advisory: it reports, and the day a record adopts it,
+ // this line and the enforcement change together.
+ enforcement: 'advisory',
+ advisoryBecause:
+ 'The requirement is APG-only. No WCAG 2.2 A/AA criterion states it, and no current Astryx record adopts it, so it reports rather than gating.',
+ run: async ({harness, subject}) => {
+ const before = (await subject.computed()).name;
+ await harness.click(subject);
+ const changed = (await subject.computed()).name;
+ if (collapse(changed) !== collapse(before)) {
+ throw new Error(
+ `turning the switch on renamed it from "${before}" to "${changed}", so its name describes the action rather than the setting`,
+ );
+ }
+ await harness.click(subject);
+ const back = (await subject.computed()).name;
+ if (collapse(back) !== collapse(before)) {
+ throw new Error(
+ `turning the switch back off renamed it from "${before}" to "${back}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.state.survives-an-aborted-press',
+ outcome:
+ 'A press the user slides off and releases elsewhere leaves the switch alone, so a misplaced touch can be taken back.',
+ sources: [WCAG_2_5_2],
+ covers: ['2.5.2-pointer-cancellation'],
+ appliesWhen: {
+ condition: 'the user is meant to be able to change this state',
+ test: facts => facts.operable,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: READS_THE_TREE,
+ enforcement: 'required',
+ run: async ({harness, subject}) => {
+ const before = (await subject.computed()).checked;
+ await harness.abortedPress(subject);
+ const after = (await subject.computed()).checked;
+ if (after !== before) {
+ throw new Error(
+ `pressing the switch and releasing away from it still turned it ${onOff(after)}: the change happens on the way down, so a press cannot be taken back`,
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.state.keeps-focus-on-change',
+ outcome:
+ 'Turning the switch on leaves focus on the switch, so a keyboard user is not thrown somewhere else mid-task.',
+ sources: [WCAG_3_2_2],
+ // Partly: see the 3.2.2 entry in `exemptions` for the half of the
+ // criterion a component-level run cannot see.
+ covers: ['3.2.2-on-input'],
+ appliesWhen: {
+ condition:
+ 'the user is meant to be able to change this state and to focus it',
+ test: facts => facts.operable && facts.focusable,
+ },
+ evidenceLayer: 'real-browser',
+ // The claim is about a CHANGE, so the state has to be read before and
+ // after: "focus stayed put" is worth nothing if nothing happened.
+ alsoNeeds: READS_THE_TREE,
+ enforcement: 'required',
+ run: async ({harness, subject}) => {
+ await subject.focus();
+ if (!(await subject.isFocused())) {
+ throw new Error(
+ 'the switch did not take focus, so this state cannot be changed from the keyboard at all',
+ );
+ }
+ const before = (await subject.computed()).checked;
+ await harness.press('Space');
+ const after = (await subject.computed()).checked;
+ if (after === before) {
+ throw new Error(
+ `pressing Space left the switch ${onOff(after)}, so nothing changed and this expectation has no change to judge`,
+ );
+ }
+ if (!(await subject.isFocused())) {
+ throw new Error(
+ `changing the switch to ${onOff(after)} moved focus off it, so the user is somewhere else without having asked to be`,
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.focus.reachable-and-escapable',
+ outcome:
+ 'Tab reaches the switch, and Tab again leaves it, so a keyboard user can get to the setting and carry on past it.',
+ sources: [WCAG_2_1_1, WCAG_2_1_2],
+ covers: ['2.1.1-keyboard', '2.1.2-no-keyboard-trap'],
+ appliesWhen: {
+ condition: 'this state is meant to be in the tab sequence',
+ test: facts => facts.focusable,
+ },
+ evidenceLayer: 'real-browser',
+ // No `alsoNeeds`: this one reads only where focus is, which is a real
+ // browser's own answer.
+ enforcement: 'required',
+ run: async ({harness, subject}) => {
+ await harness.resetFocus();
+ let reached = false;
+ for (let step = 0; step < TAB_BUDGET && !reached; step += 1) {
+ await harness.press('Tab');
+ reached = await subject.isFocused();
+ }
+ if (!reached) {
+ throw new Error(
+ `${TAB_BUDGET} presses of Tab from the start of the document never reached the switch, so a keyboard user cannot get to this setting`,
+ );
+ }
+ await harness.press('Tab');
+ if (await subject.isFocused()) {
+ throw new Error(
+ 'Tab did not move focus off the switch, so a keyboard user is stuck on it',
+ );
+ }
+ },
+ },
+ {
+ id: 'switch.state.inoperable',
+ outcome:
+ 'A switch the user is not meant to be able to change does not change when it is clicked or when Space is pressed on it.',
+ sources: [WCAG_4_1_2, APG_STATE],
+ covers: ['4.1.2-name-role-value'],
+ // Not keyed on `disabled`: a switch can also be temporarily
+ // unchangeable while it waits on the change it already started, and a
+ // second press that slips through queues a change nobody asked for.
+ appliesWhen: {
+ condition: 'the user is not meant to be able to change this state',
+ test: facts => !facts.operable,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: READS_THE_TREE,
+ enforcement: 'required',
+ run: async ({harness, subject, facts}) => {
+ const before = (await subject.computed()).checked;
+ await harness.click(subject, {ignoreAvailability: true});
+ const afterClick = (await subject.computed()).checked;
+ if (afterClick !== before) {
+ throw new Error(
+ `the user is not meant to be able to change this state, but clicking the switch turned it ${onOff(afterClick)}`,
+ );
+ }
+ // A switch kept focusable while it cannot be changed — the usual way
+ // to keep a reason or a pending state discoverable — still has to
+ // refuse the keyboard.
+ if (!facts.focusable) {
+ return;
+ }
+ await subject.focus();
+ if (!(await subject.isFocused())) {
+ throw new Error(
+ 'this state is meant to stay focusable while it cannot be changed — so the reason or the pending state stays discoverable — but the switch did not take focus',
+ );
+ }
+ await harness.press('Space');
+ const afterSpace = (await subject.computed()).checked;
+ if (afterSpace !== before) {
+ throw new Error(
+ `the user is not meant to be able to change this state, but pressing Space on the switch turned it ${onOff(afterSpace)}`,
+ );
+ }
+ },
+ },
+ ],
+
+ // Every completeness dimension this pattern does not own, and who does.
+ // A dimension answered neither here nor by an expectation's `covers` list is
+ // reported by `unansweredDimensions` and asserted empty by this pattern's
+ // suite (AST-020 FR5).
+ exemptions: {
+ '1.1.1-non-text-content': {
+ owner: 'the binding component',
+ verifiedBy:
+ "the component's own suite (Switch hides its track and thumb from assistive technology and renders its busy state as text) and the repository axe audit, `pnpm a11y:audit`",
+ reason:
+ 'The pattern owns one control node. Which decorative graphics a binding paints around that node, and whether each is hidden, is a per-component composition fact this contract never sees.',
+ },
+ '1.3.2-meaningful-sequence': {
+ owner: 'the composing page',
+ verifiedBy: "the component's DOM-order tests and page-level review",
+ reason:
+ 'A switch is a single control; the order it is read in relative to other content is decided by whatever composes it.',
+ },
+ '1.4.1-use-of-color': {
+ owner: 'the binding component and the theme',
+ verifiedBy:
+ "the component's forced-colors suite and the repository visual gate",
+ reason:
+ 'Not part-encoded, and deliberately so. WCAG is explicit that exposure to assistive technology contributes nothing here: "even if information that is conveyed by color differences is appropriately conveyed to assistive technologies, it does not necessarily pass this criterion". 1.4.1 is entirely about what a sighted person who cannot distinguish two colours can see, which is a pixel fact no layer this contract observes can read.',
+ },
+ '1.4.3-contrast-minimum': {
+ owner: 'the binding component and the theme',
+ verifiedBy:
+ 'the repository axe audit, `pnpm a11y:audit`, over the component stories, plus the visual gate',
+ reason:
+ 'Contrast is measured from resolved rendered colours over a real backdrop, which is the axe and visual layer rather than the accessibility tree.',
+ },
+ '1.4.11-non-text-contrast': {
+ owner: 'the binding component and the theme',
+ verifiedBy:
+ 'the repository axe audit, `pnpm a11y:audit`, plus the visual gate',
+ reason:
+ 'The track, thumb, and focus indicator are painted surfaces; their contrast is a rendered-colour measurement this contract cannot make.',
+ },
+ '2.4.2-page-titled': {
+ owner: 'the page',
+ verifiedBy:
+ 'page-level review and the application that hosts the control',
+ reason:
+ 'A component rendered in isolation owns no document title and cannot supply one.',
+ },
+ '2.4.3-focus-order': {
+ owner: 'the composing page',
+ verifiedBy:
+ 'page-level review; this contract proves only that the switch is one reachable stop that focus can also leave',
+ reason:
+ 'Order is a property of the sequence a page builds, not of a single focus stop.',
+ },
+ '2.4.4-link-purpose': {
+ owner: 'caller content',
+ verifiedBy: 'review of any link a caller places near the control',
+ reason: 'The adopted switch pattern has no link part.',
+ },
+ '2.4.6-headings-and-labels': {
+ owner: 'caller content and component review',
+ verifiedBy:
+ 'review of the label text against the setting it controls; this contract proves that a name exists and matches the visible label, not that the wording describes the purpose well',
+ reason:
+ 'Whether a label is descriptive is a judgement about wording that no runtime layer can make.',
+ },
+ '2.4.7-focus-visible': {
+ owner:
+ 'the interaction-modality architecture record and the binding component',
+ verifiedBy:
+ "the repository visual gate and the component's own focus-ring styling",
+ reason:
+ 'A focus indicator is a painted result. Astryx switches draw theirs on the track through an ancestor `:has(:focus-visible)` condition, so proving it means comparing pixels, which is the visual layer.',
+ },
+ '2.4.11-focus-not-obscured': {
+ owner: 'the composing page',
+ verifiedBy:
+ 'page-level and overlay review, plus the repository modal-close visibility guard',
+ reason:
+ 'Whether something covers a focused control depends on what else the page renders over it.',
+ },
+ '2.5.8-target-size': {
+ owner: 'the binding component and the composing page',
+ verifiedBy:
+ "the repository axe audit's `target-size` rule, which applies WCAG 2.2's spacing exception across neighbouring targets",
+ reason:
+ 'The exception that decides most real switches depends on the clearance between a target and its neighbours, which a binding rendered on its own cannot see.',
+ },
+ '3.1.1-language-of-page': {
+ owner: 'the page',
+ verifiedBy:
+ 'page-level review and the application that hosts the control',
+ reason:
+ 'A component rendered in isolation owns no document language and cannot supply one.',
+ },
+ '3.2.4-consistent-identification': {
+ owner: 'the design system',
+ verifiedBy:
+ 'this shared contract itself: every component that adopts the pattern binds to the same expectations, so repeated switches are identified the same way',
+ reason:
+ 'Consistency is a property of the whole set of adopters, which one binding cannot demonstrate.',
+ },
+ '3.2.2-on-input': {
+ owner: 'the caller, for its own onChange',
+ verifiedBy:
+ 'integration and page-level review of what a caller does in response to the change',
+ reason:
+ "A change of context is a change of user agent, viewport, focus, or content that changes the page's meaning. The switch owns exactly one of those: whether activating it moves focus. If a caller's onChange navigates, reloads, or rewrites the page around the control, that is the caller's context change to warn about before the user reaches the switch, and no run of one component can observe it.",
+ coversRemainderOnly: true,
+ },
+ '3.3.1-error-identification': {
+ owner: 'the binding component',
+ verifiedBy: "the component's own status-message tests",
+ reason:
+ 'Not part-encoded, and deliberately so. 3.3.1 is satisfied in TEXT — "the error must be indicated in text" — and WCAG says the programmatic half "is not required for this success criterion, but may be covered by other criteria such as 4.1.2". switch.invalid.exposed is that 4.1.2 outcome, so it contributes nothing here. The text itself is composed around the switch rather than being part of the control.',
+ },
+ '4.1.3-status-messages': {
+ owner:
+ 'the binding component, and the assistive-technology verification record for the announcement itself',
+ verifiedBy:
+ "the component's own live-region regression test, plus real-AT evidence under `docs/specs/AST-009/spec.md` whenever a change claims what is announced",
+ reason:
+ 'A status message is composed around the switch rather than being part of the control, and whether it is announced is a real-AT claim no automated layer here can settle.',
+ },
+ 'forced-colors': {
+ owner: 'the binding component and the theme',
+ verifiedBy:
+ "the component's forced-colors suite over the compiled CSS, plus manual review under Windows High Contrast",
+ reason:
+ 'Forced-colors output is a paint result; this contract observes semantics and behaviour, not paint.',
+ },
+ 'reduced-motion': {
+ owner: 'the binding component and the theme',
+ verifiedBy:
+ "the component's `prefers-reduced-motion` transition guard and the repository visual gate",
+ reason:
+ 'Motion is a rendered result over time, and no layer this contract observes can watch it.',
+ },
+ 'at-facing-strings': {
+ owner: 'the binding component',
+ verifiedBy:
+ 'the repository i18n catalog check and review of the strings a component renders for assistive technology',
+ reason:
+ 'Translation is a source-level concern: the rendered result this contract observes looks the same whichever language the string is in, so a lint-layer check is the only one that can see an untranslated string.',
+ },
+ },
+ });
diff --git a/internal/a11y-spec/src/report.ts b/internal/a11y-spec/src/report.ts
new file mode 100644
index 0000000000..83c1d64cdc
--- /dev/null
+++ b/internal/a11y-spec/src/report.ts
@@ -0,0 +1,218 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file report.ts
+ * @input Uses ./run (BindingResult) and ./contract (PatternContract)
+ * @output `summarize` and `formatReport` — the facts a reader needs, kept as
+ * separate facts — plus `blockingResults`, the gate over them, and
+ * `formatFailures`, the reader-legible failure block bindings assert on.
+ * @position Reporting layer. Also the gate: `blockingResults` decides what
+ * fails a build.
+ *
+ * `docs/specs/AST-021/spec.md` FR11 is the whole design here: report patterns,
+ * bindings, applicable expectations, passes, known failures, unrun layers, and
+ * exemptions SEPARATELY, and never collapse them into one percentage or grade.
+ * A pattern with one required failure is not "mostly conformant", and there is
+ * no number in this file that could be mistaken for saying it is.
+ *
+ * SYNC: When ./run.ts gains a status, add it here and to the README table.
+ */
+
+import type {PatternContract} from './contract';
+import type {BindingResult, ExpectationResult} from './run';
+
+export interface ReportCounts {
+ readonly pass: number;
+ readonly fail: number;
+ readonly knownFailure: number;
+ readonly unexpectedPass: number;
+ readonly notApplicable: number;
+ readonly unrun: number;
+}
+
+export interface Report {
+ readonly pattern: string;
+ readonly bindings: readonly BindingResult[];
+ readonly counts: ReportCounts;
+ /** Unrun evidence layers, so nothing reads a green run as full coverage. */
+ readonly unrunLayers: readonly string[];
+ /** Dimensions this pattern does not own, with the owner that does. */
+ readonly exemptions: readonly {
+ readonly dimension: string;
+ readonly owner: string;
+ readonly verifiedBy: string;
+ readonly reason: string;
+ /** True when expectations here cover part of it and the owner holds the rest. */
+ readonly remainderOnly: boolean;
+ /** For a part-encoded dimension: the expectations that carry the encoded half. */
+ readonly encodedBy: readonly string[];
+ }[];
+}
+
+function count(
+ results: readonly ExpectationResult[],
+ status: ExpectationResult['status'],
+): number {
+ return results.filter(result => result.status === status).length;
+}
+
+export function summarize<Facts>(
+ contract: PatternContract<Facts>,
+ bindings: readonly BindingResult[],
+): Report {
+ const results = bindings.flatMap(binding => binding.results);
+ // The layers that were actually out of reach, not the layers the unrun
+ // expectations are filed under: an interaction expectation is unrun in jsdom
+ // because of BOTH the browser it needs and the tree it reads the result from.
+ const unrunLayers = [
+ ...new Set(
+ results
+ .filter(result => result.status === 'unrun')
+ .flatMap(result => result.missingLayers ?? [result.evidenceLayer]),
+ ),
+ ].sort();
+
+ const exemptions = Object.entries(contract.exemptions)
+ .flatMap(([dimension, exemption]) =>
+ exemption == null
+ ? []
+ : [
+ {
+ dimension,
+ owner: exemption.owner,
+ verifiedBy: exemption.verifiedBy,
+ reason: exemption.reason,
+ remainderOnly: exemption.coversRemainderOnly === true,
+ encodedBy: contract.expectations
+ .filter(expectation =>
+ (expectation.covers as readonly string[]).includes(dimension),
+ )
+ .map(expectation => expectation.id),
+ },
+ ],
+ )
+ .sort((a, b) => a.dimension.localeCompare(b.dimension));
+
+ return {
+ pattern: contract.pattern,
+ bindings,
+ counts: {
+ pass: count(results, 'pass'),
+ fail: count(results, 'fail'),
+ knownFailure: count(results, 'known-failure'),
+ unexpectedPass: count(results, 'unexpected-pass'),
+ notApplicable: count(results, 'not-applicable'),
+ unrun: count(results, 'unrun'),
+ },
+ unrunLayers,
+ exemptions,
+ };
+}
+
+/**
+ * Expectations that never actually ran across a whole binding — every state
+ * reported `not-applicable` or `unrun`.
+ *
+ * A gate nothing exercises is not a gate. `definePattern` cannot catch this: it
+ * sees the contract, never the bindings, so whether an applicability condition
+ * matches any real state is only knowable once a binding has run. A binding
+ * asserts on this, so an expectation that quietly applies to nothing — through
+ * a condition no state meets, or an escape it always takes — is visible instead
+ * of counting as coverage.
+ */
+export function neverExercised(
+ bindings: readonly BindingResult[],
+): readonly string[] {
+ const seen = new Map<string, boolean>();
+ for (const binding of bindings) {
+ for (const result of binding.results) {
+ const ran =
+ result.status !== 'not-applicable' && result.status !== 'unrun';
+ seen.set(
+ result.expectation,
+ (seen.get(result.expectation) ?? false) || ran,
+ );
+ }
+ }
+ return [...seen.entries()]
+ .filter(([, ran]) => !ran)
+ .map(([expectation]) => expectation)
+ .sort();
+}
+
+/**
+ * The results that must fail a build.
+ *
+ * A `required` expectation that fails is a regression. An unexpected pass is a
+ * stale debt record, and AST-021 FR9 requires removing it rather than counting
+ * it. An `advisory` failure reports and does not gate (AST-020 FR9), and an
+ * `unrun` layer gates nothing — it is a coverage fact, reported as one.
+ */
+export function blockingResults(
+ bindings: readonly BindingResult[],
+): readonly {binding: BindingResult; result: ExpectationResult}[] {
+ return bindings.flatMap(binding =>
+ binding.results
+ .filter(
+ result =>
+ result.status === 'unexpected-pass' ||
+ (result.status === 'fail' && result.enforcement === 'required'),
+ )
+ .map(result => ({binding, result})),
+ );
+}
+
+/** A reader-legible failure block: which binding, which state, which layer, why. */
+export function formatFailures(
+ blocking: readonly {binding: BindingResult; result: ExpectationResult}[],
+): string {
+ return blocking
+ .map(
+ ({binding, result}) =>
+ `${binding.binding} [${binding.state}] via ${binding.harness}\n` +
+ ` ${result.description}\n` +
+ ` evidence layer: ${result.evidenceLayer} · enforcement: ${result.enforcement} · status: ${result.status}\n` +
+ ` ${(result.detail ?? '').split('\n').join('\n ')}`,
+ )
+ .join('\n\n');
+}
+
+/** The full factual report. Counts stay counts; there is no score to quote. */
+export function formatReport(report: Report): string {
+ const lines: string[] = [];
+ lines.push(`Accessibility spec-test report — pattern "${report.pattern}"`);
+ lines.push('');
+ for (const binding of report.bindings) {
+ lines.push(`${binding.binding} [${binding.state}] via ${binding.harness}`);
+ for (const result of binding.results) {
+ const suffix =
+ result.status === 'known-failure' && result.knownFailure != null
+ ? ` (${result.knownFailure.issue})`
+ : '';
+ lines.push(
+ ` ${result.status.padEnd(15)} ${result.expectation} · ${result.evidenceLayer} · ${result.enforcement}${suffix}`,
+ );
+ }
+ lines.push('');
+ }
+ const {counts} = report;
+ lines.push(
+ `pass ${counts.pass} · fail ${counts.fail} · known-failure ${counts.knownFailure} · ` +
+ `unexpected-pass ${counts.unexpectedPass} · not-applicable ${counts.notApplicable} · unrun ${counts.unrun}`,
+ );
+ lines.push(
+ report.unrunLayers.length === 0
+ ? 'unrun evidence layers: none in this run'
+ : `unrun evidence layers: ${report.unrunLayers.join(', ')}`,
+ );
+ for (const exemption of report.exemptions) {
+ // A dimension this pattern owns PART of reads differently from one it does
+ // not own at all, and collapsing the two would overstate the second.
+ lines.push(
+ exemption.remainderOnly
+ ? `part-encoded ${exemption.dimension} — encoded by ${exemption.encodedBy.join(', ')}; remainder → ${exemption.owner} (${exemption.verifiedBy})`
+ : `exempt ${exemption.dimension} → ${exemption.owner} (${exemption.verifiedBy})`,
+ );
+ }
+ return lines.join('\n');
+}
diff --git a/internal/a11y-spec/src/run.test.ts b/internal/a11y-spec/src/run.test.ts
new file mode 100644
index 0000000000..dcc00e42f4
--- /dev/null
+++ b/internal/a11y-spec/src/run.test.ts
@@ -0,0 +1,438 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file run.test.ts
+ * @input Uses ./contract, ./run, ./report and a stub harness
+ * @output Proof that a known failure changes only its own exact result, that an
+ * unobservable layer is reported rather than passed, and that the report
+ * keeps its facts apart.
+ * @position Runner self-test. These are the rules a migration depends on, so
+ * they are tested directly rather than through a component.
+ *
+ * `docs/specs/AST-021/spec.md` FR9 is the rule under test: "A different error,
+ * another state, a new expectation, or a wider failure MUST fail. When the
+ * expectation starts passing, CI MUST report an unexpected pass."
+ */
+
+import {describe, expect, it, vi} from 'vitest';
+import {definePattern, type PatternContract} from './contract';
+import type {EvidenceLayer, Harness, Subject} from './harness';
+import {
+ blockingResults,
+ formatReport,
+ neverExercised,
+ summarize,
+} from './report';
+import {runBinding, type KnownFailure} from './run';
+
+interface Facts {
+ readonly applicable: boolean;
+}
+
+const subject = {} as Subject;
+
+function harness(observes: readonly EvidenceLayer[]): Harness {
+ return {
+ name: 'stub',
+ observes,
+ subject: async () => subject,
+ click: async () => {},
+ abortedPress: async () => {},
+ press: async () => {},
+ resetFocus: async () => {},
+ };
+}
+
+function contractThat(
+ behaviour: () => void,
+ overrides: {
+ layer?: EvidenceLayer;
+ alsoNeeds?: readonly EvidenceLayer[];
+ enforcement?: 'required' | 'advisory';
+ } = {},
+): PatternContract<Facts> {
+ return definePattern<Facts>({
+ pattern: 'probe',
+ url: 'https://example.invalid/probe',
+ scope: 'A stub pattern used to test the runner.',
+ exemptions: {},
+ expectations: [
+ {
+ id: 'probe.outcome.observed',
+ outcome: 'The stub outcome happens.',
+ sources: [
+ {
+ standard: 'wcag',
+ id: '4.1.2',
+ name: 'Name, Role, Value',
+ level: 'A',
+ url: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+ },
+ ],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the state is applicable',
+ test: facts => facts.applicable,
+ },
+ evidenceLayer: overrides.layer ?? 'dom',
+ alsoNeeds: overrides.alsoNeeds,
+ enforcement: overrides.enforcement ?? 'required',
+ advisoryBecause:
+ overrides.enforcement === 'advisory'
+ ? 'Nothing adopts the stub outcome.'
+ : undefined,
+ run: async () => behaviour(),
+ },
+ ],
+ });
+}
+
+function knownFailure(overrides: Partial<KnownFailure> = {}): KnownFailure {
+ return {
+ expectation: 'probe.outcome.observed',
+ binding: 'Stub',
+ state: 'default',
+ evidenceLayer: 'dom',
+ failureIncludes: 'the stub outcome is missing',
+ userImpact: 'The stub does nothing for the user.',
+ issue: 'https://github.com/facebook/astryx/issues/1',
+ reason: 'Recorded by the migration; the fix is its own change.',
+ ...overrides,
+ };
+}
+
+async function run(
+ contract: PatternContract<Facts>,
+ options: {
+ facts?: Facts;
+ knownFailures?: readonly KnownFailure[];
+ observes?: readonly EvidenceLayer[];
+ state?: string;
+ } = {},
+) {
+ return runBinding({
+ contract,
+ binding: 'Stub',
+ state: options.state ?? 'default',
+ facts: options.facts ?? {applicable: true},
+ mount: async () => harness(options.observes ?? ['unit', 'dom']),
+ knownFailures: options.knownFailures,
+ });
+}
+
+const missing = () => {
+ throw new Error('the stub outcome is missing entirely');
+};
+
+describe('runBinding', () => {
+ it('passes when the outcome happens', async () => {
+ const result = await run(contractThat(() => {}));
+ expect(result.results[0]?.status).toBe('pass');
+ expect(blockingResults([result])).toEqual([]);
+ });
+
+ it('fails when the outcome is absent, and that blocks', async () => {
+ const result = await run(contractThat(missing));
+ expect(result.results[0]?.status).toBe('fail');
+ expect(result.results[0]?.detail).toContain('the stub outcome is missing');
+ expect(blockingResults([result])).toHaveLength(1);
+ });
+
+ it('does not run an expectation this state cannot change', async () => {
+ const behaviour = vi.fn();
+ const result = await run(contractThat(behaviour), {
+ facts: {applicable: false},
+ });
+ expect(behaviour).not.toHaveBeenCalled();
+ expect(result.results[0]?.status).toBe('not-applicable');
+ expect(result.results[0]?.detail).toContain('applies when');
+ });
+
+ it('reports an unobservable evidence layer instead of passing or skipping it', async () => {
+ const behaviour = vi.fn();
+ const result = await run(
+ contractThat(behaviour, {layer: 'accessibility-tree'}),
+ {observes: ['unit', 'dom']},
+ );
+ expect(behaviour).not.toHaveBeenCalled();
+ expect(result.results[0]?.status).toBe('unrun');
+ expect(result.results[0]?.detail).toContain('cannot observe');
+ expect(blockingResults([result])).toEqual([]);
+ });
+
+ it('reports unrun when a FURTHER layer the expectation reads is out of reach', async () => {
+ const behaviour = vi.fn();
+ // The shape of every interaction expectation: the claim is a real-browser
+ // one, but the answer is read out of the accessibility tree. A harness with
+ // the browser and no tree cannot run it, and must not fail it either.
+ const result = await run(
+ contractThat(behaviour, {
+ layer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ }),
+ {observes: ['unit', 'dom', 'real-browser']},
+ );
+ expect(behaviour).not.toHaveBeenCalled();
+ expect(result.results[0]?.status).toBe('unrun');
+ expect(result.results[0]?.missingLayers).toEqual(['accessibility-tree']);
+ expect(result.results[0]?.detail).toContain('accessibility-tree');
+ expect(blockingResults([result])).toEqual([]);
+ });
+
+ it('runs once every layer it reads is observable', async () => {
+ const behaviour = vi.fn();
+ const result = await run(
+ contractThat(behaviour, {
+ layer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ }),
+ {observes: ['unit', 'dom', 'accessibility-tree', 'real-browser']},
+ );
+ expect(behaviour).toHaveBeenCalled();
+ expect(result.results[0]?.status).toBe('pass');
+ });
+
+ describe('an expectation that discovers mid-run that it does not apply', () => {
+ it('reports not-applicable with its reason, never a pass', async () => {
+ const contract = contractThat(() => {});
+ const withEscape = definePattern<Facts>({
+ ...contract,
+ expectations: [
+ {
+ ...contract.expectations[0]!,
+ run: async ({notApplicable}) =>
+ notApplicable('the page has nothing for this to be about'),
+ },
+ ],
+ });
+ const result = await run(withEscape);
+ expect(result.results[0]?.status).toBe('not-applicable');
+ expect(result.results[0]?.detail).toBe(
+ 'the page has nothing for this to be about',
+ );
+ expect(blockingResults([result])).toEqual([]);
+ });
+
+ it('does not let a known-failure record turn it into recorded debt', async () => {
+ // An expectation that did not run has nothing to record a failure
+ // against, so the record must neither match nor go stale.
+ const contract = contractThat(() => {});
+ const withEscape = definePattern<Facts>({
+ ...contract,
+ expectations: [
+ {
+ ...contract.expectations[0]!,
+ run: async ({notApplicable}) => notApplicable('nothing to judge'),
+ },
+ ],
+ });
+ const result = await run(withEscape, {knownFailures: [knownFailure()]});
+ expect(result.results[0]?.status).toBe('not-applicable');
+ expect(result.results[0]?.knownFailure).toBeUndefined();
+ expect(blockingResults([result])).toEqual([]);
+ });
+
+ it('still fails when the expectation throws an ordinary error', async () => {
+ // The escape is the only thing that yields not-applicable: an expectation
+ // cannot reach it by failing in some other way.
+ const result = await run(contractThat(missing));
+ expect(result.results[0]?.status).toBe('fail');
+ });
+ });
+
+ it('reports an advisory failure without blocking', async () => {
+ const result = await run(contractThat(missing, {enforcement: 'advisory'}));
+ expect(result.results[0]?.status).toBe('fail');
+ expect(blockingResults([result])).toEqual([]);
+ });
+
+ describe('known failures', () => {
+ it('records the exact recorded failure as debt, never as a pass', async () => {
+ const result = await run(contractThat(missing), {
+ knownFailures: [knownFailure()],
+ });
+ expect(result.results[0]?.status).toBe('known-failure');
+ expect(result.results[0]?.knownFailure?.issue).toContain('issues/1');
+ expect(blockingResults([result])).toEqual([]);
+ });
+
+ it('fails on a different failure, rather than widening to cover it', async () => {
+ const result = await run(
+ contractThat(() => {
+ throw new Error('the stub outcome happened twice');
+ }),
+ {knownFailures: [knownFailure()]},
+ );
+ expect(result.results[0]?.status).toBe('fail');
+ expect(result.results[0]?.detail).toContain(
+ 'it covers a different failure',
+ );
+ expect(blockingResults([result])).toHaveLength(1);
+ });
+
+ it('fails in a state the record does not name', async () => {
+ const result = await run(contractThat(missing), {
+ state: 'another-state',
+ knownFailures: [knownFailure()],
+ });
+ expect(result.results[0]?.status).toBe('fail');
+ });
+
+ it('fails at an evidence layer the record does not name', async () => {
+ const result = await run(contractThat(missing), {
+ knownFailures: [knownFailure({evidenceLayer: 'real-browser'})],
+ });
+ expect(result.results[0]?.status).toBe('fail');
+ });
+
+ it('reports an unexpected pass when the recorded failure stops happening', async () => {
+ const result = await run(
+ contractThat(() => {}),
+ {
+ knownFailures: [knownFailure()],
+ },
+ );
+ expect(result.results[0]?.status).toBe('unexpected-pass');
+ expect(result.results[0]?.detail).toContain('remove the known-failure');
+ expect(blockingResults([result])).toHaveLength(1);
+ });
+ });
+
+ it('lets a broken mount surface instead of absorbing it as a result', async () => {
+ await expect(
+ runBinding({
+ contract: contractThat(() => {}),
+ binding: 'Stub',
+ state: 'default',
+ facts: {applicable: true},
+ mount: async () => {
+ throw new Error('the fixture never mounted');
+ },
+ knownFailures: [knownFailure()],
+ }),
+ ).rejects.toThrow('the fixture never mounted');
+ });
+});
+
+describe('the report keeps its facts apart', () => {
+ it('counts each status separately and quotes no score', async () => {
+ const contract = contractThat(missing);
+ const failing = await run(contract);
+ const known = await run(contract, {
+ state: 'known',
+ knownFailures: [knownFailure({state: 'known'})],
+ });
+ const skipped = await run(contract, {facts: {applicable: false}});
+
+ const report = summarize(contract, [failing, known, skipped]);
+ expect(report.counts).toEqual({
+ pass: 0,
+ fail: 1,
+ knownFailure: 1,
+ unexpectedPass: 0,
+ notApplicable: 1,
+ unrun: 0,
+ });
+
+ const text = formatReport(report);
+ expect(text).not.toMatch(/\d+\s*%/);
+ expect(text).not.toMatch(/score/i);
+ expect(text).toContain('known-failure 1');
+ });
+
+ it('names an expectation no state ever exercised', async () => {
+ // A gate nothing runs is not a gate, however green the report looks.
+ const base = contractThat(() => {});
+ const skipped = definePattern<Facts>({
+ ...base,
+ expectations: [
+ {
+ ...base.expectations[0]!,
+ appliesWhen: {condition: 'never, as it happens', test: () => false},
+ },
+ ],
+ });
+ const results = [
+ await run(skipped, {state: 'one'}),
+ await run(skipped, {state: 'two'}),
+ ];
+ expect(neverExercised(results)).toEqual(['probe.outcome.observed']);
+ });
+
+ it('says nothing when every expectation ran somewhere', async () => {
+ const contract = contractThat(() => {});
+ const results = [
+ await run(contract, {state: 'one', facts: {applicable: false}}),
+ await run(contract, {state: 'two'}),
+ ];
+ expect(neverExercised(results)).toEqual([]);
+ });
+
+ it('counts an unrun layer as not exercised', async () => {
+ const contract = contractThat(() => {}, {layer: 'real-browser'});
+ const results = [await run(contract, {observes: ['unit', 'dom']})];
+ expect(neverExercised(results)).toEqual(['probe.outcome.observed']);
+ });
+
+ it('tells a part-encoded dimension apart from a fully exempt one', async () => {
+ const base = contractThat(() => {});
+ const contract = definePattern<Facts>({
+ ...base,
+ exemptions: {
+ // Encoded by the stub expectation, remainder owned elsewhere.
+ '4.1.2-name-role-value': {
+ owner: 'the caller',
+ verifiedBy: 'integration review',
+ reason: 'One component cannot see the other half.',
+ coversRemainderOnly: true,
+ },
+ // Not owned here at all.
+ '2.4.7-focus-visible': {
+ owner: 'the theme',
+ verifiedBy: 'the visual gate',
+ reason: 'A focus ring is a painted result.',
+ },
+ },
+ });
+ const report = summarize(contract, [await run(contract)]);
+ const text = formatReport(report);
+
+ expect(text).toContain(
+ 'part-encoded 4.1.2-name-role-value — encoded by probe.outcome.observed; remainder → the caller',
+ );
+ // A reader of the report alone can see WHICH half is covered.
+ expect(
+ report.exemptions.find(e => e.dimension === '4.1.2-name-role-value')
+ ?.encodedBy,
+ ).toEqual(['probe.outcome.observed']);
+ expect(text).toContain('exempt 2.4.7-focus-visible → the theme');
+ // The part-encoded one must not read as fully exempt.
+ expect(text).not.toContain('exempt 4.1.2-name-role-value →');
+ expect(
+ report.exemptions.find(e => e.dimension === '4.1.2-name-role-value')
+ ?.remainderOnly,
+ ).toBe(true);
+ expect(
+ report.exemptions.find(e => e.dimension === '2.4.7-focus-visible')
+ ?.remainderOnly,
+ ).toBe(false);
+ });
+
+ it('names the layers that were not run, so a green run is not read as full coverage', async () => {
+ const contract = contractThat(() => {}, {layer: 'real-browser'});
+ const report = summarize(contract, [await run(contract)]);
+ expect(report.unrunLayers).toEqual(['real-browser']);
+ expect(formatReport(report)).toContain(
+ 'unrun evidence layers: real-browser',
+ );
+ });
+
+ it('names every layer that was out of reach, not just the one the expectation is filed under', async () => {
+ const contract = contractThat(() => {}, {
+ layer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ });
+ const report = summarize(contract, [await run(contract)]);
+ expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+ });
+});
diff --git a/internal/a11y-spec/src/run.ts b/internal/a11y-spec/src/run.ts
new file mode 100644
index 0000000000..b73366e820
--- /dev/null
+++ b/internal/a11y-spec/src/run.ts
@@ -0,0 +1,279 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file run.ts
+ * @input Uses ./contract (expectations), ./harness (the runtime seam)
+ * @output `runBinding` — runs one pattern contract against one component
+ * binding state — plus the known-failure vocabulary it obeys.
+ * @position The engine between a pattern and a component. Everything a report
+ * later says about a binding is decided here.
+ *
+ * The rules come from the accepted migration record,
+ * `docs/specs/AST-021/spec.md`:
+ *
+ * - FR8 a known failure names an expectation, a binding, a state, an evidence
+ * layer, the user impact, a public issue, and why it is not fixed here.
+ * - FR9 a known failure changes only its own exact result. A different error,
+ * another state, a new expectation, or a wider failure still fails, and
+ * an expectation that starts passing is reported as an unexpected pass
+ * so the stale record is removed rather than counted as debt forever.
+ * - FR10 required expectations that pass gate immediately.
+ *
+ * and from `docs/specs/AST-020/spec.md`:
+ *
+ * - Platform: a harness that cannot observe an assigned evidence layer reports
+ * that limitation. It does not pass, skip silently, or answer from a lower
+ * layer.
+ *
+ * SYNC: When a status is added, update ./report.ts and the README's status table.
+ */
+
+import {
+ NotApplicableHere,
+ describeExpectation,
+ requiredLayers,
+ type Enforcement,
+ type Expectation,
+ type PatternContract,
+} from './contract';
+import type {EvidenceLayer, Harness} from './harness';
+
+export type ResultStatus =
+ /** The outcome was observed. */
+ | 'pass'
+ /** The outcome was absent. */
+ | 'fail'
+ /** The exact recorded historical failure, still failing. Never a pass. */
+ | 'known-failure'
+ /** A recorded failure that now passes: the record is stale and must go. */
+ | 'unexpected-pass'
+ /** This state cannot change the outcome, so the expectation does not apply. */
+ | 'not-applicable'
+ /** No harness in this run can observe the assigned evidence layer. */
+ | 'unrun';
+
+/**
+ * One historical failure, pinned tightly enough that it cannot cover anything
+ * else (AST-021 FR8, FR9).
+ */
+export interface KnownFailure {
+ readonly expectation: string;
+ readonly binding: string;
+ readonly state: string;
+ readonly evidenceLayer: EvidenceLayer;
+ /**
+ * A distinctive fragment of the failure this record covers. A failure whose
+ * message does not contain it is a different failure, and still fails.
+ */
+ readonly failureIncludes: string;
+ /** What the person using the component actually experiences. */
+ readonly userImpact: string;
+ /** Public issue tracking the fix. */
+ readonly issue: string;
+ /** Why this migration records the gap instead of fixing it. */
+ readonly reason: string;
+}
+
+export interface ExpectationResult {
+ readonly expectation: string;
+ readonly description: string;
+ readonly outcome: string;
+ readonly evidenceLayer: EvidenceLayer;
+ readonly enforcement: Enforcement;
+ readonly status: ResultStatus;
+ /** Present for `fail`, `known-failure`, `not-applicable`, and `unrun`. */
+ readonly detail?: string;
+ /**
+ * For an `unrun` result: exactly which layers this run could not observe.
+ * Not always the expectation's own layer — an interaction expectation can be
+ * unrun because the tree it reads the result from is out of reach.
+ */
+ readonly missingLayers?: readonly EvidenceLayer[];
+ /** Present when a known-failure record was consulted. */
+ readonly knownFailure?: KnownFailure;
+}
+
+export interface BindingResult {
+ readonly pattern: string;
+ /** The component this binding is for, e.g. `Switch`. */
+ readonly binding: string;
+ /** The representative state, e.g. `off` or `focusable-disabled`. */
+ readonly state: string;
+ readonly harness: string;
+ readonly results: readonly ExpectationResult[];
+}
+
+export interface RunBindingOptions<Facts> {
+ readonly contract: PatternContract<Facts>;
+ readonly binding: string;
+ readonly state: string;
+ readonly facts: Facts;
+ /**
+ * Mount the binding fresh and return a harness pointed at it. Called once per
+ * expectation, so each one starts from the state the binding declares rather
+ * than from whatever the previous expectation left behind.
+ */
+ readonly mount: () => Promise<Harness>;
+ /** Unmount between expectations. */
+ readonly unmount?: () => Promise<void> | void;
+ /**
+ * Run only these expectation ids. Used by the contract's own mutation proof,
+ * which asks one expectation at a time whether it notices its outcome being
+ * removed. A binding leaves it unset and runs the whole contract.
+ */
+ readonly only?: readonly string[];
+ readonly knownFailures?: readonly KnownFailure[];
+}
+
+function messageOf(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+
+function findKnownFailure<Facts>(
+ known: readonly KnownFailure[],
+ expectation: Expectation<Facts>,
+ binding: string,
+ state: string,
+): KnownFailure | undefined {
+ return known.find(
+ record =>
+ record.expectation === expectation.id &&
+ record.binding === binding &&
+ record.state === state &&
+ record.evidenceLayer === expectation.evidenceLayer,
+ );
+}
+
+export async function runBinding<Facts>(
+ options: RunBindingOptions<Facts>,
+): Promise<BindingResult> {
+ const {contract, binding, state, facts, mount, unmount} = options;
+ const knownFailures = options.knownFailures ?? [];
+ const results: ExpectationResult[] = [];
+ let harnessName = 'unmounted';
+
+ for (const expectation of contract.expectations) {
+ if (options.only != null && !options.only.includes(expectation.id)) {
+ continue;
+ }
+ const base = {
+ expectation: expectation.id,
+ description: describeExpectation(expectation),
+ outcome: expectation.outcome,
+ evidenceLayer: expectation.evidenceLayer,
+ enforcement: expectation.enforcement,
+ } as const;
+
+ if (!expectation.appliesWhen.test(facts)) {
+ results.push({
+ ...base,
+ status: 'not-applicable',
+ detail: `applies when ${expectation.appliesWhen.condition}`,
+ });
+ continue;
+ }
+
+ let harness: Harness | undefined;
+ let failure: string | undefined;
+ let notApplicableReason: string | undefined;
+ let ran = false;
+
+ try {
+ const mounted = await mount();
+ harness = mounted;
+ harnessName = mounted.name;
+ const unobservable = requiredLayers(expectation).filter(
+ layer => !mounted.observes.includes(layer),
+ );
+ if (unobservable.length > 0) {
+ results.push({
+ ...base,
+ status: 'unrun',
+ missingLayers: unobservable,
+ detail: `the ${mounted.name} harness cannot observe the ${unobservable.join(' or ')} layer${unobservable.length === 1 ? '' : 's'} this expectation reads`,
+ });
+ continue;
+ }
+ ran = true;
+ const subject = await harness.subject();
+ await expectation.run({
+ harness,
+ subject,
+ facts,
+ notApplicable: reason => {
+ throw new NotApplicableHere(reason);
+ },
+ });
+ } catch (error) {
+ if (error instanceof NotApplicableHere) {
+ notApplicableReason = error.message;
+ } else {
+ failure = messageOf(error);
+ }
+ if (!ran) {
+ // The mount itself failed. That is a harness fault, not a contract
+ // result, and it must not be absorbed by a known-failure record.
+ throw error;
+ }
+ } finally {
+ await unmount?.();
+ }
+
+ if (notApplicableReason !== undefined) {
+ // Discovered from the page rather than declared up front. It is reported
+ // exactly like a declared one, so neither reads as a pass, and a
+ // known-failure record is deliberately NOT consulted: an expectation that
+ // did not run has nothing to record a failure against.
+ results.push({
+ ...base,
+ status: 'not-applicable',
+ detail: notApplicableReason,
+ });
+ continue;
+ }
+
+ const record = findKnownFailure(knownFailures, expectation, binding, state);
+
+ if (failure === undefined) {
+ results.push(
+ record == null
+ ? {...base, status: 'pass'}
+ : {
+ ...base,
+ status: 'unexpected-pass',
+ knownFailure: record,
+ detail: `the recorded failure no longer happens; remove the known-failure record and let ${record.issue} close`,
+ },
+ );
+ continue;
+ }
+
+ if (record != null && failure.includes(record.failureIncludes)) {
+ results.push({
+ ...base,
+ status: 'known-failure',
+ knownFailure: record,
+ detail: failure,
+ });
+ continue;
+ }
+
+ results.push({
+ ...base,
+ status: 'fail',
+ detail:
+ record == null
+ ? failure
+ : `${failure}\n\nA known failure is recorded for this expectation, binding, and state, but it covers a different failure (${JSON.stringify(record.failureIncludes)}). A known failure never widens to cover a new one.`,
+ knownFailure: record,
+ });
+ }
+
+ return {
+ pattern: contract.pattern,
+ binding,
+ state,
+ harness: harnessName,
+ results,
+ };
+}
diff --git a/internal/a11y-spec/src/storybook.ts b/internal/a11y-spec/src/storybook.ts
new file mode 100644
index 0000000000..070469d576
--- /dev/null
+++ b/internal/a11y-spec/src/storybook.ts
@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file storybook.ts
+ * @input Uses node:http, node:fs, node:path
+ * @output `serveStorybook` — a read-only static server over a built Storybook,
+ * for the Chromium lane to drive stories from.
+ * @position Binding infrastructure for the Playwright specs. Not part of the
+ * contract: it decides nothing about accessibility, it just puts checked-in
+ * stories in front of a real browser.
+ *
+ * Stories are the reproduction path on purpose. `docs/specs/AST-009/spec.md`
+ * FR30 asks that a scenario used for verification be checked in rather than
+ * living in a one-off page, and every other Chromium check in this repository
+ * already reads the same built Storybook.
+ *
+ * SYNC: The default directory matches the `storybook-<sha>` CI artifact path
+ * used by the accessibility job in .github/workflows/ci.yml.
+ */
+
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+
+export const DEFAULT_STORYBOOK_DIR = 'apps/storybook/dist';
+
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+ '.html': 'text/html; charset=utf-8',
+ '.js': 'text/javascript; charset=utf-8',
+ '.mjs': 'text/javascript; charset=utf-8',
+ '.css': 'text/css; charset=utf-8',
+ '.json': 'application/json; charset=utf-8',
+ '.svg': 'image/svg+xml',
+ '.png': 'image/png',
+ '.jpg': 'image/jpeg',
+ '.woff': 'font/woff',
+ '.woff2': 'font/woff2',
+};
+
+export interface StaticServer {
+ /** Origin to fetch stories from, e.g. `http://127.0.0.1:53312`. */
+ readonly origin: string;
+ close(): Promise<void>;
+}
+
+export async function serveStorybook(
+ directory = DEFAULT_STORYBOOK_DIR,
+): Promise<StaticServer> {
+ const root = path.resolve(directory);
+ if (!fs.existsSync(path.join(root, 'iframe.html'))) {
+ throw new Error(
+ `No built Storybook at ${root}. Run \`pnpm storybook:build\` first, or point ASTRYX_STORYBOOK_DIR at a build.`,
+ );
+ }
+
+ const server = http.createServer((request, response) => {
+ const requested = (request.url ?? '/').split('?')[0] ?? '/';
+ const resolved = path.resolve(
+ root,
+ `.${requested === '/' ? '/index.html' : requested}`,
+ );
+ // Never serve outside the built Storybook, whatever the URL asks for.
+ // The separator matters: a bare prefix test would also admit a sibling
+ // directory whose name merely starts with the root's.
+ const inside = resolved === root || resolved.startsWith(root + path.sep);
+ if (!inside || !fs.existsSync(resolved)) {
+ response.writeHead(404).end('not found');
+ return;
+ }
+ response.writeHead(200, {
+ 'content-type':
+ CONTENT_TYPES[path.extname(resolved)] ?? 'application/octet-stream',
+ });
+ fs.createReadStream(resolved).pipe(response);
+ });
+
+ await new Promise<void>(resolve => {
+ server.listen(0, '127.0.0.1', resolve);
+ });
+ const address = server.address();
+ if (address == null || typeof address === 'string') {
+ throw new Error('the Storybook server did not report a port');
+ }
+
+ return {
+ origin: `http://127.0.0.1:${address.port}`,
+ close: () =>
+ new Promise<void>((resolve, reject) => {
+ server.close(error => (error == null ? resolve() : reject(error)));
+ }),
+ };
+}
diff --git a/internal/a11y-spec/tsconfig.json b/internal/a11y-spec/tsconfig.json
new file mode 100644
index 0000000000..596e2cf729
--- /dev/null
+++ b/internal/a11y-spec/tsconfig.json
@@ -0,0 +1,4 @@
+{
+ "extends": "../../tsconfig.json",
+ "include": ["src"]
+}
diff --git a/package.json b/package.json
index 0f38eab881..a52270bce4 100644
--- a/package.json
+++ b/package.json
@@ -10,6 +10,7 @@
"test": "vitest run",
"test:watch": "vitest",
"test:coverage": "vitest --coverage",
+ "test:a11y-contract": "playwright test --config playwright.config.ts",
"check:package-boundaries": "node scripts/check-package-boundaries.js",
"check:repo": "pnpm check:sync && pnpm check:knowledge && pnpm check:package-boundaries && pnpm check:changesets && pnpm check:demo-media && pnpm check:executable-bits && pnpm check:cli-structure && pnpm check:use-client && pnpm check:portable-scripts && pnpm check:i18n-catalog && pnpm check:cldr-weekdays && pnpm check:fixtures && pnpm check:setup-contract",
"check:fixtures": "node internal/vibe-tests/scripts/fixture-suite.mjs verify",
diff --git a/packages/core/package.json b/packages/core/package.json
index fb3810956a..457f502134 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -681,6 +681,7 @@
"react-dom": ">=19.0.0"
},
"devDependencies": {
+ "@astryxdesign/a11y-spec": "workspace:*",
"@astryxdesign/cli": "workspace:*",
"@babel/cli": "^8.0.4",
"@babel/core": "^7.29.7",
diff --git a/packages/core/src/Switch/Switch.spec.md b/packages/core/src/Switch/Switch.spec.md
index c734c2cf7c..6fae3f77e8 100644
--- a/packages/core/src/Switch/Switch.spec.md
+++ b/packages/core/src/Switch/Switch.spec.md
@@ -13,6 +13,8 @@ review_triggers: [theming]
verified_by:
[
packages/core/src/Switch/Switch.test.tsx,
+ packages/core/src/Switch/__tests__/Switch.a11y.test.tsx,
+ packages/core/src/Switch/__tests__/Switch.a11y.chromium.spec.ts,
packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
@@ -97,6 +99,18 @@ This draft does not change or extend Switch's existing accessible name, switch
role, checked state, busy state, description/status association, or disabled
behavior.
+Switch binds to the shared switch-pattern accessibility contract
+(`internal/a11y-spec`, authored under
+[AST-020](../../../../docs/specs/AST-020/spec.md) and migrated under
+[AST-021](../../../../docs/specs/AST-021/spec.md)). The binding owns the
+standards-derived outcomes — role, accessible name, exposed on/off state,
+description, disabled exposure and inoperability, pointer and keyboard
+activation, pointer cancellation, and focus staying put on change — across the
+representative states listed in
+`__tests__/Switch.a11y.states.ts`. Callback payloads, form participation,
+disabled-reason tooltip composition, and styling remain Switch-owned and stay in
+`Switch.test.tsx`.
+
## Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
@@ -146,12 +160,16 @@ making the absence intentional.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ----------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| FR1 | `Switch.test.tsx` structure and interaction suites | On/off, size, label position, hidden label | Removing or reordering stable parts breaks existing role, label, or DOM assertions. | `audit:Switch/anatomy` |
-| FR2 | `Switch.test.tsx` label-target suite and `themingTargets.test.ts` | Current local targets | Removing the label target fails focused coverage; source/docs drift fails the target guard. | `audit:Switch/theming` |
-| FR3 | `Switch.test.tsx` loading and status suites | Busy and detached status | Removing composed feedback breaks existing spinner, busy-state, or message assertions. | `audit:Switch/anatomy` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and all current targets | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:Switch/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1 | `Switch.test.tsx` structure and interaction suites | On/off, size, label position, hidden label | Removing or reordering stable parts breaks existing role, label, or DOM assertions. | `audit:Switch/anatomy` |
+| FR2 | `Switch.test.tsx` label-target suite and `themingTargets.test.ts` | Current local targets | Removing the label target fails focused coverage; source/docs drift fails the target guard. | `audit:Switch/theming` |
+| FR3 | `Switch.test.tsx` loading and status suites | Busy and detached status | Removing composed feedback breaks existing spinner, busy-state, or message assertions. | `audit:Switch/anatomy` |
+| Switch pattern — semantics | `__tests__/Switch.a11y.test.tsx` (DOM layer, higher layers reported unrun) and `__tests__/Switch.a11y.chromium.spec.ts` (accessibility tree) | Off, on, on after a controlled update, described, hidden label, disabled, focusable-disabled, required, invalid, loading | Losing the switch role, the accessible name, the visible label's words within that name, the exposed on/off state, an attached description, or disabled, required, and invalid exposure fails the shared contract. | `audit:Switch/anatomy` |
+| Switch pattern — interaction | `__tests__/Switch.a11y.chromium.spec.ts` (real browser) | Every state, each checked for what applies to it: round trips, pointer cancellation, and focus-on-change cover the operable states (off, on, on after a controlled update, described, hidden label, required, invalid); Tab reach-and-escape covers every focusable state, adding focusable-disabled and loading; inoperability covers the states the user cannot change (disabled, focusable-disabled, loading). | Losing either direction of a pointer or Space round trip, letting a press slid off the control still change it (WCAG 2.5.2), moving focus when the state changes (WCAG 3.2.2), failing to reach or leave the control by Tab, or changing a state the user is not meant to be able to change fails the shared contract. | `audit:Switch/anatomy` |
+| Switch pattern — label stability | `__tests__/Switch.a11y.chromium.spec.ts`, reported not gated | Every operable state: off, on, on after a controlled update, described, hidden label, required, invalid | The APG requires the label not to change with the state. No current record adopts it, so the expectation is advisory: a name that flips across a round trip is reported, and does not fail the build. | `audit:Switch/anatomy` |
+| Switch pattern — state inventory | `__tests__/Switch.a11y.chromium.spec.ts` inventory assertion | Every bound state | The labels `__tests__/Switch.a11y.states.ts` claims each state renders are compared against the rendered page, so a stale inventory is reported as one rather than as a standards failure. | `audit:Switch/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and all current targets | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:Switch/theming` |
The focused Switch suite pins `switch-label`, but does not separately assert the
exact `switch-field`, `switch`, or `switch-thumb` class placement. The
diff --git a/packages/core/src/Switch/Switch.test.tsx b/packages/core/src/Switch/Switch.test.tsx
index d352513110..55652e779f 100644
--- a/packages/core/src/Switch/Switch.test.tsx
+++ b/packages/core/src/Switch/Switch.test.tsx
@@ -3,9 +3,22 @@
/**
* @file Switch.test.tsx
* @input Uses vitest, @testing-library/react, Switch component
- * @output Unit tests for Switch component behavior
+ * @output Unit tests for Switch's own contract: callbacks, form participation,
+ * composition, and styling
* @position Testing; validates Switch.tsx implementation
*
+ * The shared switch-pattern outcomes — role, accessible name, exposed on/off
+ * state, description, disabled exposure and inoperability, and keyboard and
+ * pointer activation — are owned by the reusable accessibility contract in
+ * __tests__/Switch.a11y.test.tsx (jsdom) and
+ * __tests__/Switch.a11y.chromium.spec.ts (real Chromium, where the computed
+ * accessibility tree and real focus can actually be observed). Assertions that
+ * this file used to duplicate now live there and are not repeated here.
+ *
+ * What stays here is Switch's own contract: callback payloads, form data,
+ * disabled-reason tooltip composition, the label theme target, forced-colors
+ * CSS, RTL thumb travel, and rest forwarding.
+ *
* SYNC: When Switch.tsx changes, update tests to match new behavior
*/
@@ -75,27 +88,6 @@ beforeEach(() => {
});
describe('Switch', () => {
- it('renders with label', () => {
- render(
- <Switch label="Enable notifications" value={false} onChange={() => {}} />,
- );
- expect(screen.getByLabelText('Enable notifications')).toBeInTheDocument();
- });
-
- it('renders as off by default', () => {
- render(
- <Switch label="Enable notifications" value={false} onChange={() => {}} />,
- );
- expect(screen.getByRole('switch')).not.toBeChecked();
- });
-
- it('renders as on when value prop is true', () => {
- render(
- <Switch label="Enable notifications" value={true} onChange={() => {}} />,
- );
- expect(screen.getByRole('switch')).toBeChecked();
- });
-
it('renders with custom size prop (sm / md)', () => {
const {rerender} = render(
<Switch
@@ -181,20 +173,6 @@ describe('Switch', () => {
).toBeInTheDocument();
});
- it('associates description with switch via aria-describedby', () => {
- render(
- <Switch
- label="Dark mode"
- description="Switch to a darker color scheme"
- value={false}
- onChange={() => {}}
- />,
- );
- const switchEl = screen.getByRole('switch');
- const description = screen.getByText('Switch to a darker color scheme');
- expect(switchEl).toHaveAttribute('aria-describedby', description.id);
- });
-
it('toggles when clicking on the description', async () => {
const user = userEvent.setup();
const handleChange = vi.fn();
@@ -229,18 +207,6 @@ describe('Switch', () => {
);
});
- it('is disabled when isDisabled prop is true', () => {
- render(
- <Switch
- label="Enable notifications"
- value={false}
- onChange={() => {}}
- isDisabled
- />,
- );
- expect(screen.getByRole('switch')).toBeDisabled();
- });
-
it('does not call onChange when isDisabled', async () => {
const user = userEvent.setup();
const handleChange = vi.fn();
@@ -302,6 +268,9 @@ describe('Switch', () => {
expect(getComputedStyle(row).gap).not.toMatch(/^0(px)?$/);
});
+ // Retained: the shared contract binds a hidden-label state and a described
+ // state, but not a hidden label WITH a description, which is the combination
+ // that used to drop the link.
it('keeps description linked via aria-describedby when isLabelHidden', () => {
render(
<Switch
@@ -360,13 +329,8 @@ describe('Switch', () => {
expect(children.length).toBe(2);
});
- it('has role="switch" for accessibility', () => {
- render(
- <Switch label="Enable notifications" value={false} onChange={() => {}} />,
- );
- expect(screen.getByRole('switch')).toBeInTheDocument();
- });
-
+ // Retained on purpose: the shared switch contract encodes no busy expectation
+ // — no current record adopts one — so this is the only thing gating it.
it('sets aria-busy on input when loading', () => {
render(
<Switch
@@ -391,6 +355,12 @@ describe('Switch', () => {
expect(screen.getByText('Failed to save setting')).toBeInTheDocument();
});
+ // Retained after review, not by oversight. The shared contract's
+ // switch.invalid.exposed proves that a switch in error is REPORTED in error,
+ // but the bound state is also `isRequired` and off, and Chromium derives an
+ // invalid state from constraint validation alone — so that expectation would
+ // still pass with this mapping deleted. Switch's own error-status-to-
+ // aria-invalid mapping is gated here, together with its negative below.
it('sets aria-invalid when status type is error', () => {
render(
<Switch
@@ -415,20 +385,6 @@ describe('Switch', () => {
expect(screen.getByRole('switch')).not.toHaveAttribute('aria-invalid');
});
- it('associates status message with switch via aria-describedby', () => {
- render(
- <Switch
- label="Enable notifications"
- value={false}
- onChange={() => {}}
- status={{type: 'error', message: 'Error message'}}
- />,
- );
- const switchEl = screen.getByRole('switch');
- const describedBy = switchEl.getAttribute('aria-describedby');
- expect(describedBy).toBeTruthy();
- });
-
// Regression: the status is conditionally mounted, so it must be announced
// through the persistent useAnnounce live region — a live region born
// together with its content is not reliably announced.
@@ -477,6 +433,11 @@ describe('Switch', () => {
expect(handleBlur).toHaveBeenCalled();
});
+ // Retained after review. The shared contract's switch.required.declared
+ // accepts either the native attribute or aria-required, because a non-native
+ // switch can only offer the latter — and Switch sets aria-required from a
+ // form-level default too. Only this test pins `isRequired` to the NATIVE
+ // attribute, which is what makes the browser block submission.
it('sets required attribute when isRequired is true', () => {
render(
<Switch
@@ -587,7 +548,10 @@ describe('Switch', () => {
expect(control.getAttribute('aria-describedby')).toContain(tooltip.id);
});
- it('blocks toggling while focusable-disabled', async () => {
+ // The shared switch contract owns whether a switch reported as unavailable
+ // actually stays unchanged; what stays here is Switch's own promise that it
+ // never calls back while blocked.
+ it('does not call onChange while focusable-disabled', async () => {
const user = userEvent.setup();
const onChange = vi.fn();
render(
@@ -599,10 +563,8 @@ describe('Switch', () => {
disabledMessage="Notifications are turned off org-wide"
/>,
);
- const control = screen.getByRole('switch', h);
- await user.click(control);
+ await user.click(screen.getByRole('switch', h));
expect(onChange).not.toHaveBeenCalled();
- expect(control).not.toBeChecked();
});
it('remains natively disabled when disabled without a reason', () => {
diff --git a/packages/core/src/Switch/__tests__/Switch.a11y.chromium.spec.ts b/packages/core/src/Switch/__tests__/Switch.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..53f99051f5
--- /dev/null
+++ b/packages/core/src/Switch/__tests__/Switch.a11y.chromium.spec.ts
@@ -0,0 +1,201 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Switch.a11y.chromium.spec.ts
+ * @input Uses @playwright/test, @astryxdesign/a11y-spec (the switch contract,
+ * the Chromium harness, the runner, the Storybook server) and the checked-in
+ * Switch stories
+ * @output The Chromium lane of Switch's binding to the shared switch pattern:
+ * the computed accessibility tree, real focus, and real activation.
+ * @position The lane that carries most of this contract. jsdom cannot compute a
+ * role or a name, cannot resolve a tab sequence, and cannot turn a key press
+ * into an activation, so those outcomes are proven here or not at all.
+ *
+ * Run it with:
+ * pnpm storybook:build && npx playwright install chromium
+ * pnpm test:a11y-contract
+ *
+ * SYNC: States live in ./Switch.a11y.states.ts, known failures in
+ * ./Switch.a11y.known-failures.ts, both shared with the jsdom lane.
+ */
+
+import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {
+ SWITCH_PATTERN,
+ blockingResults,
+ formatFailures,
+ formatReport,
+ neverExercised,
+ runBinding,
+ spokenWords,
+ summarize,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+ createChromiumHarness,
+ holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {SWITCH_KNOWN_FAILURES} from './Switch.a11y.known-failures';
+import {
+ REMOTE_CONTROL_LABEL,
+ SWITCH_BINDING_STATES,
+ type SwitchBindingState,
+} from './Switch.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+/** Load the story and put it into the state this row describes. */
+async function mountState(
+ page: Page,
+ state: SwitchBindingState,
+): Promise<void> {
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=${state.storyId}&viewMode=story`,
+ {waitUntil: 'load'},
+ );
+ await holdMotionStill(page);
+ const root = page.locator('#storybook-root');
+ await root.getByRole('switch').waitFor({state: 'attached'});
+ if (state.arrivesBy === 'controlled-update') {
+ // Getting into this state is the owner's doing, not the user's: the story's
+ // second control changes the value the switch is given. Doing it here, in
+ // the mount, keeps every expectation about the switch.
+ await root.getByRole('button', {name: REMOTE_CONTROL_LABEL}).click();
+ // A mount precondition, not a contract claim: if the owner's change never
+ // reached the control, every expectation below would be about a state this
+ // binding is not in.
+ await root
+ .getByRole('switch', {checked: state.facts.checked})
+ .waitFor({state: 'attached'});
+ }
+}
+
+async function runState(
+ page: Page,
+ cdp: CDPSession,
+ state: SwitchBindingState,
+): Promise<BindingResult> {
+ return runBinding({
+ contract: SWITCH_PATTERN,
+ binding: 'Switch',
+ state: state.id,
+ facts: state.facts,
+ knownFailures: SWITCH_KNOWN_FAILURES,
+ // Reload per expectation: each one starts from the state the story
+ // renders, not from whatever the previous expectation toggled it to.
+ mount: async () => {
+ await mountState(page, state);
+ return createChromiumHarness({
+ page,
+ subject: page.locator('#storybook-root').getByRole('switch'),
+ cdp,
+ });
+ },
+ });
+}
+
+/** Astryx renders these after the label text; they are not part of it. */
+const FIELD_MARKERS = ['required', 'optional'];
+
+/**
+ * Whether the page renders exactly the label the inventory claims.
+ *
+ * Word-for-word, not a prefix or a substring: "Sync" must not pass for "Sync
+ * photos", or a half-written entry would sit here unnoticed. The one allowance
+ * is Astryx's own trailing field marker, which the component adds and the
+ * inventory names the label without.
+ */
+function namesTheSameLabel(rendered: string, claimed: string): boolean {
+ const words = [...spokenWords(rendered)];
+ const last = words[words.length - 1];
+ if (last != null && FIELD_MARKERS.includes(last)) {
+ words.pop();
+ }
+ const expected = spokenWords(claimed);
+ return (
+ words.length === expected.length &&
+ words.every((word, index) => word === expected[index])
+ );
+}
+
+/**
+ * The inventory AST-021 FR2 asks for, checked against the page rather than
+ * trusted. It is deliberately NOT part of the shared contract: a wrong entry
+ * here is a stale inventory, and reporting it as a WCAG 2.5.3 failure would put
+ * a metadata typo and a real accessibility defect in the same bucket.
+ */
+test('the state inventory describes the labels the page actually renders', async ({
+ page,
+}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const wrong: string[] = [];
+ for (const state of SWITCH_BINDING_STATES) {
+ await mountState(page, state);
+ const harness = createChromiumHarness({
+ page,
+ subject: page.locator('#storybook-root').getByRole('switch'),
+ cdp,
+ });
+ const rendered = await (await harness.subject()).visibleLabelText();
+ const matches =
+ state.visibleLabel == null
+ ? rendered == null
+ : rendered != null && namesTheSameLabel(rendered, state.visibleLabel);
+ if (!matches) {
+ wrong.push(
+ `${state.id}: inventory says ${JSON.stringify(state.visibleLabel)}, page renders ${JSON.stringify(rendered)}`,
+ );
+ }
+ }
+ expect(wrong).toEqual([]);
+});
+
+test('every expectation is exercised by at least one bound state', async ({
+ page,
+}) => {
+ // A whole-binding sweep: every state, every expectation, a fresh mount each
+ // time. That is minutes of real browser work, not the seconds a single-state
+ // test takes.
+ test.setTimeout(5 * 60 * 1000);
+ const cdp = await page.context().newCDPSession(page);
+ const results: BindingResult[] = [];
+ for (const state of SWITCH_BINDING_STATES) {
+ results.push(await runState(page, cdp, state));
+ }
+ // An expectation that applies to nothing is not coverage, however green it
+ // looks. This is the only place that can notice: the contract never sees the
+ // states, so whether a condition matches a real one is a binding-side fact.
+ expect(neverExercised(results)).toEqual([]);
+});
+
+for (const state of SWITCH_BINDING_STATES) {
+ test(`Switch [${state.id}] — ${state.summary}`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const result = await runState(page, cdp, state);
+ const report = summarize(SWITCH_PATTERN, [result]);
+ // eslint-disable-next-line no-console -- the report is this run's artifact
+ console.log(formatReport(report));
+
+ expect(formatFailures(blockingResults([result]))).toBe('');
+ // Every layer this contract assigns is observable here, so a state that
+ // reports one as unrun means the harness lost a capability, not that the
+ // outcome is covered.
+ expect(report.unrunLayers).toEqual([]);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+}
diff --git a/packages/core/src/Switch/__tests__/Switch.a11y.known-failures.ts b/packages/core/src/Switch/__tests__/Switch.a11y.known-failures.ts
new file mode 100644
index 0000000000..30cc140390
--- /dev/null
+++ b/packages/core/src/Switch/__tests__/Switch.a11y.known-failures.ts
@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Switch.a11y.known-failures.ts
+ * @input Uses KnownFailure from @astryxdesign/a11y-spec
+ * @output SWITCH_KNOWN_FAILURES — the switch-pattern outcomes Switch does not
+ * deliver today, each pinned to one expectation, binding, state, and layer.
+ * @position Read by both Switch bindings. Nothing here is a pass: a recorded
+ * failure still runs, still fails, and is reported as debt.
+ *
+ * `docs/specs/AST-021/spec.md` FR8–FR10 govern this file:
+ *
+ * - a record names the expectation, binding, state, evidence layer, the user
+ * impact, a public issue, and why the migration does not fix it;
+ * - it covers only that exact failure — a different message, another state, or
+ * a wider failure still fails the build;
+ * - when the outcome starts passing, the run reports an unexpected pass and the
+ * record must be deleted rather than left standing.
+ *
+ * Adding or widening a record after the baseline is an owner decision with a
+ * linked defect, not a routine test update.
+ *
+ * SYNC: Deleting a record should close, or follow, its linked issue.
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const SWITCH_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];
diff --git a/packages/core/src/Switch/__tests__/Switch.a11y.states.ts b/packages/core/src/Switch/__tests__/Switch.a11y.states.ts
new file mode 100644
index 0000000000..e226e40df3
--- /dev/null
+++ b/packages/core/src/Switch/__tests__/Switch.a11y.states.ts
@@ -0,0 +1,275 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Switch.a11y.states.ts
+ * @input Uses SwitchStateFacts from @astryxdesign/a11y-spec and SwitchProps
+ * @output SWITCH_BINDING_STATES — every Switch state that can change the shared
+ * switch-pattern outcome, what each declares itself to be, and how each is
+ * mounted in either lane.
+ * @position The binding inventory required before any assertion moves
+ * (`docs/specs/AST-021/spec.md` FR2, FR4). Shared by the jsdom and Chromium
+ * bindings so both cover the same states and cannot drift apart.
+ *
+ * A state earns a row when it can change what the switch pattern promises: a
+ * different exposed state, a different operability, a different name source, a
+ * different attached description. States that change only appearance — size,
+ * label position, label spacing, width, theme — cannot, so they stay in
+ * Switch.test.tsx where the component owns them.
+ *
+ * SYNC: Every row's `storyId` must exist in
+ * - /apps/storybook/stories/Switch.stories.tsx
+ */
+
+import type {SwitchStateFacts} from '@astryxdesign/a11y-spec';
+import type {SwitchProps} from '../Switch';
+
+/**
+ * The label of the second control the ControlledUpdate story renders beside the
+ * switch. Both lanes press it to reach `on-after-controlled-update`.
+ *
+ * SYNC: /apps/storybook/stories/Switch.stories.tsx — the ControlledUpdate story
+ */
+export const REMOTE_CONTROL_LABEL = 'Turn on remotely';
+
+export interface SwitchBindingState {
+ /** Stable state id. Named by known-failure records, so it does not churn. */
+ readonly id: string;
+ /** What this state is, for the report and the test name. */
+ readonly summary: string;
+ /**
+ * What the state declares itself to be. `checked` is compared against what
+ * the browser exposes, so a binding cannot pass by rendering on and reporting
+ * off. The rest select which expectations apply to this state — declaring a
+ * state described, disabled, required, or in error turns those expectations
+ * on; it does not assert the negative when they are false.
+ */
+ readonly facts: SwitchStateFacts;
+ /**
+ * The label this state is expected to render where a person can read it, or
+ * null when it renders none.
+ *
+ * INVENTORY, not contract input. The shared 2.5.3 expectation reads the
+ * rendered label itself and never consults this — otherwise a binding could
+ * switch a criterion off by describing itself. This exists so the inventory
+ * AST-021 FR2 asks for is checked against the page rather than trusted, and a
+ * typo here is reported as a stale inventory, not as a standards failure.
+ */
+ readonly visibleLabel: string | null;
+ /**
+ * The props the jsdom lane renders the switch with. `value` is always the
+ * value it is FIRST rendered with — for a state the owner updates into, that
+ * is the value before the update, and `facts.checked` is where the update
+ * takes it.
+ */
+ readonly props: Omit<SwitchProps, 'onChange'>;
+ /** The checked-in Storybook story the Chromium lane drives. */
+ readonly storyId: string;
+ /**
+ * How this state comes to be, when it is not simply how the binding first
+ * renders. `controlled-update` means the switch renders with `props.value`
+ * and the owner then moves it to `facts.checked` through a second control —
+ * nobody touched the switch — so both lanes press that control during mount
+ * rather than asserting anything about it.
+ */
+ readonly arrivesBy?: 'controlled-update';
+}
+
+export const SWITCH_BINDING_STATES: ReadonlyArray<SwitchBindingState> = [
+ {
+ id: 'off',
+ summary: 'the default: a labelled switch that is off and can be turned on',
+ storyId: 'core-switch--default',
+ visibleLabel: 'Enable notifications',
+ props: {label: 'Enable notifications', value: false},
+ facts: {
+ checked: false,
+ operable: true,
+ focusable: true,
+ disabled: false,
+ described: false,
+ required: false,
+ invalid: false,
+ },
+ },
+ {
+ id: 'on',
+ summary: 'a switch whose controlled value is already on',
+ storyId: 'core-switch--on',
+ visibleLabel: 'Notifications enabled',
+ props: {label: 'Notifications enabled', value: true},
+ facts: {
+ checked: true,
+ operable: true,
+ focusable: true,
+ disabled: false,
+ described: false,
+ required: false,
+ invalid: false,
+ },
+ },
+ {
+ id: 'described',
+ summary: 'a switch with supporting text under its label',
+ storyId: 'core-switch--with-description',
+ visibleLabel: 'Dark mode',
+ props: {
+ label: 'Dark mode',
+ description: 'Switch to a darker color scheme for reduced eye strain.',
+ value: false,
+ },
+ facts: {
+ checked: false,
+ operable: true,
+ focusable: true,
+ disabled: false,
+ described: true,
+ required: false,
+ invalid: false,
+ },
+ },
+ {
+ id: 'label-hidden',
+ summary:
+ 'a switch whose label is read by assistive technology but not rendered visibly',
+ storyId: 'core-switch--with-hidden-label',
+ visibleLabel: null,
+ props: {label: 'Toggle row', isLabelHidden: true, value: false},
+ facts: {
+ checked: false,
+ operable: true,
+ focusable: true,
+ disabled: false,
+ // Nothing is rendered visibly, so WCAG 2.5.3 has nothing to compare against.
+ described: false,
+ required: false,
+ invalid: false,
+ },
+ },
+ {
+ id: 'disabled',
+ summary: 'a natively disabled switch, out of the tab sequence',
+ storyId: 'core-switch--disabled',
+ visibleLabel: 'Premium feature',
+ props: {
+ label: 'Premium feature',
+ description: 'Upgrade to enable this option',
+ isDisabled: true,
+ value: false,
+ },
+ facts: {
+ checked: false,
+ operable: false,
+ focusable: false,
+ disabled: true,
+ described: true,
+ required: false,
+ invalid: false,
+ },
+ },
+ {
+ id: 'focusable-disabled',
+ summary:
+ 'a switch disabled with a reason: still focusable so the reason is discoverable, still not operable',
+ storyId: 'core-switch--disabled-with-message',
+ visibleLabel: 'Enable notifications',
+ props: {
+ label: 'Enable notifications',
+ isDisabled: true,
+ disabledMessage: 'Notifications are turned off org-wide',
+ value: false,
+ },
+ facts: {
+ checked: false,
+ operable: false,
+ focusable: true,
+ disabled: true,
+ described: true,
+ required: false,
+ invalid: false,
+ },
+ },
+ {
+ id: 'required',
+ summary: 'a switch that has to be on before the form can be submitted',
+ storyId: 'core-switch--required',
+ visibleLabel: 'Accept terms and conditions',
+ props: {
+ label: 'Accept terms and conditions',
+ isRequired: true,
+ value: false,
+ },
+ facts: {
+ checked: false,
+ operable: true,
+ focusable: true,
+ disabled: false,
+ described: false,
+ required: true,
+ invalid: false,
+ },
+ },
+ {
+ id: 'invalid',
+ // Chromium also derives an invalid state from constraint validation on a
+ // required-but-off checkbox, so this state proves that a switch in error is
+ // reported as being in error — not that Switch's own error-status-to-
+ // aria-invalid mapping is what does it. That mapping stays gated in
+ // Switch.test.tsx.
+ summary: 'a required switch reporting an error, with the message attached',
+ storyId: 'core-switch--with-error-status',
+ visibleLabel: 'Accept terms and conditions',
+ props: {
+ label: 'Accept terms and conditions',
+ isRequired: true,
+ status: {
+ type: 'error',
+ message: 'You must accept the terms to continue',
+ },
+ value: false,
+ },
+ facts: {
+ checked: false,
+ operable: true,
+ focusable: true,
+ disabled: false,
+ described: true,
+ required: true,
+ invalid: true,
+ },
+ },
+ {
+ id: 'on-after-controlled-update',
+ summary:
+ 'a switch the owner turned on through another control — the value changed, nobody touched the switch',
+ storyId: 'core-switch--controlled-update',
+ arrivesBy: 'controlled-update',
+ visibleLabel: 'Sync photos',
+ props: {label: 'Sync photos', value: false},
+ facts: {
+ checked: true,
+ operable: true,
+ focusable: true,
+ disabled: false,
+ described: false,
+ required: false,
+ invalid: false,
+ },
+ },
+ {
+ id: 'loading',
+ summary:
+ 'a switch waiting on the change it started: focusable, busy, and not operable until it settles',
+ storyId: 'core-switch--loading',
+ visibleLabel: 'Sync photos',
+ props: {label: 'Sync photos', isLoading: true, value: false},
+ facts: {
+ checked: false,
+ operable: false,
+ focusable: true,
+ disabled: false,
+ described: false,
+ required: false,
+ invalid: false,
+ },
+ },
+];
diff --git a/packages/core/src/Switch/__tests__/Switch.a11y.test.tsx b/packages/core/src/Switch/__tests__/Switch.a11y.test.tsx
new file mode 100644
index 0000000000..0902705862
--- /dev/null
+++ b/packages/core/src/Switch/__tests__/Switch.a11y.test.tsx
@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Switch.a11y.test.tsx
+ * @input Uses @astryxdesign/a11y-spec (the switch contract, the jsdom harness,
+ * the runner), @testing-library/react, and the Switch component
+ * @output The jsdom lane of Switch's binding to the shared switch pattern.
+ * @position Binds Switch to the reusable contract at the layers jsdom can
+ * honestly observe. The accessibility-tree and real-browser layers are bound
+ * in Switch.a11y.chromium.spec.ts, and this lane reports them as unrun rather
+ * than pretending markup proves them.
+ *
+ * What is NOT here is as deliberate as what is. Callback payloads, form
+ * participation, tooltip composition, and styling stay in Switch.test.tsx: they
+ * are Switch's own contract, not the switch pattern's
+ * (`docs/specs/AST-021/spec.md` FR5).
+ *
+ * SYNC: States live in ./Switch.a11y.states.ts, known failures in
+ * ./Switch.a11y.known-failures.ts, both shared with the Chromium lane.
+ */
+
+import {useState} from 'react';
+import {describe, expect, it} from 'vitest';
+import {cleanup, fireEvent, render, screen} from '@testing-library/react';
+import {
+ SWITCH_PATTERN,
+ blockingResults,
+ createJsdomHarness,
+ formatFailures,
+ summarize,
+ runBinding,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {Switch, type SwitchProps} from '../Switch';
+import {SWITCH_KNOWN_FAILURES} from './Switch.a11y.known-failures';
+import {
+ REMOTE_CONTROL_LABEL,
+ SWITCH_BINDING_STATES,
+ type SwitchBindingState,
+} from './Switch.a11y.states';
+
+/**
+ * Switch is controlled, so a binding that pinned `value` would be testing a
+ * switch nobody ships. The wrapper is the consumer's own wiring.
+ */
+function ControlledSwitch({value, ...props}: Omit<SwitchProps, 'onChange'>) {
+ const [checked, setChecked] = useState(value);
+ return <Switch {...props} value={checked} onChange={setChecked} />;
+}
+
+/**
+ * The same switch, plus a second control its owner uses to change the value.
+ * This is the controlled-update case: the value changes because the owner
+ * changed it, not because anyone touched the switch — and the switch stays
+ * operable afterwards. Mirrors the ControlledUpdate story the Chromium lane
+ * drives, including the order, so Tab still reaches the switch first.
+ */
+function RemotelyToggledSwitch({
+ value,
+ movesTo,
+ ...props
+}: Omit<SwitchProps, 'onChange'> & {movesTo: boolean}) {
+ const [checked, setChecked] = useState(value);
+ return (
+ <>
+ <Switch {...props} value={checked} onChange={setChecked} />
+ <button type="button" onClick={() => setChecked(movesTo)}>
+ {REMOTE_CONTROL_LABEL}
+ </button>
+ </>
+ );
+}
+
+async function runState(state: SwitchBindingState): Promise<BindingResult> {
+ return runBinding({
+ contract: SWITCH_PATTERN,
+ binding: 'Switch',
+ state: state.id,
+ facts: state.facts,
+ knownFailures: SWITCH_KNOWN_FAILURES,
+ mount: async () => {
+ if (state.arrivesBy === 'controlled-update') {
+ render(
+ <RemotelyToggledSwitch
+ {...state.props}
+ movesTo={state.facts.checked}
+ />,
+ );
+ fireEvent.click(
+ screen.getByRole('button', {name: REMOTE_CONTROL_LABEL}),
+ );
+ // A mount precondition, not a contract claim: if the owner's change
+ // never reached the control, every expectation below would be about a
+ // state this binding is not in.
+ const control = screen.getByRole('switch', {hidden: true});
+ if ((control as HTMLInputElement).checked !== state.facts.checked) {
+ throw new Error(
+ `mounting "${state.id}" did not reach the declared state: the owner's change left the switch ${(control as HTMLInputElement).checked ? 'on' : 'off'}`,
+ );
+ }
+ } else {
+ render(<ControlledSwitch {...state.props} />);
+ }
+ return createJsdomHarness({
+ subject: screen.getByRole('switch', {hidden: true}),
+ });
+ },
+ unmount: cleanup,
+ });
+}
+
+describe('Switch — the shared switch pattern, jsdom lane', () => {
+ it.each(
+ SWITCH_BINDING_STATES.map(
+ state => [state.id, state.summary, state] as const,
+ ),
+ )('%s (%s)', async (_id, _summary, state) => {
+ const result = await runState(state);
+ expect(formatFailures(blockingResults([result]))).toBe('');
+ });
+
+ it('runs the DOM layer here and reports the higher layers as unrun', async () => {
+ const results: BindingResult[] = [];
+ for (const state of SWITCH_BINDING_STATES) {
+ results.push(await runState(state));
+ }
+ const report = summarize(SWITCH_PATTERN, results);
+
+ // Something actually ran, or this lane would prove nothing at all.
+ expect(report.counts.pass).toBeGreaterThan(0);
+ // And what it could not see is named, not quietly counted as covered.
+ expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+});
diff --git a/playwright.config.ts b/playwright.config.ts
new file mode 100644
index 0000000000..a83c7675a9
--- /dev/null
+++ b/playwright.config.ts
@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file playwright.config.ts
+ * @input Uses @playwright/test
+ * @output The real-Chromium lane for the accessibility spec-test contracts.
+ * @position Run with `pnpm test:a11y-contract`. Deliberately separate from
+ * `pnpm test`: the Vitest projects must stay runnable from a cold clone with
+ * no browser installed, and the accessibility-tree and real-browser evidence
+ * layers cannot run without one.
+ *
+ * `docs/specs/AST-020/spec.md` puts it plainly: a DOM emulator cannot prove
+ * focus navigation, computed accessibility-tree exposure, or engine state
+ * transitions. Everything matched here is an expectation assigned to a layer
+ * only a shipping engine can observe.
+ *
+ * The component bindings read stories out of a built Storybook, the same
+ * artifact every other Chromium check in this repository uses. Build it first:
+ *
+ * pnpm storybook:build
+ * npx playwright install chromium
+ * pnpm test:a11y-contract
+ *
+ * SYNC: When a package gains an accessibility binding, add its spec glob here.
+ */
+
+import {defineConfig, devices} from '@playwright/test';
+
+// GitHub Actions sets CI=true; some runners set it to an empty string. One
+// definition, so `forbidOnly` and the reporter choice cannot disagree.
+const isCI = (process.env.CI ?? '') !== '';
+
+export default defineConfig({
+ testDir: '.',
+ testMatch: [
+ // The contract's own conforming/violating fixture proof.
+ 'internal/a11y-spec/src/**/*.chromium.spec.ts',
+ // Component bindings.
+ 'packages/*/src/**/*.a11y.chromium.spec.ts',
+ ],
+ // The contract mounts, focuses, and types into one page at a time; parallel
+ // workers would race over real keyboard focus.
+ workers: 1,
+ fullyParallel: false,
+ forbidOnly: isCI,
+ reporter: isCI ? [['list'], ['github']] : [['list']],
+ // One `use` block, on the project. Motion is NOT held here: neither
+ // `use.reducedMotion` nor Chromium's `--force-prefers-reduced-motion` reaches
+ // `matchMedia` in this Playwright version — both were measured returning
+ // false. The specs call `holdMotionStill(page)` instead, which does work.
+ projects: [{name: 'chromium', use: {...devices['Desktop Chrome']}}],
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4bc42e33cb..4a57f45f40 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -471,6 +471,18 @@ importers:
specifier: ^8.1.3
+ internal/a11y-spec:
+ devDependencies:
+ '@playwright/test':
+ specifier: ^1.61.1
+ version: 1.61.1
+ typescript:
+ specifier: ^6.0.3
+ version: 6.0.3
+ vitest:
+ specifier: ^4.1.9
+
internal/eslint-plugin-astryx:
dependencies:
eslint:
@@ -682,6 +694,9 @@ importers:
specifier: '>=19.0.0'
version: 19.2.7([email protected])
devDependencies:
+ '@astryxdesign/a11y-spec':
+ specifier: workspace:*
+ version: link:../../internal/a11y-spec
'@astryxdesign/cli':
specifier: workspace:*
version: link:../cli