[Audit 26/32][P2][Accessibility] Run full a11y audit and fix ARIA, focus, keyboard, contrast, and live feedback gaps

[baixiangcpp]

Recommended execution order

26 of 32. Run after major layout work so accessibility fixes target stable UI.

Evidence level

Static observation; full assistive-technology verification needed.

Problem

The site has visible semantic structure and a Skip to content link, but the audit could not verify all ARIA labels, focus states, modal focus traps, keyboard flows, screen-reader output, or dynamic status announcements.

Why this matters

Developer tools often rely on dense forms, icon buttons, copy actions, and generated output. These must be keyboard-accessible and understandable to assistive technologies.

Recommended implementation

• Run Axe and Lighthouse accessibility checks.
• Manually test keyboard-only navigation.
• Verify skip link behavior.
• Add aria-labels for icon buttons.
• Add form labels and descriptions for inputs/outputs.
• Add aria-live regions for copy success, run success, run errors, import/export feedback.
• Verify modal focus trap and Escape behavior.
• Add high-contrast or reduced-motion options if needed.

Acceptance criteria

• No serious or critical Axe violations on representative pages.
• Lighthouse accessibility score is at least 90 on representative pages.
• All primary workflows can be completed with keyboard only.
• Focus states are visible.
• Copy/run/import/export feedback is announced to assistive tech.
• Modals trap focus and restore focus on close.
• Tool input/output areas have clear accessible names.
• High-risk tools and Pipeline Builder are included in manual checks.

[baixiangcpp]

Automated accessibility audit coverage landed in PR #297 (80756c18fd8a4c3dc4154b75323837d6fbe777bb).

Completed in this batch:

• Added browser-level axe coverage for representative pages with zero serious/critical violations required.
• Kept skip-link, header language keyboard path, mobile navigation, command palette, copy feedback, Pipeline Builder, and PWA flows covered by Playwright smoke.
• Fixed shared mobile/tablet touch targets and Pipeline Builder mobile diagnostics.
• Validation passed locally and in CI: npm run validate, npm run lint, npm run build:app, npm run build:post, npm run test:e2e:smoke, and npm run test:e2e:pwa.

Still not closed because these acceptance items require manual/assistive-technology verification:

• NVDA, VoiceOver, or TalkBack output for Pipeline Builder and external-request flows.
• Modal focus trap and focus restoration in real AT/browser combinations.
• Lighthouse accessibility score verification in a stable Chrome/Lighthouse environment.

[baixiangcpp]

PR #300 landed docs/accessibility/audit-23-25-26-manual-closure-runbook.md and guard coverage for the remaining #263 manual closure criteria.

Current status:

• Automated axe serious/critical coverage, keyboard smoke paths, live-feedback checks, focus/contrast guards, and representative component coverage are already in CI.
• The remaining acceptance criteria require assistive-technology and Lighthouse evidence: NVDA or desktop VoiceOver, TalkBack or iOS VoiceOver, modal/focus restoration in real AT/browser combinations, and Lighthouse accessibility >= 90 on representative pages.
• The issue should stay open until those manual AT/Lighthouse checks are run and the runbook closure template is posted here.

Latest validation for the runbook PR passed in CI: Cloudflare Pages and build (20.x).

[baixiangcpp]

PR #301 (eb58faca5f805e6a437f3ebc64de8385a98f7651) landed Lighthouse accessibility follow-ups for #263.

Completed in this follow-up:

• Removed incomplete overriding accessible names from the home command trigger and All Tools card links so visible labels and accessible names stay aligned.
• Fixed non-structural footer navigation text so it no longer disrupts heading order.
• Preserved Trust Center heading sequence for the summary cards.
• Increased dark-mode contrast for destructive tool actions such as Clear/Reset.
• Added tests/guards/lighthouse-a11y-followups.test.ts so these Lighthouse patterns stay covered.

Lighthouse evidence gathered on 2026-06-27 with Node 20 + Lighthouse 13.4.0 against production representative pages:

Route	Accessibility score
/	100
/en/all-tools	100
/en/json-formatter	96
/en/pipeline-builder	100
/en/trust-center	98
/en/install-app	98

Validation for PR #301:

• Local: focused guard/component tests, check:types, lint, validate, build:app, build:post, test:e2e:smoke.
• CI: Cloudflare Pages passed and build (20.x) passed.

Keeping #263 open because the remaining acceptance criteria still require real assistive-technology verification: NVDA or desktop VoiceOver, TalkBack or iOS VoiceOver, modal/focus restoration in real AT/browser combinations, and the final runbook closure template with tester/device/browser evidence.

[baixiangcpp]

Automated verification refresh on 2026-06-27 for main@eb58faca5f805e6a437f3ebc64de8385a98f7651.

Passed locally:

• npm run test:e2e:pwa

Relevant #263 coverage in that run:

• Skip-link keyboard path.
• Header language keyboard path.
• Mobile navigation keyboard path.
• Command palette desktop and mobile journeys.
• Representative axe matrix with zero serious or critical violations.
• PWA/offline smoke still passed after the Lighthouse follow-up fixes from PR Fix Lighthouse accessibility follow-ups #301.

Also confirmed after PR #301 merge:

• CI on main passed: build (20.x) run 28285679896.

Keeping #263 open because the remaining close criteria still require real assistive-technology verification: NVDA or desktop VoiceOver, TalkBack or iOS VoiceOver, modal/focus restoration in real AT/browser combinations, and the final runbook closure template with tester/device/browser evidence.

[baixiangcpp]

Automated verification refresh on 2026-06-29 for current main.

Passed locally:

• npm run check:audit:prod-high passed. The production high/critical gate remains green; the known Next bundled PostCSS finding remains moderate and is tracked separately in Track upstream fix for Next bundled PostCSS advisory #7.
• npm test -- --run tests/guards/pwa-install-offline-issue-260.test.ts tests/guards/mobile-a11y-audit-issues-262-263.test.ts tests/guards/next-postcss-advisory-runbook.test.ts passed: 3 files, 11 tests.
• npm run test:e2e:pwa passed.
• npm run lint passed.
• npm run check:types passed.
• npm run validate passed.

Relevant #263 coverage refreshed by the PWA run:

• Skip-link keyboard path remains green.
• Header language keyboard path remains green.
• Mobile navigation keyboard path remains green.
• Desktop and mobile command palette journeys remain green.
• Copy/action feedback paths covered by the smoke and guard checks remain green.
• Pipeline Builder smoke path remains green.
• Representative axe matrix still reports no serious or critical violations.
• PWA/offline smoke remains green after the current main changes.

Recent remote evidence:

• Latest confirmed main CI run is green: 28374709014.

Boundary for closure:

• This refresh does not satisfy the manual acceptance criteria.
• [Audit 26/32][P2][Accessibility] Run full a11y audit and fix ARIA, focus, keyboard, contrast, and live feedback gaps #263 should stay open until real assistive-technology checks are completed, including NVDA or desktop VoiceOver, TalkBack or iOS VoiceOver, modal/focus restoration in real AT/browser combinations, Lighthouse accessibility evidence on representative pages, and the final runbook closure template with tester/device/browser evidence.

[baixiangcpp]

PR #336 merged as cb8b4ab with the #263 implementation preserved in commit 5a72cc7.

Additional accessibility evidence completed:

• Command Palette, JSON Tree dialogs, and Pipeline privacy dialogs now have initial focus, bidirectional Tab trapping, Escape/cancel/confirm behavior, and opener focus restoration coverage.
• JSON key rename restores focus to the replacement node action when React disconnects the original keyed opener.
• Full Playwright smoke passed the representative Axe serious/critical matrix and keyboard paths.
• Lighthouse 13.4.0 accessibility reports for the merged candidate scored 100 on Home, All Tools, JSON Formatter, Pipeline Builder, Trust Center, and Install App.
• Remote build (20.x), dedicated PWA CI, Cloudflare Pages, and Codex review all passed with no actionable review findings.

Keeping #263 open because NVDA/desktop VoiceOver and TalkBack/iOS VoiceOver output still require real assistive-technology/browser verification and the manual runbook evidence.

[baixiangcpp]

Closure-environment audit refresh on 2026-07-16 for main@df9dae7.

Automated accessibility evidence remains green: PR #336 recorded Lighthouse 100 on all six representative routes, representative Axe serious/critical checks and keyboard/dialog focus paths passed, and post-merge CI run 29532382529 passed the complete unit/coverage/validate/build/Playwright matrix.

This Windows host does not have NVDA installed, cannot run macOS VoiceOver, and has no Android/iOS device for TalkBack or iOS VoiceOver. Windows Narrator is present, but it is not one of the desktop AT combinations required by the repository's manual closure runbook and cannot substitute for mobile AT output.

No new code defect was found. Keep #263 open until real NVDA/desktop VoiceOver plus TalkBack/iOS VoiceOver output, announcement, dialog, and focus-restoration evidence is recorded by a tester.

[baixiangcpp]

Desktop screen-reader evidence - 2026-07-16

Validated the PR #338 preview at adf4a4b66b on Windows NT 10.0.26200 with NVDA 2026.1.1 and Chrome 150.0.7871.46. The identical commit is now on main through merge commit f87ad34158a769c3a4a9766933798eb1026e4587. Tester: Codex desktop AT session.

Observed NVDA output:

• Invalid JSON Format and Minify each announced one error and did not announce a false completion.
• Valid JSON Format and Minify each announced one completion.
• Monaco Ctrl+Enter and Ctrl+Shift+Enter each triggered one action announcement and did not insert a newline.
• JSON Copy announced success once.
• Pipeline sample loading and run completion each announced the intended status once.
• YouTube external-request permission and ready states each announced once; no external request was sent during the check.

PR #338 had no review threads, Codex reported no major issues, and build (20.x), pwa, and Cloudflare Pages all passed before merge.

This satisfies the targeted desktop NVDA announcement regression covered by #338. It is not a full closure record: this Windows host still has no physical Android TalkBack or iOS VoiceOver session, so the required mobile screen-reader/device checks remain outstanding. Keep #263 open until that evidence is attached.

[baixiangcpp]

Desktop screen-reader follow-up - 2026-07-17\n\nPR #341 was merged through merge commit \72b90969810378ef33761cb65982cc46431cac81. The desktop AT regression was run on Windows 11 with NVDA 2026.1.1 and Chrome 150.\n\nThe full session covered the named \Tool actions\ group and native Tab order, JSON input/error/success feedback, All Tools search and filter dialog, Pipeline labels/run log/failure/privacy dialog, external-request disclosure and disabled reasons, and shell/dialog focus restoration. Two NVDA findings were fixed before merge: the mobile filter opener now exposes a complete count-bearing name, and external-request offline feedback no longer announces twice.\n\nFinal immutable-preview verification at https://69645812.byteflow-c58.pages.dev:\n- The isolated Chrome window remained entirely on the left display (bounds \x=-1880..-380).\n- NVDA spoke \Show filters. Active filters: 1\ exactly once.\n- NVDA spoke the external-request Offline status exactly once.\n- No request to \youtube.com, \youtube-nocookie.com, \youtu.be, or \i.ytimg.com\ was emitted during the offline check.\n\nFinal repository/remote evidence:\n- Full local suite: 1,743 passed and 3 skipped; production build and smoke E2E/Axe passed.\n- PR build, PWA, Cloudflare Pages, and Codex re-review passed; Codex reported no major issues on \cb8ab2d.\n- Post-merge main CI run https://github.com/baixiangcpp/byteflow.tools/actions/runs/29603258577 passed audit, lint, unit, coverage, validate, build/post-build gates, Playwright smoke, PWA smoke, and route-width screenshot matrix.\n\nThis completes the required desktop NVDA evidence. Keep #263 open because this host still has no physical Android TalkBack or physical iPhone VoiceOver session; the mobile screen-reader checks in the manual closure runbook remain outstanding.