Run the WCAG gate in an engine that does layout, and fix what it found

[ChelseaKR]

Closes #14. Adds ADR-0008. Independent of #26, #27 and #28; base is main.

What it found, on the first run

The scroll containers holding the wide tables were not keyboard reachable.

[serious] scrollable-region-focusable: Scrollable region must have keyboard access
    .tall.scroll:nth-child(7)
    .scroll:nth-child(19)

Every wide table on these pages sits in a container with overflow-x: auto. That is the conforming answer to WCAG 2.2 SC 1.4.10 Reflow, because the page itself does not scroll. On its own it is also a WCAG 2.1.1 Keyboard failure: a container that scrolls and cannot be focused scrolls for a mouse and a trackpad and not for a keyboard, so a sighted keyboard user cannot read the columns past the right edge at all.

Nothing in this repository could have found it. Whether a container scrolls is a fact about layout, and jsdom does none. tools/a11y.mjs had been green over it for three weeks, and so had every careful reading of the markup.

Each container is now a <section> with tabindex="0", named from the table's own caption, which every table here already carries. html-validate refuses role="region" in favour of the element, which is also the better answer: a named section is a region landmark natively, with no ARIA attribute to go stale.

The gate

Two engines, both kept.

	jsdom (tools/a11y.mjs)	Chromium (tools/a11y_browser)
Needs a browser binary	no	yes
Undecidable list	four rules, each declared with a reason	none: an undecided rule fails
SC 1.4.10 Reflow	not possible	320 by 256
SC 2.5.8 Target size	undecidable, covered nowhere	decided
Colour contrast	undecidable; measured arithmetically in test_pages_html.py	decided

Both read the built pages off disk as file:// URLs. Nothing is served, no port is opened, and CI reaches the network only to fetch the browser. The reflow spec is ported from ledger's tools/a11y_browser/reflow.spec.ts, which runs against a served app; the adaptation is that these pages are static files.

Wired into make pages, so it is inside make verify and CI runs it as the same target, which is what CONTRIBUTING.md promises. make browser-audit runs npm audit --audit-level=high against the harness: a gate's own toolchain is not exempt from the check the gate exists to apply.

Proof the new gate can fail

Run unchanged against main's built pages (built in a detached worktree, PERIMETER_SITE_DIR pointed at it):

  2 failed
    [chromium] › axe.spec.ts:27:7 › axe in a browser: dins.html
    [chromium] › axe.spec.ts:27:7 › axe in a browser: perimeters.html
  6 passed (2.8s)

The six that pass there are positive controls that pass in both states: three reflow assertions, two directory guards, and index.html, which carries no scroll container.

tests/test_a11y_browser_gate.py, in the shape tests/test_a11y_gate.py already uses, is the ADR-0004 evidence. Eleven cases:

• a conformant page passes both specs (positive control, parametrised over both)
• a block 900px wide fails reflow at 320px
• a 300-character unbreakable string inside a correctly sized paragraph fails reflow, which is the shape a layout inspector hides
• an unfocusable scroll container fails axe, which is the defect above, kept as a regression
• #aaa on #fff fails axe on contrast, which jsdom files as undecided
• an 8px pointer target fails axe on target-size, which is SC 2.5.8
• an empty directory fails both, rather than passing
• a missing directory fails both, rather than passing

It refuses to skip when CI is set, because a skipped gate test reads as a passing one.

Gate output

$ make verify
...
Required test coverage of 90% reached. Total coverage: 100.00%
============================= 574 passed in 22.55s =============================
...
  8 passed (2.5s)
found 0 vulnerabilities
determinism: build/run-one and build/run-two are byte-identical (5 files)
MAKE_VERIFY_EXIT=0

Exit code read from $?. html-validate clean, both axe runs clean, reflow clean, both dependency trees clean.

About the waivers.yml the issue asks for

Nothing is suppressed anywhere after this, so there is none.

tools/a11y.mjs still declares four rules undecidable in jsdom, but every one of them is now decided by the browser run, and target-size, the one the issue correctly identified as covered by nothing, is decided rather than waived. An empty registry would be a file saying nothing. The absence is the claim, and the Accessibility row in README.md states it, with A11Y-06 and A11Y-09 recorded as met rather than waived.

README.md's "what still needs a person" list loses reflow and target size and keeps print, focus appearance against real backgrounds, a screen reader, and looking at the layout. It also now says that focus appearance matters more than it did, because every scroll container is a new tab stop.

Cost, stated

make verify is slower (roughly 22s of test time against 9s) and needs a browser binary, which is a one-time download. The local gate stays byte-for-byte identical to CI, so the cost is paid in both places or neither.

🤖 Generated with Claude Code