Ticket #259: accessibility audit — verification
- Date: 2026-11-12
- Branch:
ticket/259-accessibility - Base:
integration/prod-partialsata1fe441 - Spec: parent #255; ticket #259
- Unit gate:
npm run verify(strict typecheck + full test suite) - Result: typecheck passed; 1963 tests passed, 0 failed, 0 skipped after merging
integration/prod-partials(#263); the ticket commit alone passed 1959. - Manual checklist: terminal-accessibility-checklist.md
Contrast
src/v2/tui/theme.ts now exports a pure WCAG contrast helper:
contrastRatio(foreground, background)returns the WCAG ratio, ornullwhen either side is not a concrete color (for exampletransparent).meetsContrast(foreground, background, "text" | "ui")applies the WCAG AA thresholds: 4.5:1 for text, 3:1 for large text and UI.PALETTE_TEXT_ROLESandPALETTE_UI_ROLESclassify every color role. A test fails if a new palette role is neither classified nor an explicit surface/data role.
The table-driven matrix in src/v2/tui/theme.test.ts covers four host surfaces: dark, light, a custom raised dark surface (luminance fallback), and a custom raised light surface. Every text role is checked at 4.5:1 against both the card surface (panel) and the page (bg); border, focus, and card-focus roles are checked at 3:1 against the card surface. Automatic black/white chip text is checked separately. The known WCAG #777777/white 4.48:1 example and the black/white 21:1 pair anchor the helper independently of the palette.
No production palette value changed. The matrix proves the derived paleBlue, cardFocus, and panel fallbacks, and it turns a host theme with inaccessible text into a failing fixture instead of an unstated assumption.
Non-color status
src/v2/tui/workrows.test.ts asserts for every canonical DERIVED_WORK_STATUSES value:
- a visible one-cell glyph;
- a plain uppercase state word (
QUEUED,WORKING,WAITING,RETRYING,NEEDS YOU,REPLIED,FAILED,STALLED,CANCELLED); - a lower-case label and a non-empty detail line;
- a glyph tone, status tone, and bar tone from the palette.
Errors and approvals carry text, not only color: a failed task's transcript announcement includes failed and the bounded error text; a needs-you card reads NEEDS YOU and waiting for you…; approval rows name their source and title. The existing approval and terminal-announcement tests remain in place.
Keyboard-only reachability
src/v2/tui/interaction.test.ts now has a keyboard-only matrix with one row per catalog action and context. Each row proves the action has a key binding and, where the pure reducer owns the transition, that the keyboard event reaches the expected focus, pane mode, overlay, field, mode, or command state. The matrix covers pane selection and movement, Tab/Shift+Tab, roster, chat, Work, settings, wizard, approvals, help, command, composer Insert/Normal/Visual, confirm, picker, and result.
A second test applies the Esc ladder from every context (all panes in select and interact, composer, settings field, wizard field, dialog field, help, logs, command, and visual selection). It fails on any revisited state, proves a fixed point, and requires that fixed point to be an idle no-op except for the wizard's adapter-owned discard confirmation. A third test proves Tab visits every visible pane, returns to the start, skips hidden panes, and never enters a pane. A fourth table asserts every keymap context (including filter, search, and completion) exposes an escape, close, or cancel binding. Together these cover “every action reachable from the keyboard, no focus trap” without rendering OpenTUI.
Reduced motion, NO_COLOR, and ASCII
The reduced-motion and NO_COLOR gates were already tested; the audit adds state-preservation assertions: under NO_COLOR the working card keeps ⠋, WORKING, and its tones. Stagger, clocks, and the work tide remain frozen.
Defect fixed: ASCII mode previously changed only chrome separators. A terminal without a Braille or box-drawing font still received Braille/status marks in the glyph slot. The narrow fix adds one shared isAsciiTerminal(env) predicate and ASCII fallbacks at the existing pure seams:
| Surface | Unicode | ASCII |
|---|---|---|
| chrome separator | │ | ` |
| working / retrying | ⠋ | * / ~ |
| waiting / waiting-for-children | ▫ / ◌ | - / o |
| needs-you | ◆ | ! |
| replied / failed / stalled / cancelled | ● / ✕ / ◍ / ⊘ | + / x / % / / |
| tool / thinking | ▸ / · | > / . |
| empty state | ○───○───○ | o---o---o |
| init stages | ● / ○ | # / - |
| resolved approval | ✓ | + |
State words, card details, approval text, and terminal announcements are unchanged; chat message content is never rewritten. Unicode remains the default, and callers without an explicit ASCII environment keep the existing frames, so the change is limited to the accessibility mode.
Manual checklist
docs/verification/terminal-accessibility-checklist.md covers screen readers (Orca/NVDA/VoiceOver), high-contrast and custom themes, font scaling and the required Braille range (U+2800–U+28FF), reduced motion, NO_COLOR, ASCII fallback, keyboard-only navigation, and host-dependent limits. It records that the TUI is a terminal surface without a semantic accessibility tree, that streaming updates are not live-announced, and that the host owns focus, key routing, fonts, color depth, and high-contrast overrides.
Privacy
This record contains fixture names, role names, thresholds, and test counts only. It contains no conversation content, prompts, answers, credentials, file bytes, or absolute private paths. The contrast fixtures are synthetic palette values, not user data.
Conflict risk
- Low for TUI tickets: changes are confined to
theme.ts,motion.ts,workrows.ts,separators.ts,chrome.ts,initrow.ts,bubbles.ts,components.tsx, andapp.tsxcall sites. There is no layout change and no new runtime seam. - Docs index: the checklist and this record are new files; the only shared docs edit is the Verification index in
docs/README.md. - Other partials: #256 (flake), #257/#258 (host/Node/CI), #260 (latency), #261 (CI matrix), and #262 (docs freshness) do not touch the TUI palette, status grammar, or interaction reducer. A docs-freshness check may want to add these links, but no version constant changes here.