Skip to content

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

TypeScript
27.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file toggle-button.ts
 * @input Uses the shared accessibility-contract vocabulary
 * @output TOGGLE_BUTTON_PATTERN and ToggleButtonStateFacts
 * @position The reusable contract for buttons with a persistent pressed state.
 *   Ordinary command buttons remain owned by BUTTON_PATTERN.
 *
 * Adopted pattern: https://www.w3.org/WAI/ARIA/apg/patterns/button/
 *
 * SYNC: When an expectation changes, update
 * - /internal/a11y-spec/README.md
 * - /internal/a11y-spec/src/patterns/toggle-button.fixtures.ts
 * - /packages/core/src/ToggleButton/__tests__/ToggleButton.a11y.states.ts
 */

import {
  definePattern,
  type ApgRequirement,
  type AstryxRecord,
  type PatternContract,
  type WcagCriterion,
} from '../contract';
import type {Subject} from '../harness';
import {saysInOrder, spokenWords} from '../spoken';

const APG_URL = 'https://www.w3.org/WAI/ARIA/apg/patterns/button/';
const UNDERSTANDING = 'https://www.w3.org/WAI/WCAG22/Understanding';
const FAMILY_BUTTONS =
  'https://github.com/meta/astryx/blob/e86aa19ecb7e8204c8b5b430bb61a971b813d137/docs/families/buttons.md';

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_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_2_2: WcagCriterion = {
  standard: 'wcag',
  id: '3.2.2',
  name: 'On Input',
  level: 'A',
  url: `${UNDERSTANDING}/on-input.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 FAMILY_BUTTONS_FR1: AstryxRecord = {
  standard: 'astryx',
  id: 'family:buttons',
  clause: 'FR1',
  requirement:
    'A Button-family control MUST receive a non-empty accessible `label`.',
  url: `${FAMILY_BUTTONS}#L108-L111`,
};
const FAMILY_BUTTONS_FR2: AstryxRecord = {
  standard: 'astryx',
  id: 'family:buttons',
  clause: 'FR2',
  requirement:
    'A momentary or persistent action renders an operable button with keyboard activation, focus-visible feedback, and `type="button"` unless the component\'s documented form mode says otherwise.',
  url: `${FAMILY_BUTTONS}#L112-L116`,
};
const FAMILY_BUTTONS_FR3: AstryxRecord = {
  standard: 'astryx',
  id: 'family:buttons',
  clause: 'FR3',
  requirement: 'A disabled member MUST NOT invoke its callback or Action.',
  url: `${FAMILY_BUTTONS}#L117-L120`,
};
const FAMILY_BUTTONS_FR6: AstryxRecord = {
  standard: 'astryx',
  id: 'family:buttons',
  clause: 'FR6',
  requirement:
    'A ToggleButton MUST expose its effective state with `aria-pressed` and request the next controlled value on activation.',
  url: `${FAMILY_BUTTONS}#L135-L138`,
};

const APG_ROLE: ApgRequirement = {
  standard: 'apg',
  pattern: 'button',
  requirement: 'The button has role of button.',
  url: `${APG_URL}#wai-ariaroles,states,andproperties`,
};
const APG_LABEL: ApgRequirement = {
  standard: 'apg',
  pattern: 'button',
  requirement:
    'The button has an accessible label. By default, the accessible name is computed from any text content inside the button element. However, it can also be provided with aria-labelledby or aria-label.',
  url: `${APG_URL}#wai-ariaroles,states,andproperties`,
};
const APG_DESCRIPTION: ApgRequirement = {
  standard: 'apg',
  pattern: 'button',
  requirement:
    "If a description of the button's function is present, the button element has aria-describedby set to the ID of the element containing the description.",
  url: `${APG_URL}#wai-ariaroles,states,andproperties`,
};
const APG_UNAVAILABLE: ApgRequirement = {
  standard: 'apg',
  pattern: 'button',
  requirement:
    'When the action associated with a button is unavailable, the button has aria-disabled set to true.',
  url: `${APG_URL}#wai-ariaroles,states,andproperties`,
};
const APG_PRESSED: ApgRequirement = {
  standard: 'apg',
  pattern: 'button',
  requirement:
    'If the button is a toggle button, it has an aria-pressed state. When the button is toggled on, the value of this state is true, and when toggled off, the state is false.',
  url: `${APG_URL}#wai-ariaroles,states,andproperties`,
};
const APG_STABLE_LABEL: ApgRequirement = {
  standard: 'apg',
  pattern: 'button',
  requirement: 'The label on a toggle does not change when its state changes.',
  url: `${APG_URL}#aboutthispattern`,
};
const APG_ENTER: ApgRequirement = {
  standard: 'apg',
  pattern: 'button',
  requirement: 'Enter: Activates the button.',
  url: `${APG_URL}#keyboardinteraction`,
};
const APG_SPACE: ApgRequirement = {
  standard: 'apg',
  pattern: 'button',
  requirement: 'Space: Activates the button.',
  url: `${APG_URL}#keyboardinteraction`,
};

export interface ToggleButtonStateFacts {
  readonly pressed: boolean;
  readonly operable: boolean;
  readonly focusable: boolean;
  readonly unavailable: boolean;
  readonly described: boolean;
}

const ALWAYS = {
  condition: 'the binding renders the toggle button',
  test: () => true,
};
const READS_TREE = ['accessibility-tree'] as const;
const TAB_BUDGET = 10;

function pressedWord(value: 'true' | 'false' | 'mixed' | null): string {
  return value === 'true'
    ? 'pressed'
    : value === 'false'
      ? 'not pressed'
      : value === 'mixed'
        ? 'partly pressed'
        : 'without a pressed state';
}

async function roundTrip(
  subject: Subject,
  start: boolean,
  activate: () => Promise<void>,
  how: string,
): Promise<void> {
  const from = start ? 'true' : 'false';
  const to = start ? 'false' : 'true';
  const before = (await subject.computed()).pressed;
  if (before !== from) {
    throw new Error(
      `the binding declares ${pressedWord(from)}, but the browser starts ${pressedWord(before)}`,
    );
  }
  await activate();
  const after = (await subject.computed()).pressed;
  if (after !== to) {
    throw new Error(
      `${how} left the toggle button ${pressedWord(after)}: it did not become ${pressedWord(to)}`,
    );
  }
  await activate();
  const back = (await subject.computed()).pressed;
  if (back !== from) {
    throw new Error(
      `${how} changed the toggle button to ${pressedWord(after)}, but doing it again left it ${pressedWord(back)} instead of returning it to ${pressedWord(from)}`,
    );
  }
}

export const TOGGLE_BUTTON_PATTERN: PatternContract<ToggleButtonStateFacts> =
  definePattern<ToggleButtonStateFacts>({
    pattern: 'toggle-button',
    url: APG_URL,
    scope:
      'One persistent action control that is reported as a button, exposes its pressed state, keeps one name, and changes in both directions through pointer, Enter, and Space.',
    expectations: [
      {
        id: 'toggle-button.role.exposed',
        outcome:
          'The control is exposed as a button, so the user understands that it performs an action.',
        sources: [WCAG_4_1_2, FAMILY_BUTTONS_FR2, 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 !== 'button') {
            throw new Error(
              role == null
                ? 'the browser exposes no role for this toggle button'
                : `the browser reports this control as "${role}", not as a button`,
            );
          }
        },
      },
      {
        id: 'toggle-button.name.exposed',
        outcome:
          'The toggle button has an accessible name, so the user knows which persistent action it controls.',
        sources: [FAMILY_BUTTONS_FR1, WCAG_4_1_2, APG_LABEL],
        covers: ['4.1.2-name-role-value'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'accessibility-tree',
        enforcement: 'required',
        run: async ({subject}) => {
          if ((await subject.computed()).name.trim() === '') {
            throw new Error(
              'the browser computes no accessible name for this toggle button',
            );
          }
        },
      },
      {
        id: 'toggle-button.name.matches-visible-label',
        outcome:
          'The accessible name contains the visible label, so a speech-input user can say what they can read.',
        sources: [WCAG_2_5_3, APG_LABEL],
        covers: ['2.5.3-label-in-name'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'accessibility-tree',
        alsoNeeds: ['real-browser'],
        enforcement: 'required',
        run: async ({subject, notApplicable}) => {
          const visible = await subject.visibleLabelText();
          if (visible == null) {
            return notApplicable(
              'this state renders no visible words, so WCAG 2.5.3 has no visible label to compare',
            );
          }
          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}"`,
            );
          }
        },
      },
      {
        id: 'toggle-button.state.exposed',
        outcome:
          'The pressed state is exposed and matches the rendered state, so assistive technology reports the same persistent choice the user sees.',
        sources: [FAMILY_BUTTONS_FR6, WCAG_4_1_2, APG_PRESSED],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'accessibility-tree',
        enforcement: 'required',
        run: async ({subject, facts}) => {
          const {pressed} = await subject.computed();
          const expected = facts.pressed ? 'true' : 'false';
          if (pressed == null) {
            throw new Error(
              'the browser exposes no pressed state for this toggle button',
            );
          }
          if (pressed !== expected) {
            throw new Error(
              `this state is ${pressedWord(expected)} but the browser reports it as ${pressedWord(pressed)}`,
            );
          }
        },
      },
      {
        id: 'toggle-button.description.resolvable',
        outcome:
          'Every description target exists, so supporting text is not silently dropped.',
        sources: [WCAG_1_3_1, APG_DESCRIPTION],
        covers: ['1.3.1-info-and-relationships'],
        appliesWhen: {
          condition: 'the binding renders supporting text',
          test: facts => facts.described,
        },
        evidenceLayer: 'dom',
        enforcement: 'required',
        run: async ({subject}) => {
          const ids = ((await subject.attribute('aria-describedby')) ?? '')
            .split(/\s+/)
            .filter(Boolean);
          if (ids.length === 0) {
            throw new Error(
              'the binding renders supporting text, but the toggle button has no aria-describedby',
            );
          }
          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 resolves to nothing`,
            );
          }
        },
      },
      {
        id: 'toggle-button.description.exposed',
        outcome: 'Supporting text is exposed as the toggle button description.',
        sources: [WCAG_4_1_2, APG_DESCRIPTION],
        covers: ['4.1.2-name-role-value'],
        appliesWhen: {
          condition: 'the binding renders supporting text',
          test: facts => facts.described,
        },
        evidenceLayer: 'accessibility-tree',
        enforcement: 'required',
        run: async ({subject}) => {
          if ((await subject.computed()).description.trim() === '') {
            throw new Error(
              'the binding renders supporting text, but the browser computes no accessible description',
            );
          }
        },
      },
      {
        id: 'toggle-button.unavailable.exposed',
        outcome: 'An unavailable toggle button is reported as unavailable.',
        sources: [WCAG_4_1_2, APG_UNAVAILABLE],
        covers: ['4.1.2-name-role-value'],
        appliesWhen: {
          condition: 'the binding declares this state unavailable',
          test: facts => facts.unavailable,
        },
        evidenceLayer: 'accessibility-tree',
        enforcement: 'required',
        run: async ({subject}) => {
          if (!(await subject.computed()).disabled) {
            throw new Error(
              'this state is unavailable, but the browser reports the toggle button as available',
            );
          }
        },
      },
      {
        id: 'toggle-button.state.pointer-round-trip',
        outcome:
          'A pointer changes the pressed state and changes it back, with the exposed state following both transitions.',
        sources: [FAMILY_BUTTONS_FR6, APG_PRESSED, WCAG_4_1_2],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: {
          condition: 'the user can change this state',
          test: facts => facts.operable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: READS_TREE,
        enforcement: 'required',
        run: async ({harness, subject, facts}) =>
          roundTrip(
            subject,
            facts.pressed,
            () => harness.click(subject),
            'clicking the toggle button',
          ),
      },
      {
        id: 'toggle-button.state.enter-round-trip',
        outcome: 'Enter changes the pressed state and changes it back.',
        sources: [WCAG_2_1_1, FAMILY_BUTTONS_FR2, APG_ENTER],
        covers: ['2.1.1-keyboard', 'apg-interaction'],
        appliesWhen: {
          condition: 'the state is operable and focusable',
          test: facts => facts.operable && facts.focusable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: READS_TREE,
        enforcement: 'required',
        run: async ({harness, subject, facts}) => {
          await subject.focus();
          if (!(await subject.isFocused())) {
            throw new Error(
              'the toggle button did not take focus, so Enter never reaches it',
            );
          }
          await roundTrip(
            subject,
            facts.pressed,
            () => harness.press('Enter'),
            'pressing Enter on the focused toggle button',
          );
        },
      },
      {
        id: 'toggle-button.state.space-round-trip',
        outcome: 'Space changes the pressed state and changes it back.',
        sources: [WCAG_2_1_1, FAMILY_BUTTONS_FR2, APG_SPACE],
        covers: ['2.1.1-keyboard', 'apg-interaction'],
        appliesWhen: {
          condition: 'the state is operable and focusable',
          test: facts => facts.operable && facts.focusable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: READS_TREE,
        enforcement: 'required',
        run: async ({harness, subject, facts}) => {
          await subject.focus();
          if (!(await subject.isFocused())) {
            throw new Error(
              'the toggle button did not take focus, so Space never reaches it',
            );
          }
          await roundTrip(
            subject,
            facts.pressed,
            () => harness.press('Space'),
            'pressing Space on the focused toggle button',
          );
        },
      },
      {
        id: 'toggle-button.name.stable-across-change',
        outcome:
          'The name stays the same after both state changes, so it identifies the action rather than contradicting the pressed state.',
        sources: [APG_STABLE_LABEL, WCAG_4_1_2],
        wcagOutcome:
          'The accessible name in 4.1.2 continues to identify the same control while its separately exposed state changes.',
        covers: ['apg-interaction'],
        appliesWhen: {
          condition: 'the user can change this state',
          test: facts => facts.operable,
        },
        evidenceLayer: 'accessibility-tree',
        alsoNeeds: ['real-browser'],
        enforcement: 'advisory',
        advisoryBecause:
          'The label-stability detail is APG guidance that no current Astryx record adopts as a required shared outcome.',
        run: async ({harness, subject}) => {
          const before = (await subject.computed()).name;
          await harness.click(subject);
          const changed = (await subject.computed()).name;
          if (changed.trim().toLowerCase() !== before.trim().toLowerCase()) {
            throw new Error(
              `changing the pressed state renamed the toggle button from "${before}" to "${changed}"`,
            );
          }
          await harness.click(subject);
          const back = (await subject.computed()).name;
          if (back.trim().toLowerCase() !== before.trim().toLowerCase()) {
            throw new Error(
              `changing the pressed state back renamed the toggle button from "${before}" to "${back}"`,
            );
          }
        },
      },
      {
        id: 'toggle-button.state.survives-an-aborted-press',
        outcome:
          'A press released away from the control leaves the pressed state unchanged.',
        sources: [WCAG_2_5_2],
        covers: ['2.5.2-pointer-cancellation'],
        appliesWhen: {
          condition: 'the user can change this state',
          test: facts => facts.operable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: READS_TREE,
        enforcement: 'required',
        run: async ({harness, subject}) => {
          const before = (await subject.computed()).pressed;
          await harness.abortedPress(subject);
          const after = (await subject.computed()).pressed;
          if (after !== before) {
            throw new Error(
              `pressing and releasing away still changed the toggle button to ${pressedWord(after)}`,
            );
          }
        },
      },
      {
        id: 'toggle-button.focus.stays-on-change',
        outcome:
          'Changing the pressed state leaves focus on the toggle button.',
        sources: [WCAG_3_2_2],
        // Partly: see the 3.2.2 exemption for context changes caused by the
        // caller rather than by the ToggleButton itself.
        covers: ['3.2.2-on-input'],
        appliesWhen: {
          condition: 'the state is operable and focusable',
          test: facts => facts.operable && facts.focusable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: READS_TREE,
        enforcement: 'required',
        run: async ({harness, subject}) => {
          await subject.focus();
          if (!(await subject.isFocused())) {
            throw new Error(
              'the toggle button did not take focus, so its state cannot be changed from the keyboard',
            );
          }
          const before = (await subject.computed()).pressed;
          await harness.press('Space');
          if ((await subject.computed()).pressed === before) {
            throw new Error(
              'pressing Space did not change the pressed state, so there is no change whose focus outcome can be checked',
            );
          }
          if (!(await subject.isFocused())) {
            throw new Error(
              'changing the pressed state moved focus off the toggle button',
            );
          }
        },
      },
      {
        id: 'toggle-button.focus.reachable-and-escapable',
        outcome: 'Tab reaches the toggle button and then leaves it.',
        sources: [WCAG_2_1_1, WCAG_2_1_2],
        covers: ['2.1.1-keyboard', '2.1.2-no-keyboard-trap'],
        appliesWhen: {
          condition: 'the state belongs in the tab sequence',
          test: facts => facts.focusable,
        },
        evidenceLayer: 'real-browser',
        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 never reached the toggle button`,
            );
          }
          await harness.press('Tab');
          if (await subject.isFocused()) {
            throw new Error('Tab did not move focus off the toggle button');
          }
        },
      },
      {
        id: 'toggle-button.state.inoperable',
        outcome:
          'A toggle button that cannot be operated keeps its pressed state under pointer, Enter, and Space.',
        sources: [FAMILY_BUTTONS_FR3, FAMILY_BUTTONS_FR6, WCAG_4_1_2],
        covers: ['4.1.2-name-role-value'],
        appliesWhen: {
          condition: 'the user cannot change this state',
          test: facts => !facts.operable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: READS_TREE,
        enforcement: 'required',
        run: async ({harness, subject, facts}) => {
          const before = (await subject.computed()).pressed;
          await harness.click(subject, {ignoreAvailability: true});
          if ((await subject.computed()).pressed !== before) {
            throw new Error(
              'clicking an inoperable toggle button changed its pressed state',
            );
          }
          if (!facts.focusable) {
            return;
          }
          await subject.focus();
          if (!(await subject.isFocused())) {
            throw new Error(
              'this state is declared focusable but cannot take focus',
            );
          }
          for (const key of ['Enter', 'Space'] as const) {
            await harness.press(key);
            if ((await subject.computed()).pressed !== before) {
              throw new Error(
                `pressing ${key} changed an inoperable toggle button`,
              );
            }
          }
        },
      },
    ],
    exemptions: {
      '1.1.1-non-text-content': {
        owner: 'the binding component',
        verifiedBy: 'component icon tests and the repository axe audit',
        reason:
          'Decorative or informative graphics inside the control are component composition, not pressed-button semantics.',
      },
      '1.3.2-meaningful-sequence': {
        owner: 'the composing page',
        verifiedBy: 'page-level DOM-order review',
        reason:
          'A single control cannot determine its order among surrounding content.',
      },
      '1.3.5-identify-input-purpose': {
        owner: 'the composing form',
        verifiedBy: 'form integration review',
        reason:
          'A toggle button performs an action and does not collect user information.',
      },
      '1.4.1-use-of-color': {
        owner: 'the binding component and theme',
        verifiedBy: 'forced-colors tests and the visual gate',
        reason:
          'Whether pressed state is conveyed without color alone is a rendered-pixel claim.',
      },
      '1.4.3-contrast-minimum': {
        owner: 'the binding component and theme',
        verifiedBy: 'axe and visual gates',
        reason: 'Resolved text contrast is a rendered-pixel measurement.',
      },
      '1.4.11-non-text-contrast': {
        owner: 'the binding component and theme',
        verifiedBy: 'axe, forced-colors, and visual gates',
        reason:
          'Control, state, icon, and focus-indicator contrast are rendered-pixel measurements.',
      },
      '2.4.2-page-titled': {
        owner: 'the page',
        verifiedBy: 'page-level review',
        reason: 'A component does not own the document title.',
      },
      '2.4.3-focus-order': {
        owner: 'the composing page',
        verifiedBy: 'page-level focus-order review',
        reason:
          'This contract proves reachability and escape, not the meaning of the surrounding sequence.',
      },
      '2.4.4-link-purpose': {
        owner: 'the link pattern and caller content',
        verifiedBy: 'link-pattern and page review',
        reason:
          'ToggleButton remains an action and never adopts link semantics.',
      },
      '2.4.6-headings-and-labels': {
        owner: 'caller content',
        verifiedBy:
          'content review of whether the supplied label describes the action',
        reason:
          'The contract proves that a name exists, not that the chosen wording is descriptive.',
      },
      '2.4.7-focus-visible': {
        owner: 'interaction-modality and the binding component',
        verifiedBy: 'the repository visual gate',
        reason: 'A visible focus indicator is a paint result.',
      },
      '2.4.11-focus-not-obscured': {
        owner: 'the composing page',
        verifiedBy: 'page and overlay review',
        reason: 'Obscuration depends on surrounding authored content.',
      },
      '2.5.8-target-size': {
        owner: 'the binding component and composing page',
        verifiedBy: 'the repository axe target-size rule and visual review',
        reason:
          'Target-size exceptions depend on rendered geometry and neighbouring targets.',
      },
      '3.1.1-language-of-page': {
        owner: 'the page',
        verifiedBy: 'page-level review',
        reason: 'A component does not own the document language.',
      },
      '3.2.2-on-input': {
        owner: 'the caller, for its response to onPressedChange',
        verifiedBy:
          'integration and page-level review of any navigation, reload, or surrounding content change triggered by the caller',
        reason:
          'This contract proves that changing pressed state keeps focus on the ToggleButton. It cannot observe whether caller code changes the wider page context in response to onPressedChange.',
        coversRemainderOnly: true,
      },
      '3.2.4-consistent-identification': {
        owner: 'the design system and caller content',
        verifiedBy: 'shared pattern adoption and page-level content review',
        reason:
          'Consistency is a property of repeated controls across a product.',
      },
      '3.3.1-error-identification': {
        owner: 'the composing workflow',
        verifiedBy: 'workflow validation and status-message tests',
        reason:
          'A toggle button exposes pressed state, not a validation error contract.',
      },
      '3.3.2-labels-or-instructions': {
        owner: 'caller content',
        verifiedBy: 'content review',
        reason:
          'Instructions for a workflow are not owned by one toggle button.',
      },
      '4.1.3-status-messages': {
        owner: 'the binding component and caller',
        verifiedBy:
          'status-message tests and AST-009 when announcement is claimed',
        reason:
          'A pressed state is exposed on the control; separate status announcements are composed around it.',
      },
      'forced-colors': {
        owner: 'the binding component and theme',
        verifiedBy:
          'ToggleButton forced-colors tests and manual Windows High Contrast review',
        reason: 'Forced-colors output is a paint result.',
      },
      'reduced-motion': {
        owner: 'the binding component and theme',
        verifiedBy: 'motion guards and the visual gate',
        reason: 'Motion is a rendered result over time.',
      },
      'at-facing-strings': {
        owner: 'the binding component and caller content',
        verifiedBy:
          'localization review and AST-009 when announcement is claimed',
        reason:
          'The contract compares names and labels but does not own translation or spoken output.',
      },
    },
  });