jpmschweitzerandClaude
77e395b3f2
Three docs under docs/testing/:
* README.md — layer-by-layer reference (what each covers, the
runner, how to invoke, local vs CI flow). Points at the load-
bearing startup gate and the client-side-only constraint so a
macOS clone runs the same suite as Linux.
* a11y-manual.md — 15-minute manual checklist run at every tier
cut. Orca on Linux, VoiceOver on macOS. Catches prose drift
automation can't judge.
* claude-ui-workflow.md — how Claude Code drives the WASM build
through Playwright, including the `flt-semantics-placeholder`
quirk (semantics are opt-in in Flutter web; the driver
auto-clicks the placeholder to enable them).
Co-Authored-By: Claude <noreply@anthropic.com>
1.8 KiB
Manual a11y checklist — run at every tier cut
Automated a11y tests catch structural regressions (missing Semantics, broken contrast, missing i18n keys). They don't catch "this label is technically correct but reads like robot noise." A 15-minute manual pass at every tier cut does.
Linux — Orca
- Start Orca:
orca -s(settings), toggle on "Focus follows mouse". - Launch clide:
flutter run -d linuxor the built bundle. - Tab through every slot in order. Every stop should read
- panel name, then
- a one-line verb describing what the widget does.
- Open the command palette (
ctrl+konce it's wired). Read each command out loud. Flag commands whose name alone doesn't make it obvious what they do. - Open the theme picker. Orca should announce "Select theme", then read each row as "theme name, activate this theme". Selecting announces the new theme.
- Disconnect the daemon mid-session. Orca should announce the statusbar change (it's a live region).
macOS — VoiceOver
VoiceOver: cmd+F5. Same checklist as Orca. Extra pass:
- Rotor navigation (
ctrl+opt+u) should list every Semantic landmark; no "unknown group" entries. - Per-element hints read cleanly when pressing
ctrl+opt+shift+h.
Report a drift
Any label that feels off — noise, tech jargon, abbreviations screen
readers mispronounce — becomes a follow-up ticket. Do not "fix" in
the branch being cut; queue it so each tier stays focused. File
under docs/todo-a11y.md (create if absent) with:
- [ ] ext.<id>: <key-or-widget> — <what's wrong>, <suggested wording>
Why this isn't automated
Automation catches structural violations. Automation can't judge prose. A 15-minute human pass per tier stays cheap and catches the gap. Revisit automation (axe-core via Playwright, Flutter a11y harnesses) if we ship a public build.