Skip to content

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

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

/**
 * @file menu-button.ts
 * @input WCAG 2.2 A/AA success criteria and the APG Menu Button pattern's role, state, relationship, and keyboard requirements
 * @output MENU_BUTTON_PATTERN — the reusable contract a control that opens an anchored menu binds to when it adopts Menu Button's required parts, plus the ArrowDown/ArrowUp opening Astryx ships as a named exception
 * @position Pattern contract; bound by the DropdownMenu and MoreMenu anchored triggers under their records' AR4/AR1 (`spec:AST-020/FR15`)
 */

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

const APG_URL = 'https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/';
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_5_2: WcagCriterion = {
  standard: 'wcag',
  id: '2.5.2',
  name: 'Pointer Cancellation',
  level: 'A',
  url: `${UNDERSTANDING}/pointer-cancellation.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: 'menu-button',
  requirement: 'The element that opens the menu has role button.',
  url: `${APG_URL}#wai-ariaroles,states,andproperties`,
};
const APG_HASPOPUP: ApgRequirement = {
  standard: 'apg',
  pattern: 'menu-button',
  requirement:
    'The element with role button has aria-haspopup set to either menu or true.',
  url: `${APG_URL}#wai-ariaroles,states,andproperties`,
};
const APG_EXPANDED: ApgRequirement = {
  standard: 'apg',
  pattern: 'menu-button',
  requirement:
    'When the menu is displayed, the element with role button has aria-expanded set to true. When the menu is hidden, aria-expanded is set to false.',
  url: `${APG_URL}#wai-ariaroles,states,andproperties`,
};
const APG_CONTROLS: ApgRequirement = {
  standard: 'apg',
  pattern: 'menu-button',
  requirement:
    'Optionally, the element with role button has a value specified for aria-controls that refers to the element with role menu.',
  url: `${APG_URL}#wai-ariaroles,states,andproperties`,
};
const APG_ENTER: ApgRequirement = {
  standard: 'apg',
  pattern: 'menu-button',
  requirement: 'Enter: opens the menu and places focus on the first menu item.',
  url: `${APG_URL}#keyboardinteraction`,
};
const APG_SPACE: ApgRequirement = {
  standard: 'apg',
  pattern: 'menu-button',
  requirement: 'Space: Opens the menu and places focus on the first menu item.',
  url: `${APG_URL}#keyboardinteraction`,
};
const APG_DOWN: ApgRequirement = {
  standard: 'apg',
  pattern: 'menu-button',
  requirement:
    '(Optional) Down Arrow: opens the menu and moves focus to the first menu item.',
  url: `${APG_URL}#keyboardinteraction`,
};
const APG_UP: ApgRequirement = {
  standard: 'apg',
  pattern: 'menu-button',
  requirement:
    '(Optional) Up Arrow: opens the menu and moves focus to the last menu item.',
  url: `${APG_URL}#keyboardinteraction`,
};

/**
 * The current Astryx adoption of the pattern's required parts: a control that
 * already plays the menu button role takes its role, name, state and
 * relationship properties, and Enter/Space activation.
 */
const AST_020_FR15: AstryxRecord = {
  standard: 'astryx',
  id: 'spec:AST-020',
  clause: 'FR15',
  url: 'https://github.com/meta/astryx/blob/878fad9d7ac23cd3f4c5def64595abd770bb01a3/docs/specs/AST-020/spec.md#L83-L92',
  requirement:
    "Where a component part already plays an APG pattern's role, Astryx adopts that pattern's required parts for it: the role, the accessible name, the state and relationship properties, and activation by Tab plus Enter or Space.",
};

/**
 * What a binding knows about one menu button. The subject is the control that
 * opens the menu; `menu` is the element with role menu it controls, and
 * `first-item` and `last-item` are that menu's first and last enabled items.
 */
export interface MenuButtonStateFacts {
  /** Whether the menu is meant to be displayed in this state. */
  readonly open: boolean;
  /** Whether the user is meant to be able to open the menu. */
  readonly operable: boolean;
  /** Whether the control is meant to accept keyboard focus. */
  readonly focusable: boolean;
  /** Whether the binding declares the optional aria-controls relationship. */
  readonly controls: boolean;
  /**
   * Whether the binding opens on ArrowDown (first item) and ArrowUp (last
   * item), the APG-optional keys Astryx ships for anchored menus.
   */
  readonly arrowKeysOpen: boolean;
}

const ALWAYS = {
  condition: 'the binding designates a control that opens a menu',
  test: () => true,
};

async function authoredExpanded(subject: Subject): Promise<boolean | null> {
  const value = await subject.attribute('aria-expanded');
  return value === 'true' ? true : value === 'false' ? false : null;
}

async function assertOpen(
  subject: Subject,
  menu: Subject,
  expected: boolean,
  after: string,
): Promise<void> {
  const state = await authoredExpanded(subject);
  if (state !== expected) {
    throw new Error(
      `${after} left aria-expanded ${state == null ? 'absent or invalid' : state} instead of ${expected}`,
    );
  }
  const visible = await menu.isVisible();
  if (visible !== expected) {
    throw new Error(
      `${after} left the control ${expected ? 'expanded' : 'collapsed'} while the menu was ${visible ? 'visible' : 'hidden'}`,
    );
  }
}

async function focusOrFail(subject: Subject, forWhat: string): Promise<void> {
  await subject.focus();
  if (!(await subject.isFocused())) {
    throw new Error(
      `the menu button did not take focus, so ${forWhat} never reaches it`,
    );
  }
}

/**
 * Opens the menu with one key from the focused control, checks where focus
 * landed, then presses the control again so the next expectation starts from
 * the state the binding declared (the pointer round trip proves that press
 * closes the menu). A binding whose menu does not close that way fails here
 * with that reason rather than leaking an open menu into the next check.
 */
async function openWithKey(
  harness: Harness,
  subject: Subject,
  key: 'Enter' | 'Space' | 'ArrowDown' | 'ArrowUp',
  landing: 'first-item' | 'last-item',
): Promise<void> {
  const menu = await harness.related('menu');
  const target = await harness.related(landing);
  await assertOpen(subject, menu, false, 'the starting state');
  await focusOrFail(subject, key);
  await harness.press(key);
  await assertOpen(
    subject,
    menu,
    true,
    `pressing ${key} on the focused control`,
  );
  if (!(await target.isFocused())) {
    throw new Error(
      `pressing ${key} opened the menu without moving focus to its ${landing === 'first-item' ? 'first' : 'last'} enabled item`,
    );
  }
  await harness.click(subject);
  if ((await authoredExpanded(subject)) !== false) {
    throw new Error(
      'pressing the control again did not close the menu, so it cannot be returned to its starting state',
    );
  }
}

export const MENU_BUTTON_PATTERN: PatternContract<MenuButtonStateFacts> =
  definePattern<MenuButtonStateFacts>({
    pattern: 'menu-button',
    url: APG_URL,
    scope:
      "A menu button's role and name, aria-haspopup, expanded state, optional aria-controls to its menu, Enter and Space opening with focus on the first item, and — where a binding ships them — ArrowDown and ArrowUp opening on the first and last items.",
    expectations: [
      {
        id: 'menu-button.control.role-and-name',
        outcome:
          'The browser exposes the control as a named button, so a user hears what the menu is for before opening it.',
        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, name} = await subject.computed();
          if (role !== 'button') {
            throw new Error(
              `the browser exposes this control as ${role == null ? 'no role' : `"${role}"`}, not as a button`,
            );
          }
          if (!name || name.trim() === '') {
            throw new Error(
              'the browser computes no accessible name for this control',
            );
          }
        },
      },
      {
        id: 'menu-button.control.haspopup-menu',
        outcome:
          'The control says it opens a menu, so a user knows a press reveals choices rather than acting at once.',
        sources: [WCAG_4_1_2, APG_HASPOPUP, AST_020_FR15],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'dom',
        enforcement: 'required',
        run: async ({subject}) => {
          const value = await subject.attribute('aria-haspopup');
          if (value !== 'menu' && value !== 'true') {
            throw new Error(
              `aria-haspopup is ${value ?? 'absent'}; a menu button says "menu" or "true"`,
            );
          }
        },
      },
      {
        id: 'menu-button.control.expanded-state',
        outcome:
          'The control reports whether its menu is displayed, in both states.',
        sources: [WCAG_4_1_2, APG_EXPANDED, AST_020_FR15],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'dom',
        enforcement: 'required',
        run: async ({subject, facts}) => {
          const expanded = await subject.attribute('aria-expanded');
          if (expanded !== String(facts.open)) {
            throw new Error(
              `the menu is ${facts.open ? 'displayed' : 'hidden'} but aria-expanded is ${expanded ?? 'absent'}`,
            );
          }
        },
      },
      {
        id: 'menu-button.control.controls-menu',
        outcome:
          'The declared control relationship identifies the menu element.',
        sources: [WCAG_1_3_1, APG_CONTROLS, AST_020_FR15],
        covers: ['1.3.1-info-and-relationships', 'apg-interaction'],
        appliesWhen: {
          condition:
            'the binding declares the optional aria-controls relationship',
          test: facts => facts.controls,
        },
        evidenceLayer: 'dom',
        enforcement: 'required',
        run: async ({harness, subject}) => {
          const menu = await harness.related('menu');
          if (!(await harness.references(subject, 'aria-controls', menu))) {
            throw new Error('aria-controls does not identify the menu');
          }
          if ((await menu.attribute('role')) !== 'menu') {
            throw new Error('the controlled element does not have role menu');
          }
        },
      },
      {
        id: 'menu-button.menu.matches-state',
        outcome:
          'A displayed menu is visible and a hidden menu is not, so the exposed state describes what the user receives.',
        sources: [WCAG_4_1_2, APG_EXPANDED],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'required',
        run: async ({harness, subject, facts}) => {
          await assertOpen(
            subject,
            await harness.related('menu'),
            facts.open,
            'the rendered state',
          );
        },
      },
      {
        id: 'menu-button.open.enter-focuses-first-item',
        outcome:
          'With focus on the control, Enter opens the menu and places focus on its first enabled item.',
        sources: [WCAG_2_1_1, APG_ENTER, AST_020_FR15],
        covers: ['2.1.1-keyboard', '2.4.3-focus-order', 'apg-interaction'],
        appliesWhen: {
          condition:
            'the menu starts hidden and the control can be operated and focused',
          test: facts => !facts.open && facts.operable && facts.focusable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'required',
        run: async ({harness, subject}) => {
          await openWithKey(harness, subject, 'Enter', 'first-item');
        },
      },
      {
        id: 'menu-button.open.space-focuses-first-item',
        outcome:
          'With focus on the control, Space opens the menu and places focus on its first enabled item.',
        sources: [WCAG_2_1_1, APG_SPACE, AST_020_FR15],
        covers: ['2.1.1-keyboard', '2.4.3-focus-order', 'apg-interaction'],
        appliesWhen: {
          condition:
            'the menu starts hidden and the control can be operated and focused',
          test: facts => !facts.open && facts.operable && facts.focusable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'required',
        run: async ({harness, subject}) => {
          await openWithKey(harness, subject, 'Space', 'first-item');
        },
      },
      {
        id: 'menu-button.open.arrow-down-focuses-first-item',
        outcome:
          'With focus on the control, ArrowDown opens the menu and places focus on its first enabled item.',
        sources: [APG_DOWN],
        wcagOutcome:
          'Supports WCAG 2.2 2.1.1 by keeping the implemented arrow-key open keyboard-operable; the APG recommends it, so this row is advisory until the binding record adopts it as current.',
        covers: ['2.4.3-focus-order', 'apg-interaction'],
        appliesWhen: {
          condition:
            'the binding ships arrow-key opening, the menu starts hidden, and the control can be operated and focused',
          test: facts =>
            facts.arrowKeysOpen &&
            !facts.open &&
            facts.operable &&
            facts.focusable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'advisory',
        advisoryBecause:
          "ArrowDown and ArrowUp opening are optional in the APG pattern; this becomes required once the binding's component record adopts them as current (AST-020 FR9).",
        run: async ({harness, subject}) => {
          await openWithKey(harness, subject, 'ArrowDown', 'first-item');
        },
      },
      {
        id: 'menu-button.open.arrow-up-focuses-last-item',
        outcome:
          'With focus on the control, ArrowUp opens the menu and places focus on its last enabled item.',
        sources: [APG_UP],
        wcagOutcome:
          'Supports WCAG 2.2 2.1.1 by keeping the implemented arrow-key open keyboard-operable; the APG recommends it, so this row is advisory until the binding record adopts it as current.',
        covers: ['2.4.3-focus-order', 'apg-interaction'],
        appliesWhen: {
          condition:
            'the binding ships arrow-key opening, the menu starts hidden, and the control can be operated and focused',
          test: facts =>
            facts.arrowKeysOpen &&
            !facts.open &&
            facts.operable &&
            facts.focusable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'advisory',
        advisoryBecause:
          "ArrowDown and ArrowUp opening are optional in the APG pattern; this becomes required once the binding's component record adopts them as current (AST-020 FR9).",
        run: async ({harness, subject}) => {
          await openWithKey(harness, subject, 'ArrowUp', 'last-item');
        },
      },
      {
        id: 'menu-button.open.pointer-round-trip',
        outcome:
          'A pointer press opens the menu and a second press closes it, with the exposed state following both.',
        sources: [WCAG_4_1_2, APG_EXPANDED],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: {
          condition: 'the menu starts hidden and the control can be operated',
          test: facts => !facts.open && facts.operable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'required',
        run: async ({harness, subject}) => {
          const menu = await harness.related('menu');
          await assertOpen(subject, menu, false, 'the starting state');
          await harness.click(subject);
          await assertOpen(subject, menu, true, 'clicking the control');
          await harness.click(subject);
          await assertOpen(subject, menu, false, 'clicking the control again');
        },
      },
      {
        id: 'menu-button.control.unavailable-stays-closed',
        outcome:
          'An unavailable control that still takes focus keeps its menu closed on every opening key and on a press, so a disabled trigger never surprises the user with choices it says it cannot offer.',
        sources: [WCAG_4_1_2, APG_EXPANDED],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: {
          condition:
            'the control cannot be operated but can receive focus, and the menu starts hidden',
          test: facts => !facts.operable && facts.focusable && !facts.open,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'required',
        run: async ({harness, subject}) => {
          const menu = await harness.related('menu');
          await assertOpen(subject, menu, false, 'the starting state');
          await focusOrFail(subject, 'the opening keys');
          for (const key of [
            'Enter',
            'Space',
            'ArrowDown',
            'ArrowUp',
          ] as const) {
            await harness.press(key);
            if ((await authoredExpanded(subject)) !== false) {
              throw new Error(
                `an unavailable control opened its menu on ${key}`,
              );
            }
          }
          await harness.click(subject, {ignoreAvailability: true});
          if ((await authoredExpanded(subject)) !== false) {
            throw new Error(
              'an unavailable control opened its menu on a press',
            );
          }
        },
      },
      {
        id: 'menu-button.control.survives-an-aborted-press',
        outcome:
          'A press released away from the control leaves the menu hidden, so an unintended press can be cancelled.',
        sources: [WCAG_2_5_2],
        covers: ['2.5.2-pointer-cancellation'],
        appliesWhen: {
          condition: 'the menu starts hidden and the control can be operated',
          test: facts => !facts.open && facts.operable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'required',
        run: async ({harness, subject}) => {
          const menu = await harness.related('menu');
          await assertOpen(subject, menu, false, 'the starting state');
          await harness.abortedPress(subject);
          await assertOpen(
            subject,
            menu,
            false,
            'releasing the press away from the control',
          );
        },
      },
    ],
    exemptions: {
      '1.1.1-non-text-content': {
        owner: 'the binding component',
        verifiedBy:
          "the component's decorative-icon tests and the repository axe audit, `pnpm a11y:audit`",
        reason:
          'The menu button contract owns trigger state and controlled-content behavior. Decorative graphics such as a chevron are binding-specific composition.',
      },
      '1.3.1-info-and-relationships': {
        owner: 'the binding component and composing page',
        verifiedBy:
          "the binding's component tests and page-level relationship review",
        reason:
          'This contract encodes the optional trigger-to-content relationship. Other structure and relationships inside or around that content belong to the binding and its composition.',
        coversRemainderOnly: true,
      },
      '1.3.2-meaningful-sequence': {
        owner: 'the binding component and composing page',
        verifiedBy:
          "the component's DOM-order tests and page-level reading-order review",
        reason:
          'The page decides where the trigger and revealed section sit relative to surrounding content.',
      },
      '1.3.5-identify-input-purpose': {
        owner: 'the composing form and caller content',
        verifiedBy:
          'form integration review for any user-information input inside the disclosed content',
        reason:
          'A menu button trigger does not itself collect information about the user.',
      },
      '1.4.1-use-of-color': {
        owner: 'the binding component and theme',
        verifiedBy: 'the repository visual gate and forced-colors review',
        reason:
          'Color and any non-color menu button cue are rendered presentation facts, not trigger-state semantics.',
      },
      '1.4.3-contrast-minimum': {
        owner: 'the binding component and theme',
        verifiedBy:
          'the repository axe audit over component stories plus the visual gate',
        reason:
          'Text contrast depends on resolved colors and backdrop in the rendered binding.',
      },
      '1.4.11-non-text-contrast': {
        owner: 'the binding component and theme',
        verifiedBy:
          'the repository axe audit plus rendered review of the trigger boundary, state cue, and focus indicator',
        reason:
          'Control and menu button-cue contrast are paint outcomes owned by the binding and theme.',
      },
      '2.1.1-keyboard': {
        owner: 'the button pattern and composing page',
        verifiedBy:
          'BUTTON_PATTERN focus-navigation expectations plus page-level keyboard-order review',
        reason:
          'This contract encodes the Enter, Space, ArrowDown, and ArrowUp opening transitions. Generic reachability and other page keyboard paths remain with the button and composition owners.',
        coversRemainderOnly: true,
      },
      '2.1.2-no-keyboard-trap': {
        owner: 'the button pattern and composing page',
        verifiedBy:
          'BUTTON_PATTERN for adopters, plus binding-local focus reach/escape tests and page-level keyboard review',
        reason:
          'A menu button adds no focus trap; Tab entry and exit are generic button and composition behavior.',
      },
      '2.4.2-page-titled': {
        owner: 'the page',
        verifiedBy: 'page-level review',
        reason: 'A menu button rendered in isolation owns no document title.',
      },
      '2.4.3-focus-order': {
        owner: 'the menu pattern and the composing page',
        verifiedBy:
          "the menu contract's focus-return evidence and page-level focus-order review; this contract proves only where focus lands on open",
        reason:
          "Where focus goes after the menu closes, and the control's place among surrounding controls, belong to the menu contract and the composition.",
        coversRemainderOnly: true,
      },
      '2.4.4-link-purpose': {
        owner: 'the link pattern and caller content',
        verifiedBy: 'review of links inside or around the disclosed content',
        reason: 'The adopted menu button trigger is a button, not a link.',
      },
      '2.4.6-headings-and-labels': {
        owner: 'the button pattern and caller content',
        verifiedBy:
          'BUTTON_PATTERN naming checks plus content review of the trigger label',
        reason:
          'Whether the trigger label describes its purpose is a caller-content judgement; generic button naming is already owned by BUTTON_PATTERN.',
      },
      '2.4.7-focus-visible': {
        owner:
          'the interaction-modality architecture record, binding component, and theme',
        verifiedBy:
          "the component's focus-ring styling and the repository visual gate",
        reason: 'A focus indicator is a paint outcome.',
      },
      '2.4.11-focus-not-obscured': {
        owner: 'the composing page and overlay system',
        verifiedBy: 'page-level and overlay visibility review',
        reason:
          'Whether another surface covers the focused trigger or revealed content depends on composition.',
      },
      '2.5.3-label-in-name': {
        owner: 'the button pattern and caller content',
        verifiedBy:
          'BUTTON_PATTERN for adopters, plus binding-local visible-label and accessible-name checks',
        reason:
          'The menu button adds state to a button without changing who owns the button label and name.',
      },
      '2.5.8-target-size': {
        owner: 'the binding component and composing page',
        verifiedBy:
          "the repository axe audit's target-size rule over the trigger and neighbouring targets",
        reason:
          'Target size and spacing exceptions depend on the binding geometry and neighbouring controls.',
      },
      '3.1.1-language-of-page': {
        owner: 'the page',
        verifiedBy: 'page-level language review',
        reason:
          'A menu button rendered in isolation owns no document language.',
      },
      '3.2.2-on-input': {
        owner: 'the menu pattern and the composing page',
        verifiedBy:
          "the menu contract's focus-return evidence and integration review of any navigation a chosen item causes",
        reason:
          "Opening a menu from its button moves focus into the menu by the pattern's own design, and the menu contract owns focus return on close; what a chosen item then does is caller behavior.",
      },
      '3.2.4-consistent-identification': {
        owner: 'the design system and caller content',
        verifiedBy:
          'this shared contract across bindings plus content review of repeated menu button labels',
        reason:
          'Consistency is a property of the full set of repeated functions, not one isolated menu button.',
      },
      '3.3.1-error-identification': {
        owner: 'the binding component and composing form',
        verifiedBy: 'form-level error-state and text review',
        reason: 'The menu button pattern defines no validation error state.',
      },
      '3.3.2-labels-or-instructions': {
        owner: 'the composing form and caller content',
        verifiedBy: 'form-level review of labels and instructions',
        reason:
          'The menu button trigger does not collect user input that needs form instructions.',
      },
      '4.1.2-name-role-value': {
        owner: 'the button pattern and binding component',
        verifiedBy:
          'BUTTON_PATTERN for adopters, plus binding-local role, name, and unavailable-state tests',
        reason:
          'This contract encodes the control role and name, aria-haspopup, the expanded state, and their transitions. Other button semantics remain with BUTTON_PATTERN.',
        coversRemainderOnly: true,
      },
      '4.1.3-status-messages': {
        owner:
          'the caller and the assistive-technology verification record, spec:AST-009',
        verifiedBy:
          'the status-message pattern and real-AT evidence under AST-009 when a change claims spoken or braille output',
        reason:
          'Showing or hiding ordinary content is not itself a status-message contract, and this pattern makes no announcement claim.',
      },
      'apg-interaction': {
        owner: 'the button pattern',
        verifiedBy:
          'BUTTON_PATTERN for adopters, plus binding-local role, name, reachability, and activation tests',
        reason:
          "This contract encodes the menu button's state, relationship, and opening transitions. The menu itself — item roles, arrow navigation inside it, Escape and focus return — is the menu pattern's; the trigger's generic button semantics stay with BUTTON_PATTERN.",
        coversRemainderOnly: true,
      },
      'forced-colors': {
        owner: 'the binding component and theme',
        verifiedBy:
          "the component's forced-colors tests plus rendered Windows High Contrast review",
        reason:
          'Forced-colors output is a paint result owned by the binding and theme.',
      },
      'reduced-motion': {
        owner: 'the binding component and theme',
        verifiedBy:
          "the component's reduced-motion source tests and rendered motion review",
        reason:
          'Reveal motion is binding-specific paint over time and is not part of menu button semantics.',
      },
      'at-facing-strings': {
        owner: 'the binding component and caller content',
        verifiedBy:
          'the repository i18n catalog check and source review of authored labels and descriptions',
        reason:
          'The menu button contract introduces no string; trigger and content text come from the binding or caller.',
      },
    },
  });