From c9f2dfe0f41024b1fbb55b5ba8d09a20b493e714 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Wed, 16 Sep 2026 16:06:04 +0200 Subject: [PATCH 01/75] WCAG 2.2 AA accessibility improvements Phase 1: Theme toggle span->button with aria-label, nav/menu expanders aria-pressed->aria-expanded, SVG controls a->button with keyboard zoom + focus trap, btn-reset/search/copy-code focus-visible indicators. Phase 2: Search combobox+listbox ARIA pattern, aria-live status announcements, th scope=col, admonition role=note/alert, contentinfo footer landmark, prefers-reduced-motion override. Phase 4: axe-core post-build check (scripts/check_a11y.mjs) integrated into check.bat. --- builder/PLAN-a11y.md | 264 ++++++++++++++++++ builder/render.mjs | 31 +- builder/template.mjs | 13 +- .../vendor/just-the-docs/_sass/buttons.scss | 5 + builder/vendor/just-the-docs/_sass/code.scss | 5 +- .../vendor/just-the-docs/_sass/search.scss | 3 +- .../just-the-docs/assets/js/just-the-docs.js | 48 +++- check.bat | 2 + docs/_sass/custom/custom.scss | 24 +- docs/assets/js/svg-inline.js | 127 +++++++-- docs/assets/js/theme-switch.js | 7 +- package-lock.json | 11 + package.json | 3 +- scripts/check_a11y.mjs | 125 +++++++++ 14 files changed, 616 insertions(+), 52 deletions(-) create mode 100644 builder/PLAN-a11y.md create mode 100644 scripts/check_a11y.mjs diff --git a/builder/PLAN-a11y.md b/builder/PLAN-a11y.md new file mode 100644 index 00000000..4a350340 --- /dev/null +++ b/builder/PLAN-a11y.md @@ -0,0 +1,264 @@ +# Accessibility Audit — WCAG 2.2 AA + +Target: WCAG 2.2 AA conformance for the online site at `docs.twinbasic.com`. + +Scope: the generated HTML template/chrome (builder pipeline, JS, CSS) **and** content-level patterns (tables, code blocks, admonitions, SVG diagrams, headings) — but with a firm constraint on where fixes land. + +## Guiding principle: no HTML in markdown + +Accessibility fixes must not push raw HTML into `docs/` markdown files. The markdown source should stay readable, diffable, and free of ARIA attributes. Every fix belongs in one of: + +- **`builder/template.mjs`** — page skeleton, sidebar, search, breadcrumbs, footer. +- **`builder/render.mjs`** — markdown-it renderer rules, post-processing (admonitions, tables, anchor headings, code blocks). This file already has custom `th_open`, `td_open`, `table_open` rules that inject wrapper divs and normalise attributes — the same pattern extends to `scope`, `role`, etc. +- **SCSS files** — focus indicators, motion, contrast. +- **JS files** — `just-the-docs.js`, `theme-switch.js`, `svg-inline.js` — ARIA state management, live regions, focus trapping, keyboard handlers. + +If a fix *cannot* be expressed in the pipeline — i.e. it requires per-page semantic knowledge that the builder can't infer — document it as a content-authoring guideline in WIP.md and apply to affected pages in a separate pass. But aim to avoid this. + +--- + +## Phase 1 — Keyboard & semantic blockers + +These are real WCAG failures: keyboard users and/or screen reader users cannot operate parts of the site. + +### 1.1 Theme toggle: `` → `