Per-screen-reader worked scripts

Full NVDA + Firefox and VoiceOver + Safari scripts for the sample flow "User edits their profile email." SKILL.md Step 3 has the row template, the VoiceOver chord table, and a minimal excerpt; these are the complete per-reader versions, including the WCAG SC / APG notes that populate the "Why" column.

NVDA + Firefox (Windows)

## NVDA + Firefox (Windows) - User edits their profile email

### Pre-conditions
- NVDA is running.
- Firefox is on https://app.example.com/profile.
- Virtual cursor mode is on (NVDA default for browsers).

### Step 1 - Navigate to the profile-edit form

| Keystroke | Expected announcement                                          |
|-----------|----------------------------------------------------------------|
| H         | "Edit profile, heading level 2" - moves to next heading.       |
| H         | "Profile information, heading level 3" - moves further.        |
| F         | "Email, edit, blank" - jumps to first form field.              |

NVDA's `H` quick-key navigates by heading; `F` by form field.
The announcements should match the visible heading text and field
labels (per WCAG SC 2.4.6 Headings and Labels).

### Step 2 - Edit the email value

| Keystroke         | Expected announcement                                  |
|-------------------|--------------------------------------------------------|
| Enter (focus mode) | "Email, edit, has autocomplete" - enters focus mode.  |
| (type new email)  | (each character spoken if `say characters` is on)     |

### Step 3 - Submit the form

| Keystroke | Expected announcement                                          |
|-----------|----------------------------------------------------------------|
| Tab       | "Save changes, button" - moves to submit.                       |
| Enter     | (no announcement immediately; wait for live region)             |

### Step 4 - Success confirmation

| Behavior          | Expected announcement                                          |
|-------------------|----------------------------------------------------------------|
| (page response)   | "Profile saved" - announced via `aria-live="polite"` region.   |

If no announcement: the success region is missing `aria-live`
attribute, OR the region is added to the DOM with content already
in it (live regions only announce **changes** post-mount).

VoiceOver + Safari (macOS)

VoiceOver uses VO+arrow keys (Ctrl+Option+arrow) and different quick-key patterns from NVDA. Re-author the same flow:

## VoiceOver + Safari (macOS) - User edits their profile email

### Step 1 - Navigate to the profile-edit form

| Keystroke    | Expected announcement                                       |
|--------------|-------------------------------------------------------------|
| VO + Cmd + H | "Edit profile, heading level 2"                              |
| VO + Cmd + J | "Email, edit text"                                           |

VoiceOver's announcements are sometimes more verbose than NVDA's (reads role words like "edit text" where NVDA says "edit"). This is a vendor convention; don't try to suppress it.

Per-archetype WCAG 2.2 checklist builder

Companion reference for screen-reader-test-author. Consult when a component spec needs explicit a11y acceptance criteria before implementation, when building an a11y-acceptance gate at design-review time, or for pre-PR self-review. The checklist pairs with the SKILL.md test narratives for manual verification and with a11y-violation-gate for automated scans.

Step 1 - Identify the component archetype

Each archetype has its own checklist pattern:

Step 2 - Apply the per-archetype checklist

Static text / display

• [ ] Heading levels are sequential (h1 -> h2 -> h3; no skips).
• [ ] Color contrast >= 4.5:1 (or 3:1 for large text per wcag-color-contrast).
• [ ] Decorative-only images have empty alt=""; meaningful images have descriptive alt.
• [ ] Information conveyed by color alone is also conveyed another way (text, icon, pattern; SC 1.4.1).

Interactive - single trigger

• [ ] Native <button> / <a href> used (no <div onclick>).
• [ ] Visible focus indicator at >= 3:1 contrast vs. background.
• [ ] Activatable via Enter (and Space for <button>).
• [ ] Accessible name matches visible label (or is announced via aria-label / aria-labelledby if no visible label).
• [ ] On press: announces state change if applicable (e.g. toggle button announces aria-pressed).
• [ ] Loading / disabled states programmatically conveyed (aria-disabled / aria-busy).

Interactive - form input

• [ ] Has a <label for="..."> OR aria-labelledby referencing a visible label.
• [ ] Required fields marked via required (native) AND a non-color cue.
• [ ] Validation errors conveyed via aria-invalid="true" plus an error message linked via aria-describedby.
• [ ] On invalid submit: focus moves to the first invalid field.
• [ ] Autocomplete attributes set per WCAG 2.2 SC 1.3.5 (autocomplete="email", "name", etc.).
• [ ] Placeholder is NOT used as the only label.

Interactive - multi-state (disclosure / accordion / tabs)

• [ ] aria-expanded reflects open/closed state on the trigger.
• [ ] aria-controls references the controlled region's id.
• [ ] Keyboard interaction matches the APG pattern (opens in new window):
  • Disclosure: Enter/Space toggles.
  • Accordion: Tab between headers; Enter/Space toggles.
  • Tabs: Tab to active tab; Left/Right to navigate; Home/End.
• [ ] Hidden content uses the hidden attribute or display: none (NOT visibility: hidden or opacity: 0, which leave the content focusable).

Interactive - overlay (modal / drawer / popover)

(See wcag-keyboard-navigation references/focus-trap.md for the 6-step pattern.)

• [ ] role="dialog" (modal) OR role="alertdialog" (interrupt).
• [ ] aria-modal="true" for modals.
• [ ] aria-labelledby references the dialog's title.
• [ ] On open: focus moves into the dialog.
• [ ] Tab cycles within the dialog; doesn't escape to the page.
• [ ] Escape closes (for non-destructive dialogs).
• [ ] On close: focus returns to the triggering element.
• [ ] Outside content is inert (or pre-inert focusable cycle).

Composite (combobox, date picker, multi-select)

(See aria-authoring-patterns.)

• [ ] Match the matching APG pattern's full keyboard model.
• [ ] aria-expanded on the trigger.
• [ ] aria-controls linking trigger to the popup.
• [ ] aria-activedescendant (when not moving DOM focus) OR moves DOM focus into the popup.
• [ ] Selected state announced via aria-selected (listbox) or aria-checked (tree).
• [ ] Type-ahead works (typing a letter focuses matching item).

Live region

• [ ] Container has role="status" (polite) or role="alert" (assertive) OR aria-live="polite" / "assertive".
• [ ] Container exists in the DOM before content is inserted (live regions only announce changes; pre-mounted with content suppresses the first announcement).
• [ ] Content updates are detected - for SPA frameworks, ensure the render produces a real DOM mutation rather than a virtual-DOM-only update.

Layout / navigation

• [ ] Landmarks declared: <header> / <main> / <nav> / <footer> / <aside>. (One <main> per page.)
• [ ] Skip-to-main-content link as the first focusable element.
• [ ] Pagination controls have aria-label (e.g. "Pagination").
• [ ] Breadcrumb has aria-label="Breadcrumb" and aria-current="page" on the current page.

Step 3 - Add per-component customization

Beyond the archetype defaults, the spec may declare:

• Custom keyboard shortcuts - verify SC 2.1.4 (Character Key Shortcuts).
• Animation / motion - verify SC 2.3.3 and respect prefers-reduced-motion.
• Auto-rotating content (carousel, ticker) - pause / play control; SC 2.2.2 (Pause, Stop, Hide).
• Time-limited interactions (countdown timer) - pause / extend control; SC 2.2.1 (Timing Adjustable).

Step 4 - Emit the artifact

Manual-verification items must be emitted as concrete keystrokes and expected announcements - never as a bare skill name. The artifact ships into the user's repo and has to be runnable by a tester holding only that file. Baseline commands (per the NVDA user guide (opens in new window) and Apple VoiceOver (opens in new window); same set as SKILL.md Step 3):

A step passes when the announcement identifies the element type, reads the visible label verbatim, and conveys state and position-in-set where applicable.

Markdown checklist (for spec / PR review)

## A11y Checklist - `<ComponentName>`

**Archetype:** Interactive - overlay (modal)

### Required (must pass before merge)

- [ ] Modal has `role="dialog"` and `aria-modal="true"`.
- [ ] Modal title is `aria-labelledby`-referenced.
- [ ] On open: focus moves to first focusable inside modal.
- [ ] Tab cycles within modal; outside content is `inert`.
- [ ] Escape closes; focus returns to trigger.
- [ ] Close button has accessible name "Close" or "Dismiss".
- [ ] Focus indicator on close button at >= 3:1 contrast.

### Per-component (this design adds)

- [ ] Confirmation modal's "Delete" button has `aria-describedby`
      linking to the warning text.
- [ ] On confirm: live region announces "Deleted" via
      `aria-live="polite"`.

### Verification

- Automated: axe-core scan with `dialog` rule enabled.
- Manual (NVDA + Firefox, Windows): press `Enter` on the trigger -
  NVDA announces "Confirm delete, dialog"; `Tab` cycles inside the
  dialog and never reaches page content; `Escape` closes and focus
  returns to the trigger, announced as "Delete, button".
- Manual (VoiceOver + Safari, macOS): `VO`+`Space` on the trigger,
  `VO`+`Right arrow` to walk the dialog contents, `Escape` to
  close - same expected announcements.
- Code review: against the checklist above.

YAML test plan (for test-management tools)

component: ConfirmModal
archetype: overlay-modal
checks:
  - id: AC-MODAL-1
    description: Modal has role and aria-modal
    severity: blocker
    method: automated
    rule: axe::role-modal
  - id: AC-MODAL-2
    description: Focus moves to first focusable on open
    severity: blocker
    method: e2e-test
    framework: playwright
  - id: AC-MODAL-3
    description: Escape closes; focus restored
    severity: blocker
    method: e2e-test
  - id: AC-MODAL-4
    description: Live region announces "Deleted" on confirm
    severity: blocker
    method: manual
    tester_role: a11y-specialist
    instructions: >-
      NVDA + Firefox (Windows): Tab to "Delete", press Enter.
      NVDA must speak "Deleted" from the aria-live="polite" region
      without focus moving. VoiceOver + Safari (macOS): VO+Space on
      "Delete"; same announcement expected.

Anti-patterns

References

• W3C WCAG 2.2 - https://www.w3.org/TR/WCAG22/
• W3C ARIA Authoring Practices - apg (opens in new window).
• Related: wcag-keyboard-navigation, wcag-color-contrast, aria-authoring-patterns, a11y-violation-gate.

Per-widget manual accessibility test matrices

Companion reference for screen-reader-test-author. Consult when a rendered widget has cleared automated scanning and a tester needs a fill-in pass/fail sheet to run by hand against NVDA and VoiceOver. One row = one keystroke + the expected focus behavior + the expected NVDA announcement + the expected VoiceOver announcement + the WCAG 2.2 success criterion that row verifies - so a failure is attributable the moment it is observed.

Where the SKILL.md narrative is organized by user flow ("user edits their profile email"), these matrices are organized by widget archetype, so the same block is reused on every screen that contains that widget. Run automated scanning first to clear structural defects, then run the matrix - rule engines cannot observe focus order in practice, hear an announcement, or confirm focus returned to the trigger.

Announcement strings are expectations, not guarantees

Screen readers report a control's accessible name, role, and state, but the exact wording is chosen by the reader and varies by version and paired browser (NVDA reports name, type, value, state, description, and position for the focused control per the NVDA User Guide (opens in new window) and WebAIM: Using NVDA (opens in new window)).

Treat every string in the matrices below as a containment assertion: the announcement must contain the accessible name, the role word, and any applicable state word. Do not assert string equality. Record the actual string in the Notes column, and record the NVDA version, VoiceOver / macOS version, and browser at the top of the sheet.

Test stacks

Run two stacks, because a defect that one stack papers over the other exposes:

VoiceOver does not infer a label from proximity: an explicit <label for> or aria-label is required for the field name to be announced (WebAIM: Using VoiceOver to Evaluate Web Accessibility (opens in new window)).

How to build a sheet

1. Inventory the widget archetypes on screen. A screen is almost always a composition: a form with three text inputs, one checkbox, one combobox, and a submit button that opens a confirmation dialog uses five blocks.
2. Copy the matching blocks into one sheet, in the order the widgets appear in the DOM. Do not paraphrase the expected column; the value of the matrix is that two testers on different machines assert the same thing.
3. Substitute the placeholders. Replace {name} with the widget's visible label text, {option} with a real option string, {error} with the real validation message. If a widget has no visible label, that is already a finding: record it against SC 4.1.2 before running the block.
4. Run each row and fill Result (PASS, FAIL, or N/A), pasting the actual announcement into Notes whenever it differs from the expectation.
5. Attribute every failure to its row's success criterion. A failing row reports as "row 4, Escape did not close the dialog, SC 2.1.2 Level A" rather than "the dialog is not accessible".

Universal traversal (prepend to every sheet)

Sequential navigation with Tab and Shift+Tab applies to every focusable element regardless of archetype (WebAIM: Keyboard Accessibility (opens in new window)).

Row U4 is the operative check for SC 2.1.2: focus that can enter a component with the keyboard must be able to leave it with the keyboard (WCAG 2.2 (opens in new window)). Inside a modal dialog the equivalent exit is the Escape row, not Tab; see the dialog block.

Row U5's structure keys: NVDA single-letter navigation (f, h, d) (NVDA User Guide (opens in new window)); the VoiceOver rotor opens with VO-U (or VO-Command-Left/Right Arrow), and items within a category are reached with the Up and Down Arrow keys (Apple: Use the VoiceOver rotor on Mac (opens in new window)).

Button

Per the APG Button pattern (opens in new window): Space and Enter both activate; the element has role button and an accessible label, computed by default from its text content.

Row B5 covers the APG convention that an unavailable button carries aria-disabled="true" rather than the native disabled attribute, which would remove it from the tab sequence and make B5 N/A rather than a failure (APG Button pattern (opens in new window)).

Toggle button

A toggle button carries an aria-pressed state (true on, false off), and its label must stay constant across toggles (APG Button pattern (opens in new window)).

If the label text changes between T2 and T3 (for example "Mute" becoming "Unmute" while aria-pressed also flips), record it: the state is being conveyed twice and contradictorily, against the APG note above.

Checkbox

Space toggles a focused checkbox; the element has role checkbox with aria-checked set to true, false, or mixed (APG Checkbox pattern (opens in new window)).

Row C4 wording differs most across versions of both stacks; assert only that a third state distinct from checked and unchecked is spoken.

Text input / form field

Tab enters and exits a text field and arrow keys move within the text (WebAIM: Keyboard Accessibility (opens in new window)). NVDA switches into focus mode automatically on interactive fields when automatic focus mode is enabled (NVDA User Guide (opens in new window)).

SC 3.3.1 requires that a detected input error is identified and described to the user in text (WCAG 2.2 (opens in new window)). Row F7 fails if the error is only a red border or an icon, even when the field is otherwise announced correctly.

Modal dialog

APG specifies the container has role="dialog" with aria-modal="true" and is labeled by aria-labelledby or aria-label (APG Dialog (Modal) pattern (opens in new window)).

Read D4 and D5 together. An intentional focus cycle is a design requirement of the pattern, not a violation, only because D5 provides a keyboard exit. If D5 fails while D4 passes, the widget is a keyboard trap under SC 2.1.2, not a correctly implemented dialog.

Menu button

APG specifies the trigger has role="button", aria-haspopup "set to either menu or true", and aria-expanded set to true when the menu is displayed and false when it is hidden (APG Menu Button pattern (opens in new window)). Behavior once the menu is open is defined by the menu pattern (APG Menu and Menubar pattern (opens in new window)).

Combobox

APG specifies role="combobox" on the input, aria-expanded set to false when the popup is hidden and true when visible, aria-controls referencing the popup, and aria-activedescendant referencing the focused popup element (APG Combobox pattern (opens in new window)).

Success criterion lookup

Every SC the matrices cite, with its normative anchor. All are current in WCAG 2.2 (WCAG 2.2 (opens in new window)); note WCAG 2.2 removed 4.1.1 Parsing.

Worked example

A ConfirmDeleteDialog opened by a "Delete project" button, containing a "Type the project name to confirm" text input and Cancel / Delete buttons. The sheet composes: Universal traversal, Button (trigger), Modal dialog, Text input, Button (Cancel), Button (Delete).

# Widget accessibility matrix: ConfirmDeleteDialog

Stack A: NVDA 2025.1 + Firefox 141 on Windows 11
Stack B: VoiceOver on macOS 15.4 + Safari 18.4
Tester: ____________________   Date: 2026-07-19

| # | Key | Expected focus / behavior | Expected NVDA | Expected VoiceOver | WCAG 2.2 SC | Result | Notes |
|---|---|---|---|---|---|---|---|
| U1 | Tab first to last | 4 stops, DOM order = visual order | name + role each stop | name + role each stop | 2.4.3 (A) | | |
| U2 | Tab (observe) | focus ring visible at all 4 stops | n/a | n/a | 2.4.7 (AA) | | |
| B1 | Tab | "Delete project" button focused | "Delete project, button" | "Delete project, button" | 4.1.2 (A) | | |
| D1 | Enter on trigger | focus moves inside the dialog | "Confirm delete, dialog" | "Confirm delete, web dialog" | 2.1.1 (A) | | |
| D2 | Tab from Delete (last) | wraps to the text input (first) | "Project name, edit, blank" | "Project name, text field" | 2.4.3 (A) | | |
| D4 | Tab x6 | page behind is never reached | dialog content only | dialog content only | 2.4.3 (A) | | |
| F7 | Tab to input after bad value | error text associated | "Project name, edit, invalid entry, Names do not match" | "Project name, text field, Names do not match" | 3.3.1 (A) | | |
| D5 | Escape | dialog closes | "Delete project, button" | "Delete project, button" | 2.1.2 (A) | | |
| D6 | Enter on Cancel | dialog closes, focus returns to trigger | "Delete project, button" | "Delete project, button" | 2.4.3 (A) | | |

A completed run reports as a per-row verdict list, not a prose summary:

ConfirmDeleteDialog: 7 PASS, 2 FAIL, 0 N/A
FAIL D5  Escape (NVDA + Firefox)   SC 2.1.2 A   dialog stayed open; no keyboard exit
FAIL F7  Tab to errored input (both stacks)  SC 3.3.1 A   heard "Project name, edit"; error text not announced

Anti-patterns

Limitations

• Version drift. Every announcement column is a starting expectation. Re-derive against the exact NVDA build, VoiceOver / macOS version, and browser under test, and record those versions on the sheet.
• Browser pairing changes results. The same markup can announce differently under NVDA with Chrome than with Firefox. Pin the pairing per stack and note it in the report.
• Asynchronous updates. Widgets that populate options lazily or announce via live regions need tester judgment on timing.
• Archetype coverage. The blocks cover button, toggle button, checkbox, text input, modal dialog, menu button, and combobox. For other patterns, derive a new block from that pattern's keyboard interaction table in the APG pattern index (opens in new window).
• No visual or color coverage. Contrast ratios, color-only status cues, and target size are outside these matrices.
• Manual by construction. The tester is the instrument. These matrices produce a signed sheet, not a CI signal.