Accessibility Testing Skill

Browser Tooling Routing (read first)

npx playwright test

.spec.js

.spec.js

references/baseline-url-scan.mjs

playwright

@axe-core/playwright

--census

--alt-snapshot

agent-browser

@e1

/webwright:run

/webwright:craft

aria_snapshot()

keyboard-a11y-tester

0.5.0

@guidepup/virtual-screen-reader

0.32.1

agent-browser screenshot

agent-browser screenshot --annotate

agent-browser snapshot

browser_press_key

npx playwright test

agent-browser

Do you have a prose description of what to test, but no test script yet?
  YES → /webwright:run (one-shot) or /webwright:craft (reusable parameterized tool)
  NO, you need to run an existing test → npx playwright test
  NO, you have a list of URLs and need machine-readable axe evidence across all of them, no test file → references/baseline-url-scan.mjs (or pa11y-ci --sitemap for sitemap-wide sweeps)
  NO, you need to audit a live URL against a user goal (journey, announcements, focus indicators) → keyboard-a11y-tester
  NO, you need to assert component announcements, names, or reading order in unit tests (no URL yet) → virtual-screen-reader
  NO, you need to explore interactively → agent-browser

agent-browser

focus → press Enter → aria-expanded: false → true

Meta+K

agent-browser

Input.dispatchKeyEvent

Verification evidence contract

page.keyboard.press()

npx playwright test

keyboard-a11y-tester

virtual-screen-reader

baseline-url-scan.mjs

--census

--alt-snapshot

agent-browser screenshot

a11y-critic

bug-reporting

Interactive reconnaissance with agent-browser

.spec.js

agent-browser

agent-browser open https://example.com/component-under-test
agent-browser snapshot -i                    # Returns interactive elements with refs: [ref=e1], [ref=e2]...
agent-browser focus @e1                      # Focus by ref
agent-browser press Enter                    # Real CDP keyboard event
agent-browser get attr @e1 aria-expanded     # Verify state mutation
agent-browser screenshot --annotate          # Numbered overlays mapping to refs (useful for multimodal review)
agent-browser close

--profile Default

--session <name>

--json

--allowed-domains

npx playwright test

agent-browser

.spec.js

Test script generation with Webwright

sync_playwright

/webwright:run

/webwright:run Navigate to https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/.
Open the modal by clicking the trigger button.
Verify focus moves into the modal.
Tab through all focusable elements and verify focus wraps (focus trap).
Press Escape and verify the modal closes and focus returns to the trigger.

• Keyboard events use

  page.keyboard.press()

  or

  locator.press()

  , NOT synthetic

  dispatchEvent

• Assertions verify state changes (before/after), not just attribute presence
• No

  time.sleep()

  > 5 seconds or hardcoded waits that mask timing issues

page.locator("body").aria_snapshot()

agent-browser snapshot -i

• No built-in axe-core — the LLM must write injection code (it does this correctly; see benchmark task 3c)
• May miss a11y-specific patterns unless the prompt is specific about what to check
• Python scripts don't run in JS CI without a Python runner
• Requires Claude Code plugin install — not available in Codex CLI
• Do not run simultaneously with agent-browser — both launch Chrome instances that may conflict on ports

page.keyboard.press()

evals/suites/webwright-benchmark/

Installation

pip install playwright && playwright install chromium

1. /plugin marketplace add microsoft/Webwright

2. /plugin install webwright@webwright

git clone https://github.com/microsoft/Webwright && /plugin install ./Webwright

agent-browser

keyboard-a11y-tester

.py

python3 script.py

Goal-driven journey audits with keyboard-a11y-tester

.spec.js

agent-browser

0.5.0

7e852a7

97eb13e

.click()

@guidepup/virtual-screen-reader

--storage-state <playwright-storageState.json>

evals/results/keyboard-a11y-tester/README.md

Install (clone path — verified; Node ≥ 20)

git clone https://github.com/ezufelt/keyboard-a11y-tester && cd keyboard-a11y-tester
git checkout 0.5.0                    # adopted pin (tagged release)
npm install && node scripts/setup-check.mjs   # npx playwright install chromium only if browser_available=false

/plugin marketplace add ezufelt/keyboard-a11y-tester

Run

# Batch blind Tab-crawl (unattended; never presses Enter/Space) — per viewport:
node scripts/runner.mjs --url https://site --viewport desktop --max-steps 40 --out <dir>

# Driven session (the value center — the agent decides every keystroke):
node scripts/runner.mjs serve --url https://site --goal "find and submit the contact form" \
     --viewport desktop --port 9333          # default port is 9333 (9400 in upstream examples is just an example)
# prints: READY <session-dir>
node scripts/runner.mjs observe <session-dir>
node scripts/runner.mjs step <session-dir> --press Tab      # one key → AX name/role/state, focus style, sr_announcement
node scripts/runner.mjs step <session-dir> --type "hello@example.com"
node scripts/runner.mjs finish <session-dir> && node scripts/runner.mjs stop <session-dir>

sr_announcement.live_announcements

Artifacts (temp dir, or

--out

)

• trace.json

  — per step: keystroke, selector, CDP AX name/role/state, computed focus style,

  focus_moved

  , screenshot ref,

  sr_announcement

• deterministic-findings.json

  —

  {wcag, persona, conformance_level, confidence, severity, url, locations, persona_impact, evidence[]}

• screen-reader-census.json

  — whole-page reading order (spoken phrase, role, selector) + declared live regions

• screenshots/step_NNNN.png

  — focused-region crops

Calibration rules (measured on our 33 fixtures, 2026-07-10)

1. Batch-mode 4.1.3 "silent live region" findings are never failure evidence. A blind crawl never operates anything, so correctly-wired regions look silent (confidence 0.35–0.4 vs 0.7+ elsewhere). They are prompts to run a driven session and judge from

   live_announcements

   .
2. UA-intrinsic names mask missing labels. An unlabeled

   <input type=file>

   reports AX name "Choose File", so the unnamed-control check stays quiet. Label association still needs axe/static/judgment review.
3. Component-scale pages ≠ full pages. Skip-link (2.4.1) and landmark findings assume a whole page; on component targets treat them as granularity artifacts.
4. AA vs AAA honesty. 2.4.13 focus-appearance findings are AAA-informative by design — never report them as 2.4.7 failures. The AAA pixel measurement is also rendering-environment-sensitive (macOS locally can emit AAA-informative findings that Linux CI does not, observed at both

   97eb13e

   and

   0.5.0

   ) — one more reason never to gate on it.
5. Emulated SR ≠ real AT. Findings are spec-compliant-announcement evidence; the §6 manual NVDA/VoiceOver protocol still applies before shipping.

6. conformance_level

   is the check's gate, not the SC's WCAG level (code-read at

   0.5.0

   , not fixture-measured — upstream #27, filed 2026-08-04). Only the 2.4.13 check emits

   AAA

   ; every other finding falls through

   level || 'AA'

   to

   "AA"

   , mislabeling the nine Level A SCs the checks cover (1.1.1, 1.3.1, 1.4.1, 2.1.2, 2.4.1, 2.4.3, 3.2.1, 3.3.2, 4.1.2) — 2.4.7 and 4.1.3 are coincidentally correct. Read the field only as pass-fail (

   AA

   ) vs informative (

   AAA

   ) and derive the SC's true level from the SC number. Delete this rule when the pin advances past a fix for #27.

Mapping findings → A11y Evidence Finding Contract

• severity:

  serious

  → MAJOR (CRITICAL if it blocks the goal);

  moderate

  → MINOR or MAJOR by user impact;

  minor

  /AAA-informative → ENHANCEMENT
• fingerprint: derive from selector + wcag + check kind (the tool's

  id

  embeds the viewport and is run-scoped — don't use it)
• persona → perspective_alarms:

  keyboard

  →

  keyboard_motor

  ;

  screen-reader

  →

  screen_reader_semantic

• evidence: cite step ids + measured values (e.g.

  trace.json step_0003: outline 3px solid; AAA contrast 2.34

  )

Cautions

• Client production sites: on pages with a CAPTCHA the runner suppresses

  navigator.webdriver

  (page-scoped) so the CAPTCHA can initialize — automation-signal spoofing that can trip a WAF or security review. Get explicit client sign-off before pointing it at client production infrastructure; prefer staging.
• Don't run concurrently with agent-browser or Webwright sessions (Chrome instance/port contention). Chromium-only — cross-browser coverage stays with

  npx playwright test

  .
• Run desktop and mobile viewports separately; navigation often collapses behind a disclosure on mobile.

Component screen-reader assertions with virtual-screen-reader

implement → test

user-event

.spec.js

aria-busy

0.32.1

"button, Save document"

"polite: Draft saved"

virtual.perform(virtual.commands.*)

moveToNextHeading

moveToNextLandmark

jumpToErrorMessageElement

@storybook/addon-vitest

docs/virtual-screen-reader-adoption-assessment.md

Install (Node ≥ 20)

npm install --save-dev @guidepup/virtual-screen-reader@0.32.1   # exact pin; re-verify calibration rules on any bump

Core patterns (Vitest, jsdom environment — the verified harness)

import { afterEach, expect, test } from "vitest";
import { virtual } from "@guidepup/virtual-screen-reader";

afterEach(async () => {
  await virtual.stop().catch(() => {});   // stateful singleton — mandatory, or phrase logs leak across tests
  document.body.innerHTML = "";
});

// 1. Announcement assertion — persistent-container pattern (the only reliable shape; see rule 3)
test("saving announces to screen reader users", async () => {
  document.body.innerHTML = `
    <main><button>Save</button></main>
    <div role="status" id="app-status"></div>  <!-- persistent, empty at mount -->
  `;
  await virtual.start({ container: document.body });
  document.getElementById("app-status").textContent = "Item saved";
  await Promise.resolve();   // microtask flush suffices (measured) — no arbitrary sleep needed
  expect(await virtual.spokenPhraseLog()).toContain("polite: Item saved");
});

// 2. Reading-order / name assertions — bounded walk (never while-true; see rule 1)
test("reads the expected sequence", async () => {
  document.body.innerHTML = `<h2>Cart</h2><p>$29.00</p><button>Buy now</button>`;
  await virtual.start({ container: document.body });
  const phrases = [];
  for (let i = 0; i < 40; i++) {           // max-step guard: aria-modal traps the cursor by design
    await virtual.next();
    const p = await virtual.lastSpokenPhrase();
    phrases.push(p);
    if (p === "end of document") break;
  }
  expect(phrases.indexOf("$29.00")).toBeLessThan(phrases.indexOf("button, Buy now"));
});

Storybook stories as SR tests (verified 2026-07-13: Storybook 10.4.6 +

@storybook/addon-vitest

browser mode, Chromium)

npx vitest run --project=storybook

import { expect, userEvent, waitFor } from "storybook/test";
import { virtual } from "@guidepup/virtual-screen-reader";

export const AnnouncesOnSave = {
  play: async ({ canvasElement, canvas }) => {
    await virtual.start({ container: canvasElement });   // scope to the story canvas
    try {
      await userEvent.click(await canvas.findByRole("button", { name: "Save order" }));
      await waitFor(async () =>
        expect(await virtual.spokenPhraseLog()).toContain("polite: Item saved"));
    } finally {
      await virtual.stop();   // mandatory — measured: the phrase log SURVIVES a missing stop and bleeds into the next story (start() itself recovers; the leak is the hazard)
    }
  },
};

finally

@storybook/test-runner

evals/results/virtual-screen-reader/harness/storybook/

Calibration rules (measured 2026-07-11 at 0.32.1; environments noted)

1. Never walk-to-end-of-document when

   aria-modal="true"

   is present (jsdom). The cursor traps inside the modal by design (upstream #54) — the walk never terminates. Scope

   container

   to the component and bound every walk with a max-step guard.
2. A silent or short walk is not a clean pass — check for shadow roots first (jsdom). Open shadow DOM is invisible (upstream #182). If

   element.shadowRoot

   exists anywhere under the container, VSR evidence is partial: route to keyboard-a11y-tester or browser testing instead.
3. Mount-with-content live regions read as silent — including correctly-fixed ones (jsdom AND Chromium — engine behavior, not a jsdom artifact). VSR announces mutations inside existing live regions (text changes, child insertions, mount-empty-then-fill) but not insertion of a pre-populated

   role="alert"

   element. Removal splits on

   aria-atomic

   (measured, fixture sweep): clearing a non-atomic region is silent; clearing an

   aria-atomic="true"

   region announces an empty

   "polite: "

   phrase — an empty polite entry is a region-clear marker, not noise. Interpretive context (domain knowledge, not probed here): real screen readers are also inconsistent on pre-populated alert insertion, which is why robust toast guidance uses a persistent container. Consequences: assert via the persistent-container pattern; a silent log after mount-with-content of an alert is inconclusive, not proof the fix failed; buggy-component silence is defect evidence only alongside the structural fact (no role/aria-live present).
4. Fake timers wedge the singleton — hard incompatibility (Vitest; Jest unmeasured, mechanism harness-independent). Under fake timers,

   start()

   resolves but log reads hang forever, and the wedged state cascades hangs into every later test in the file, teardown included. Never enable fake timers in a file that runs VSR. Components needing fake timers (auto-dismiss toasts) get announcement assertions in a separate real-timer file — natural with the persistent-container pattern (assert the announcement on show; the timed dismiss is a separate concern).
5. Cite the VSR version in every piece of evidence (

   vsr@0.32.1 <test file>

   ). Both consumption routes are frozen (this exact pin; keyboard-a11y-tester's committed lockfile), so skew arises only on deliberate upgrade — the citation makes it detectable. Re-verify rules 1–4 on any version bump.

Evidence

evals/results/virtual-screen-reader/

docs/a11y-evidence-finding-contract.md

Baseline URL-list scan with references/baseline-url-scan.mjs

.spec.js

2026-08-13-epa-public-sites/evidence/harness/audit-pages.mjs

.spec.js

agent-browser

playwright

@axe-core/playwright

CLAUDE.md

1280x800,320x800

--viewports WxH[,WxH...]

summary.json

agent-browser

keyboard-a11y-tester

• --census

  — three DOM-census heuristics, reported under a

  census

  key on every viewport record, always separate from axe's

  violations

  /

  incomplete

  and always labeled detector heuristics, never a conformance verdict: empty paragraphs (no text, no element children), autocomplete-absence (inputs whose type/name/label suggest a WCAG 1.3.5 known purpose but carry no

  autocomplete

  attribute), and duplicate ids (an id used on more than one element).

• --alt-snapshot

  — writes

  alt-snapshot.json

  : one entry per URL, each a sorted list of every

  img

  /

  svg[role=img]

  's selector,

  src_or_title

  , and

  alt

  . Captured once per page (first viewport only — alt text doesn't vary by viewport).

Install and run

npm install -D playwright @axe-core/playwright   # peer deps — install in your own project, never in this repo
npx playwright install chromium

node .claude/skills/a11y-test/references/baseline-url-scan.mjs --urls-file urls.txt --out ./baseline-scan-output
# or pass URLs directly, with a custom viewport list:
node .claude/skills/a11y-test/references/baseline-url-scan.mjs --out ./out --viewports 1280x800,320x800 https://example.com https://example.org/page
# with the DOM-census heuristics and an alt-text snapshot:
node .claude/skills/a11y-test/references/baseline-url-scan.mjs --out ./out --census --alt-snapshot https://example.com

urls.txt

http(s)://

#

--delay

@axe-core/playwright

package.json

axe_core_version

summary.json

--alt-snapshot

alt-snapshot.json

node references/baseline-url-scan.mjs --out ./before --alt-snapshot https://example.com/page
# ...make your change...
node references/baseline-url-scan.mjs --out ./after --alt-snapshot https://example.com/page
diff before/alt-snapshot.json after/alt-snapshot.json

What this mode IS and IS NOT

• IS for: baseline and regression sweeps across many pages in one run; machine-readable evidence (rule id, impact, node count, sample selectors) that can feed a11y-critic Phase 0 or the Optional A11y Evidence Finding Contract (§4 below); trend baselines across repeated runs of the same URL list — rerun and diff

  summary.json

  (or

  alt-snapshot.json

  for alt-text specifically).
• IS NOT: keyboard-operability or screen-reader evidence of any kind — it never presses a key or captures an announcement (route those to keyboard-a11y-tester or virtual-screen-reader). Axe-core is a detector, not a verdict authority here, same as every other automated lane in this bundle: it covers roughly 30-40% of WCAG 2.2 issue classes (the same axe-detectable-subset ceiling as the §4 in-spec-file scans below), and its rules are heuristics, not the standard itself. A clean scan is not a conformance claim — it means axe found nothing in its rule set on the URLs scanned, nothing more. Treat the output as candidate findings for human review. The

  --census

  checks are heuristics one level below even axe's rules — pattern-matches on markup shape and naming, not accessibility-tree computation — so their false-positive rate is higher by design; triage every

  census

  hit by hand before filing it.

pa11y-ci for sitemap-wide sweeps (routed, not vendored)

pa11y-ci

npx pa11y-ci --sitemap https://example.com/sitemap.xml --runner axe --runner htmlcs

1. Keyboard Accessibility Tests

Required Testing Method

• Use

  page.keyboard.press('Enter')

  ,

  page.keyboard.press('Tab')

  ,

  page.keyboard.press('Escape')

  ,

  page.keyboard.press('Space')

  for single keys
• Use

  page.keyboard.press('Shift+ArrowRight')

  ,

  page.keyboard.press('Control+Enter')

  ,

  page.keyboard.press('Meta+Enter')

  for key combos
• Use

  page.keyboard.down('Shift')

  /

  page.keyboard.up('Shift')

  with

  page.keyboard.press('ArrowRight')

  for held-key sequences (e.g., text selection)
• Use

  element.focus()

  then verify with

  toBeFocused()

  or

  document.activeElement === element

• NEVER use synthetic

  dispatchEvent(new KeyboardEvent(...))

  to test keyboard features — that bypasses the real browser keyboard path and proves nothing
• NEVER claim a keyboard test passed by only reading DOM attributes (aria-expanded, aria-pressed, etc.) without actually pressing a key and observing the state change

What to Test (with real key presses)

1. Tab order: Press Tab repeatedly and verify focus moves to each interactive element in logical order
2. Enter/Space activation: Focus a button/link, press Enter or Space, verify the expected action occurred (panel opened, state toggled, navigation happened)
3. Escape to dismiss: Open a modal/popup/sidebar, press Escape, verify it closed
4. Arrow key navigation: For tablists, menus, and custom widgets — press Arrow keys and verify focus/selection moves
5. Keyboard text selection: For content areas — use Shift+Arrow to select text, verify selection was created via

   window.getSelection()

6. Modifier combos: Test Ctrl+Enter, Meta+Enter, and other app-specific shortcuts
7. Focus management: After opening/closing panels, verify focus moves to the correct element (e.g., CKEditor gets focus when annotation form opens, focus returns to trigger after modal closes)

State Verification Pattern

1. Record initial state (aria-expanded, aria-pressed, visibility, activeElement)
2. Perform real keyboard action (page.keyboard.press)
3. Wait for UI to update (waitForTimeout or waitForFunction)
4. Verify state actually changed (attribute toggled, element visible/hidden, focus moved)

const btn = page.locator('button[aria-expanded]');
const initialExpanded = await btn.getAttribute('aria-expanded');
await btn.focus();
await page.keyboard.press('Enter');
await page.waitForTimeout(300);
const afterExpanded = await btn.getAttribute('aria-expanded');
expect(initialExpanded).not.toBe(afterExpanded); // State MUST change

WAI-ARIA APG Keyboard Test Templates

page.keyboard.press()

aria-activedescendant

const tree = page.locator('[role="tree"]');
await tree.focus();
const before = await tree.getAttribute('aria-activedescendant');
await page.keyboard.press('ArrowDown');
await page.waitForTimeout(200);
const after = await tree.getAttribute('aria-activedescendant');
expect(after).not.toBe(before);
expect(after).toBeTruthy(); // must reference a [role="treeitem"] id

[role="tab"]

tabindex="0"

tabindex="-1"

aria-selected="true"

[role="tablist"]

const activeTab = page.locator('[role="tab"][tabindex="0"]');
await activeTab.focus();
await page.keyboard.press('ArrowRight');
await page.waitForTimeout(200);
const newActive = page.locator('[role="tab"][tabindex="0"]');
await expect(newActive).toHaveAttribute('aria-selected', 'true');
expect(await page.locator('[role="tab"][aria-selected="true"]').count()).toBe(1);

[role="dialog"]

await triggerButton.click();
const dialog = page.locator('[role="dialog"]');
// Tab past last focusable item — should wrap to first
const focusables = dialog.locator('button, [href], input, [tabindex="0"]');
const count = await focusables.count();
for (let i = 0; i < count; i++) await page.keyboard.press('Tab');
await expect(focusables.first()).toBeFocused();
await page.keyboard.press('Escape');
await expect(triggerButton).toBeFocused();

await triggerButton.click();
const panel = page.locator('[role="region"]'); // or your panel selector
await expect(panel.locator('button[aria-label*="Close"]')).toBeFocused();
await page.keyboard.press('Escape');
await page.waitForTimeout(150); // allow React unmount + setTimeout(0)
await expect(triggerButton).toBeFocused();

aria-expanded

aria-controls

const btn = page.locator('button[aria-expanded]');
await btn.focus();
const initial = await btn.getAttribute('aria-expanded');
await page.keyboard.press('Enter');
await page.waitForTimeout(200);
const toggled = await btn.getAttribute('aria-expanded');
expect(toggled).not.toBe(initial);
const panelId = await btn.getAttribute('aria-controls');
const panel = page.locator(`#${panelId}`);
await expect(panel).toBeVisible(); // when expanded=true

const trigger = page.locator('button[aria-haspopup="menu"]');
await trigger.focus();
await page.keyboard.press('Enter');
await page.waitForTimeout(200);
const menu = page.locator('[role="menu"]');
await expect(menu).toBeVisible();
await expect(menu.locator('[role="menuitem"]').first()).toBeFocused();
await page.keyboard.press('End');
await expect(menu.locator('[role="menuitem"]').last()).toBeFocused();
await page.keyboard.press('Escape');
await expect(trigger).toBeFocused();

aria-expanded

aria-activedescendant

const input = page.locator('[role="combobox"]');
await input.focus();
await input.type('ap');
await page.waitForTimeout(300);
await expect(input).toHaveAttribute('aria-expanded', 'true');
const listbox = page.locator('[role="listbox"]');
await page.keyboard.press('ArrowDown');
expect(await input.getAttribute('aria-activedescendant')).toBeTruthy();
await page.keyboard.press('Enter');
await expect(listbox).toBeHidden();

const listbox = page.locator('[role="listbox"]');
await listbox.focus();
await expect(listbox.locator('[role="option"]').first()).toHaveAttribute('aria-selected', 'true');
await page.keyboard.press('ArrowDown');
await page.waitForTimeout(150);
await expect(listbox.locator('[role="option"]').nth(1)).toHaveAttribute('aria-selected', 'true');
await page.keyboard.press('End');
await expect(listbox.locator('[role="option"]').last()).toBeFocused();

aria-valuenow

aria-valuemin

aria-valuemax

const slider = page.locator('[role="slider"]');
await slider.focus();
const before = Number(await slider.getAttribute('aria-valuenow'));
await page.keyboard.press('ArrowRight');
await page.waitForTimeout(150);
expect(Number(await slider.getAttribute('aria-valuenow'))).toBeGreaterThan(before);
await page.keyboard.press('Home');
expect(await slider.getAttribute('aria-valuenow')).toBe(await slider.getAttribute('aria-valuemin'));
await page.keyboard.press('End');
expect(await slider.getAttribute('aria-valuenow')).toBe(await slider.getAttribute('aria-valuemax'));

const input = page.locator('[aria-label*="date" i]');
await input.focus();
await page.keyboard.press('Enter');
const grid = page.locator('[role="grid"]');
await expect(grid).toBeVisible();
await page.keyboard.press('ArrowRight');
await page.keyboard.press('PageDown');
await page.keyboard.press('Enter');
await expect(grid).toBeHidden();
expect(await input.inputValue()).not.toBe('');

aria-expanded

const headers = page.locator('[role="button"][aria-expanded]');
await headers.first().focus();
const initial = await headers.first().getAttribute('aria-expanded');
await page.keyboard.press('Enter');
await page.waitForTimeout(200);
expect(await headers.first().getAttribute('aria-expanded')).not.toBe(initial);
await page.keyboard.press('ArrowDown');
await expect(headers.nth(1)).toBeFocused();
await page.keyboard.press('End');
await expect(headers.last()).toBeFocused();

aria-checked

const radios = page.locator('[role="radiogroup"] [role="radio"]');
await radios.first().focus();
await page.keyboard.press('ArrowDown');
await page.waitForTimeout(150);
await expect(radios.nth(1)).toHaveAttribute('aria-checked', 'true');
await expect(radios.first()).toHaveAttribute('aria-checked', 'false');
await page.keyboard.press('Tab');
await expect(radios.nth(1)).not.toBeFocused();

Live Site Requirement

if (!BASE_URL || !BASE_URL.match(/https?:\/\/.+/)) {
  throw new Error('Keyboard tests require a real site. Set BASE_URL.');
}

SPA-Specific Testing Patterns

• No direct URL navigation: SPA routes (e.g.,

  /book/truth-lending/2460032

  ) return 404 from the server — the server has no route for them. Navigate WITHIN the app by clicking menu items and waiting for React to render. Use

  waitForSelector()

  to confirm content has loaded before interacting.
• Duplicate DOM (mobile + desktop): Many React apps render the same component twice — once for desktop, once for mobile. Playwright strict mode throws when a selector matches both. Fix by scoping to a container (

  nav.left-sidebar [role="tree"]

  ) or appending

  .first()

  /

  .last()

  to your locator.
• React state waits: After

  page.keyboard.press()

  , React state updates are async — the DOM may not reflect the new state for tens of milliseconds. Add

  waitForTimeout(200–500)

  or

  waitForFunction(() => ...)

  before asserting on ARIA attributes that change via React state.
• React 16

  setTimeout(0)

  for focus-after-unmount: In React 16, focus calls issued inside async callbacks do not survive component unmount. Production code must wrap the focus call in

  setTimeout(() => el.focus(), 0)

  . Tests must account for this by allowing 100–200ms after a panel closes before checking

  document.activeElement

  .
• DOMPurify stripping

  data-*

  attributes: A bare

  DOMPurify.sanitize()

  call strips

  data-*

  attributes by default. If tests find click handlers broken after sanitization, the fix is to route sanitization through a wrapper component that calls sanitize at render time (not as a pre-processing step that discards needed attributes).
• Playwright MCP cannot deliver keyboard events: The Playwright MCP browser integration CANNOT forward keyboard events —

  browser_press_key

  calls are silently dropped for most interactive widgets. Always run keyboard a11y tests with

  npx playwright test

  using

  .spec.js

  files. Use the MCP browser only for visual inspection and DOM queries.

CSS Anti-patterns That Break Keyboard Access

visibility:hidden

:focus-within

visibility: hidden

:focus-within

• visibility: hidden

  removes the element from the tab order entirely
• Because the element can't receive focus,

  :focus-within

  is never triggered on the parent
• Result: keyboard users can never reach the element at all

/* ❌ BROKEN — keyboard users can never trigger :focus-within on the parent */
.annotation-block-edit {
  opacity: 0;
  visibility: hidden; /* removes from tab order → :focus-within never fires */
}
.annotation-block:focus-within .annotation-block-edit {
  opacity: 1;
  visibility: visible;
}

/* ✅ CORRECT — opacity keeps element in tab order; :focus-within works */
.annotation-block-edit {
  opacity: 0; /* visually hidden but still focusable */
}
.annotation-block:hover .annotation-block-edit,
.annotation-block:focus-within .annotation-block-edit {
  opacity: 1;
}

opacity

visibility

ARIA Attribute Checks (supplement, not substitute)

• Buttons have

  aria-label

  or visible text
• Toggle buttons have

  aria-pressed

  or

  aria-expanded

• Tab widgets have

  role="tablist"

  ,

  role="tab"

  ,

  aria-selected

• SVGs inside buttons have

  aria-hidden="true"

• Close buttons have descriptive

  aria-label

• Only one tab has

  aria-selected="true"

  per tablist

Section 5: Time-Based Media Tests

<video>

<audio>

Caption Infrastructure

• Verify

  <track kind="captions">

  exists on every

  <video>

  with speech
• Verify

  <track>

  has valid

  src

  pointing to caption file
• Verify caption toggle control exists and is keyboard-accessible

Transcript Availability

• Verify transcript exists adjacent to media OR a visible link to it
• For audio-only content: verify full text transcript is available

Media Player Keyboard Access

• Tab: focus enters player controls; all controls have visible focus indicators
• Space: play/pause toggle
• Arrow keys: seek forward/backward; Up/Down: volume control
• C or CC button: caption toggle; Escape: exit fullscreen

Audio Auto-play

• Verify no audio auto-plays on page load
• If auto-play exists: verify pause/stop control is the first focusable element

Section 6: Screen Reader Test Protocol

Test Matrix

Landmark Navigation Test

• Use landmark navigation (NVDA: D key, VoiceOver: Web rotor)
• Verify:

  <main>

  ,

  <nav>

  ,

  <header>

  ,

  <footer>

  announced correctly
• Verify: multiple

  <nav>

  elements have distinguishing

  aria-label

Heading Navigation Test

• Navigate by headings (NVDA: H key, VoiceOver: Web rotor); verify hierarchy is logical, no skipped levels;

  <h1>

  present

Form Mode Test

• Tab into form (NVDA enters focus mode automatically)
• Verify: each input announces its label and "required" if applicable
• Verify: error messages announce when field is focused;

  aria-describedby

  reads after label

Live Region Test

• Trigger dynamic content changes (form submission, async updates, notifications)
• Verify:

  aria-live="polite"

  announces after current speech
• Verify:

  aria-live="assertive"

  interrupts; toast content announced without focus moving

SPA Route Change Test

• Navigate between routes; verify page title updates and is announced
• Verify: focus moves to main content or heading; back button restores expected focus

2. Visual Regression Tests (REQUIRED)

Baseline Strategy

• Preferred: Use

  npx playwright test --update-snapshots

  on the current branch to establish baselines, then run tests after further changes to detect regressions.
• CRITICAL — build must be complete first: Only run

  --update-snapshots

  after any build (React, webpack, etc.) has fully finished. Running it during a concurrent build captures mixed pre/post-build screenshots — some pages reflect old code, some new. The resulting baseline is internally inconsistent and will fail on the next clean run. Wait for the build to complete, then run

  --update-snapshots

  , then run the tests.
• Cross-branch comparison: Only when explicitly requested. Requires branch switching, cache clearing, and potential config sync — avoid unless necessary.
• Never assume branch-switching is safe without checking with the user first.

Playwright Screenshot Configuration

toHaveScreenshot()

• maxDiffPixelRatio

  (0 to 1): Maximum ratio of different pixels to total pixels. Use

  0.01

  (1%) for element screenshots,

  0.03

  (3%) for full-page screenshots. This is the primary control for flakiness.

• threshold

  (0 to 1): Per-pixel color distance tolerance (0 = exact, 1 = any color). Default

  0.2

  is fine for most cases. This is NOT the overall diff threshold.

• maxDiffPixels

  : Absolute count of allowed different pixels. Alternative to

  maxDiffPixelRatio

  .

// Element screenshot — tight tolerance
await expect(element).toHaveScreenshot('name.png', {
  maxDiffPixelRatio: 0.01,
});

// Full-page screenshot — looser for dynamic content
await expect(page).toHaveScreenshot('name.png', {
  fullPage: true,
  maxDiffPixelRatio: 0.03,
  mask: [page.locator('.dynamic-region')],
});

BackstopJS (Optional)

npm install --save-dev backstopjs

backstop.json

• Use

  scenarioDefaults

  for shared settings (delay, misMatchThreshold, removeSelectors)
• Use

  "selectors": ["document"]

  for full-page, or class/tag selectors for elements
• Avoid attribute selectors with quoted values (e.g.

  [type='text']

  ) — they cause parse errors in Puppeteer engine
• Use

  requireSameDimensions: false

  for pages with dynamic heights
• Full-page scenarios need higher

  misMatchThreshold

  (15-20%) due to dynamic content
• Element scenarios can use tighter thresholds (5-10%)

onReady.cjs

.cjs

"type": "module"

const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
module.exports = async (page, scenario, vp) => {
  await wait(2000);
  await page.evaluate(() => {
    document.querySelectorAll('dialog, [role="dialog"], .modal, .popup').forEach(el => el.remove());
  });
  await wait(300);
};

npx backstop reference --config=path/to/backstop.json  # Capture baseline
npx backstop test --config=path/to/backstop.json       # Compare against baseline
npx backstop approve --config=path/to/backstop.json    # Promote test -> reference
npx backstop openReport --config=path/to/backstop.json # View HTML report

Handling Dynamic Content

• Prefer element-level screenshots over full-page — more stable and more useful for a11y regression detection.
• Mask dynamic regions: Playwright uses

  mask: [page.locator()]

  , BackstopJS uses

  removeSelectors

  or

  hideSelectors

  .
• Common elements to mask/remove:

  .contextual

  ,

  .toolbar-tray

  ,

  .messages

  ,

  [data-drupal-messages]

  ,

  dialog

  ,

  [role="dialog"]

  , time/date elements.
• Dismiss popups before capture: Use Playwright's

  dismissPopups()

  helper or BackstopJS

  onReadyScript

  .
• Use

  waitForLoadState('networkidle')

  and a short wait to let JS behaviors settle before capture.

Contrast Verification

• Use browser DevTools (Chrome: CSS Overview, Firefox: Accessibility Inspector) to audit all text contrast
• Run axe-core with

  color-contrast

  rule enabled (catches most but not all cases)
• Manually check: text over images/gradients (axe-core misses these)
• Manually check: focus indicator contrast against both focused and unfocused backgrounds
• Check non-text contrast: UI component borders, icons, form control outlines (WCAG 1.4.11)
• Test with forced-colors mode: verify all interactive elements remain distinguishable

Zoom and Reflow Verification

• Set viewport to 1280px, zoom to 400% (equivalent to 320px)
• Verify: no horizontal scrollbar, content reflows to single column
• Verify: no text truncation, overlap, or content hidden behind other elements
• Test text spacing override: 1.5x line height, 2x paragraph spacing, 0.12em letter spacing
• Verify: all interactive elements remain visible and operable at 200% zoom

Elements to Test

• Focus indicators (links, buttons, inputs in :focus state)
• Breadcrumbs (structure and current page indicator)
• Navigation menus (default, hover, active states)
• Form inputs (borders, focus states)
• Link underlines in content areas
• External link icons
• Skip links (when visible)
• Progress bars and loading indicators

Viewport Sizes

• Desktop: 1280x800
• Tablet: 768x1024
• Mobile: 320x568

Reporting

• Playwright:

  npx playwright show-report

  for HTML report with side-by-side diffs
• BackstopJS:

  npx backstop openReport

  for visual comparison dashboard

3. WCAG Compliance Checks

• 1.1.1 Non-text Content (alt text, aria-labels)
• 1.4.1 Use of Color (link underlines)
• 1.4.3 Contrast Minimum (4.5:1 normal text, 3:1 large text — note: text inside UI components like buttons uses TEXT thresholds, not the 3:1 UI component boundary threshold)
• 1.4.10 Reflow (320px viewport)
• 1.4.11 Non-text Contrast (form borders, focus indicators)
• 2.4.4 Link Purpose (contextual aria-labels)
• 2.4.6 Headings and Labels (no empty headings)
• 2.4.7 Focus Visible (outline visibility)
• 2.4.8 Location (breadcrumbs with aria-current)
• 2.4.11 Focus Not Obscured (focused element not hidden by sticky headers/footers/banners) [WCAG 2.2]
• 2.4.13 Focus Appearance (focus indicator ≥2px perimeter, 3:1 contrast change) [WCAG 2.2]
• 2.5.7 Dragging Movements (drag ops have single-pointer alternative) [WCAG 2.2]
• 2.5.8 Target Size (interactive targets ≥24x24 CSS pixels) [WCAG 2.2]
• 3.3.7 Redundant Entry (don't re-ask for info already provided) [WCAG 2.2]
• 3.3.8 Accessible Authentication (no cognitive function tests for login, paste/autofill supported) [WCAG 2.2]

4. Automated Scanning (axe-core via Playwright)

axe-core Injection Pattern

// In a Playwright test file (.spec.js)
const { test, expect } = require('@playwright/test');
const fs = require('fs');

test('axe-core accessibility scan', async ({ page }) => {
  await page.goto(BASE_URL);
  await page.waitForLoadState('networkidle');

  // Inject axe-core
  const axeSource = fs.readFileSync(
    require.resolve('axe-core/axe.min.js'), 'utf-8'
  );
  await page.evaluate(axeSource);

  // Run audit
  const results = await page.evaluate(() =>
    axe.run(document, {
      runOnly: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice']
    })
  );

  // Report violations
  const violations = results.violations;
  if (violations.length > 0) {
    const report = violations.map(v => ({
      id: v.id,
      impact: v.impact,
      description: v.description,
      helpUrl: v.helpUrl,
      nodes: v.nodes.length
    }));
    console.log('axe violations:', JSON.stringify(report, null, 2));
  }
  expect(violations.length).toBe(0);
});

Multi-Page Scanning

• Default state (no interactions)
• Loading state (if applicable — trigger a load and scan before it completes)
• Error state (submit an invalid form, then scan)
• Expanded state (open all disclosures/tabs, then scan)

Dynamic Test Prioritization

• axe found ARIA violations → prioritize screen reader testing (Section 1 keyboard + ARIA checks)
• axe found color-contrast violations → prioritize visual inspection (Section 2 focus indicators, link underlines)
• axe found heading/structure violations → prioritize keyboard navigation order testing
• axe found no form violations → deprioritize form testing with a note that automated checks passed
• Always test regardless: focus indicators at zoom, reduced-motion, skip links

Scale and Sampling (>15 pages)

1. Run

   discover

   phase: list all routes, group by template (list page, detail page, form page, etc.)
2. Select 1-2 pages per template group
3. Scan representatives, report which templates were covered
4. Document sampling strategy in the test report

docs/wcag-em-2-reference.md

1. Random sample: add a randomly selected sample of 10% of the structured (template-based) sample, on top, drawn from routes not already selected; record the selection method in the test report
2. Representativeness check: if the random sample surfaces content types or violation patterns the structured sample missed, the template classification was not representative — expand the structured sample, re-classify, and repeat until the random sample stops surfacing new finding types
3. Complete processes: multi-view journeys (checkout, multi-step applications, auth) are tested end-to-end, never as isolated pages — include every view in the process (the default sequence plus completion-critical branches) and route them to keyboard-a11y-tester driven sessions (see "Goal-driven journey audits" above); per-page scans do not count as process evidence
4. State coverage: each sampled page is evaluated in its states (default, loading, error, expanded — the Multi-Page Scanning list above); name the state coverage in the sampling documentation

Output Format

## axe-core Scan Results
Pages scanned: [count]
Total violations: [count]
Critical: [n] | Serious: [n] | Moderate: [n] | Minor: [n]

### Violations by Rule
| Rule ID | Impact | Description | Pages | Elements |
|---------|--------|-------------|-------|----------|
| color-contrast | serious | Elements must meet color contrast | 3 | 12 |

Optional A11y Evidence Finding Contract

A11y Evidence Finding

a11y-critic

perspective-audit

### A11y Evidence Finding
finding_id: stable lowercase id, e.g. a11y_form_error_describedby
fingerprint: stable 8-64 char hex hash derived from component/target/rule, not the crawl URL alone
source: test command, test file, axe rule id, agent-browser ref, or observed artifact
wcag_or_apg: WCAG 2.2 criterion or WAI-ARIA APG pattern citation
section_508_fpc_context: Section 508 context only when applicable; Revised Section 508 maps web conformance to WCAG 2.0 Level A/AA
severity: CRITICAL | MAJOR | MINOR | ENHANCEMENT
perspective_alarms: screen_reader_semantic=LOW|MEDIUM|HIGH; keyboard_motor=LOW|MEDIUM|HIGH; etc.
evidence: file:line, DOM excerpt, axe node, screenshot, keyboard trace, or measured value
reproduction_steps: commands or user steps needed to reproduce
expected_behavior: what the user or assistive technology should experience
actual_behavior: what the test observed
trend: new | persistent | worsening | improving | resolved

• Treat WCAG 2.2 AA as the current planning and testing target. Treat Section 508 as regulatory context only when the project scope explicitly requires it.
• Use stable fingerprints to support trend language across reruns. Prefer component name + selector/accessibility target + rule/pattern + criterion over route-only fingerprints.
• Mark perspective alarms only when the evidence suggests a perspective-specific access risk. Any MEDIUM or HIGH alarm can feed

  perspective-audit

  .
• Do not copy scanner/runtime code or generated dashboard state from external projects into this skill. This contract is a reporting discipline, not a crawler product boundary.

5. Static Analysis (eslint-plugin-jsx-a11y) — React/Vue/JSX only

Setup

# Install as dev dependency
pnpm add -D eslint-plugin-jsx-a11y  # or npm/yarn

# Create temporary standalone config (avoids ESLint 9 flat config issues)
cat > eslint.a11y.mjs << 'EOF'
import jsxA11y from "eslint-plugin-jsx-a11y";
import tseslint from "typescript-eslint";
export default [{
  files: ["src/**/*.tsx", "src/**/*.jsx"],
  plugins: { "jsx-a11y": jsxA11y },
  languageOptions: {
    parser: tseslint.parser,
    parserOptions: { ecmaFeatures: { jsx: true } },
  },
  rules: { ...jsxA11y.flatConfigs.recommended.rules },
}];
EOF

# Run
npx eslint --config eslint.a11y.mjs src/

# Clean up temp config (keep the plugin installed)
rm eslint.a11y.mjs

Known False Positives

role

<Link>

ICT Testing Baseline coverage crosswalk (declared Section 508 audits only)

atbcb/ICTTestingBaseline

main

6c537a3b

• The not-covered and partial rows are the deliverable. They name what gets assigned to manual/AT methods in the evaluation plan's sampling and coverage boundary. Never imply stack coverage the crosswalk doesn't grant; a test classified judgment-only in the manifest is never

  covered

  .
• Every baseline test ID cited must exist in

  docs/ict-baseline-test-id-manifest.yaml

  for the web baseline. IDs are valid per-baseline (

  11.A-PageTitled

  is web-only;

  11.A-DocumentTitled

  is documents-only), and baseline IDs are the exact-ID class models fabricate — hand-verify every one; never generate them.
• Phrasing: "designed to cover N of 62; gaps: ..." — never "baseline-aligned" or "baseline-conformant" (alignment recognition is an external review of a test process), and never any Trusted Tester certification claim (a DHS credential held by humans).

• 24.A-Parsing

  always passes by upstream design (WCAG 2.0 Errata 13) — execute nothing for it; report real markup consequences under the SCs they actually break.
• The Electronic Documents baseline is out of measurement scope entirely (web-only stack): document samples go to the report's coverage boundary with a manual/AT method, never to these execution modes.
• Maintenance: the crosswalk is rebuilt by hand against

  docs/ict-testing-baseline-reference.md

  on that reference's recheck triggers — a regenerated crosswalk without value-checking is the fabrication failure mode by construction.

Test Execution Order

1. Static analysis (§5) — fast, no server needed
2. Keyboard accessibility tests (§1)
3. Visual regression tests (§2)
4. axe-core automated scans (§4)
5. WCAG compliance checks (§3)
6. Time-based media tests (§5-media) — if applicable
7. Screen reader tests (§6) — if applicable
8. Report consolidated results with pass/fail counts per section