Skip to content

Human Screen-Reader Walkthrough (WW-63e) — the layer that cannot be automated

Plain-language version: Screen-Reader Walkthrough Checklist — the actual script a person follows.

This is the engineering rationale for Layer 4 of the accessibility stack in a11y-verification.md: a timeboxed manual pass where a human runs NVDA (or Narrator) and listens. It is deliberately not a test, has no CI job, and cannot fail a build. This doc explains why that is correct rather than a gap someone should close.

Where it sits

Layer Mechanism Verdict type CI
1 — static axe npm run test:a11y, built app, backend offline machine-checkable WCAG 2.2 AA hard gate (frontend job)
2 — live axe a11y-live.spec.ts, real backend same rules, real data states hard gate
3 — NVDA automation a11y-sr.spec.ts (Guidepup, real NVDA, real speech) asserted announcement strings local/manual only — see its header
4 — this walkthrough a person, 10 minutes, Windows qualitative judgement none, by design

Layers 1–3 answer "is it correct?" This layer answers "is it usable?" — and those are different questions with different oracles.

Why Layer 4 can't be a gate

The automated layers verify propositions: this control has an accessible name, focus moves into the dialog, the heading order is monotonic, contrast passes. All decidable, all asserted, all already covered by the structure sweep (test:a11y:structure) and the axe gates.

What they cannot decide is whether the result is coherent by ear. Every one of these passes every automated check and is still bad:

  • A link named Apply for Senior Staff Software Engineer, Payments Platform (Remote — US) — a perfect accessible name that takes nine seconds to hear before you learn it's a link.
  • A route where every heading is technically correct and the reading order still tells the story backwards.
  • A status region that announces correctly, and announces on every keystroke.
  • A judgement-pause dialog that traps focus properly and never says why it interrupted you.

There is no assertion for "too chatty." There is no selector for "this made me feel lost." Encoding one would mean inventing a threshold, and then the threshold becomes the target — the suite would go green while the app got harder to hear. The same rule that governs metrics elsewhere in this repo applies to test oracles: a proxy that can be satisfied without producing the outcome is worse than an honest human check.

So Layer 4 stays a judgement call, run by a person, producing notes rather than a boolean.

Scope and cadence

  • Timebox: 10 minutes. Long enough for the five flows in the checklist, short enough to actually get done. A 45-minute protocol would be more thorough and would never be run.
  • Platform: Windows only. NVDA and Narrator are the readers our users have; VoiceOver behaviour is not a substitute and would produce misleading notes.
  • Routes covered: queue, sidebar nav, onboarding form, and both interrupt dialogs (judgement pause, account wall). The two dialogs matter most — they're the moments the app takes control away from the user, and the moments a screen-reader user is most likely to be stranded.
  • When to run: before a release that touched navigation, dialogs, forms, or focus management. Not every PR — the automated layers cover regression; this covers drift.

What comes back

Notes, in four buckets the checklist names: reading order, verbosity, stuck moments, and technically-correct-but-weird. Findings become backlog tickets like any other bug.

A walkthrough that produces no notes is a suspicious walkthrough, not a clean one — the same way a review with no comments usually means nobody read it. The expected output of ten minutes of honest listening is at least one "that was awkward."

  • a11y-verification.md — the full four-layer stack, and how to run layers 1–3
  • a11y-sr.spec.ts — Layer 3's real-NVDA automation, and its header comment on why it is local-only
  • contributing.md — the CI gates this walkthrough deliberately is not part of