feat(a11y): WCAG 2.2 AA — V1 complete (5 chunks: infra + AA fixes + generators + CI + page) by adoistic · Pull Request #1 · adoistic/falsafa

adoistic · 2026-05-14T15:06:40Z

Summary

All five chunks of the WCAG 2.2 AA implementation. Lands a defensible conformance claim with single-source-of-truth YAML, three AA blocker fixes, three derived-data generators (VPAT 2.5 INT, EN 301 549 Annex F, typed matrix module), a four-job CI workflow that runs real-screen-reader transcripts on every PR, and a public /accessibility page that exposes every claim with click-through proof.

Spec: docs/superpowers/specs/2026-05-14-accessibility-design.md
Plan: docs/superpowers/plans/2026-05-14-accessibility-v1.md

What lands

Chunk 1 — Bootstrap

apps/a11y-tools/ package (zod schema, parser, verifier with lines + anchor evidence); docs/accessibility/conformance.yaml seeded with 86 WCAG SCs + 9 § 508 + 7 EN 301 549; 11 a11y:* npm scripts.

Chunk 2 — AA blocker fixes

B.3 contrast (scripts/a11y-contrast-audit.ts regression gate): --rule 1.22:1 → 3.92:1 light; --accent-soft 2.52:1 → 9.70:1 light; dark + sepia equivalents (15 pairs verified)
B.5 system-pref CSS: prefers-color-scheme, prefers-contrast, forced-colors
B.1 language emission: bcp47Of() + isRtl() helpers normalize corpus's long-form (Urdu/arabic) to BCP-47 (ur-Arab); variant pages emit <article lang dir>; /about wraps 16 foreign-term spans
B.2 RTL: :dir(rtl) overrides in reader.css
B.4 SearchDialog: combobox/listbox pattern with role, aria-expanded, aria-controls, aria-activedescendant, arrow-key navigation; native search clear button restored

Chunk 3 — Generators

VPAT 2.5 INT → docs/accessibility/vpat-v1.0.html (105 table rows)
Annex F → docs/accessibility/statement-en301549.html (EU/US/India enforcement)
Matrix TS module → apps/site/src/lib/conformance.generated.ts (typed, drives the page)
CLI dispatcher: a11y:generate vpat | annex-f | matrix

Chunk 4 — CI workflow + 8 journeys

New deps: pa11y-ci, @guidepup/guidepup, @guidepup/playwright
Playwright config with 3 projects (synthetic / voiceover / nvda); 47 tests across 8 journey specs (homepage, search, catalog, reader-english, reader-original, variant-switch, eval-case, theme-prefs)
Helpers: synthetic-transcript (AT-tree dumper, 3 unit tests), guidepup-helpers (VO + NVDA lifecycle), synthesize-audio (espeak-ng fallback), merge-artifacts (CI artifact reorganizer)
pa11y config with 7 audited URLs (real corpus slugs)
.github/workflows/a11y.yml — 4 parallel jobs (Ubuntu static, Ubuntu synthetic, macOS VoiceOver, Windows NVDA) + commit-results that pushes [skip ci] artifact refresh to main

Chunk 5 — `/accessibility` page + footer link

apps/site/src/pages/accessibility.astro — 10-section audit page (lede + downloads, preferences, audit-yourself, matrix, exceptions, methodology, § 508 + EN 301 549 mappings, recent test runs, JAWS log, report issue)
5 new components under apps/site/src/components/: ConformanceMatrix (4 principle groups, 86 rows, expandable evidence), AccessibilityExceptions, AuditYourself, AccessibilityTestRuns (filesystem-backed), JawsLog (YAML-backed)
apps/site/src/lib/test-run-artifacts.ts — build-time reader for docs/accessibility/test-runs/
apps/site/scripts/prepare-a11y-artifacts.ts — mirrors docs/accessibility/ into Astro's public dir so the page can link to its own VPAT/Annex-F/test-runs via /docs/... URLs
Footer link "Accessibility" on every page (Base.astro)

Evidence in conformance.yaml

WCAG 1.3.1, 1.4.3, 1.4.11, 2.1.1, 2.3.3, 2.4.1, 2.4.6, 2.4.7, 3.1.1, 3.1.2, 4.1.2, 4.1.3 + EN 301 549 § 5.2 — does-not-support → supports with source/test/artifact refs.

Plan deviations (flagged)

Task 14 — works.json schema didn't match; corpus has script populated as long-form names. Pivoted to extend bcp47Of() with normalization maps. Zero data migration.
Task 26 — plan's bunx --cwd apps/site … syntax breaks on current bun. Switched to bunx playwright … --config tests/a11y/playwright.config.ts from worktree root.
Task 33 fix-up — bare bun test auto-loads Playwright .spec.ts files as bun tests (8 load failures). Scoped the test npm script to explicit roots apps scripts tests/a11y/lib.
Journey URLs — plan's simplified slugs (/works/bang-i-dara/01/original/) don't exist; used real corpus slugs (mirza-ghalib-diwan-e-ghalib-74ed4c/01-aa-ke-meri-jaan-ko-qarar-nahin-hai, etc.) for journeys + pa11y URLs.

Verification

bun run test — 386 pass, 0 fail (35 net new across Chunks 2-4)
bun run a11y:contrast — Contrast audit PASSED. 15 pairs verified.
bun run a11y:verify — Conformance YAML verification PASSED (86 criteria, 9 508, 7 EN 301 549 checked).
bun run a11y:generate {vpat,annex-f,matrix} — all three regenerate from the YAML deterministically
bun run --cwd apps/site build — succeeds; 1936 pages indexed including /accessibility
bun run a11y:synthetic -- --list — 47 tests across 8 journeys enumerate
End-to-end DOM smoke on dev server:
- /accessibility → 86 matrix rows (60 / 18 / 8 by status), 10 aria-labelledby sections, download links resolve 200
- /docs/accessibility/vpat-v1.0.html → 200
- /docs/accessibility/statement-en301549.html → 200
- Home page footer → <a href="/accessibility/">Accessibility</a>
- Variant pages emit lang + dir (Chunk 2 carryover, still verified)
- Search dialog emits role="combobox" + role="listbox" (Chunk 2 carryover)

CI first-run expectations

Merge → push to main → triggers 4 parallel jobs (static, synthetic, voiceover, nvda). On success, commit-results downloads all 4 artifact buckets, runs bun run a11y:merge-artifacts to reorganize into the canonical docs/accessibility/test-runs/<journey>/<sha>/ layout, regenerates VPAT/Annex-F/matrix from the new SHA, and pushes chore(a11y): refresh test-run artifacts [skip ci] back to main. Vercel then redeploys; the /accessibility page goes live with the first set of CI artifacts.

The plan acknowledges Guidepup on macOS / NVDA on Windows can be flaky on first setup (audio routing permissions, NVDA installation timing). Job-level if: always() ensures artifacts upload even on partial failure.

Out of V1

Chrome Aa picker (font size + theme override)
Focus-appearance AAA (2.4.13)
Target-size AAA (2.5.8)
Glossary popovers / <abbr> sweep
3 documented content-type exceptions (WCAG 3.1.3 / 3.1.5 / 3.1.6 — graduate-philosophy corpus)

All earmarked for V2 in a separate spec + plan.

Test plan

bun install resolves cleanly
bun run test passes (386 tests)
bun run a11y:contrast exits 0 (15 pairs verified)
bun run a11y:verify exits 0 with 86/9/7 count
bun run a11y:generate {vpat,annex-f,matrix} re-emits artifacts byte-identical (modulo date)
bun run --cwd apps/site build succeeds
/accessibility renders with 86 matrix rows + downloads + footer link
First push to main: 4 CI jobs go green; commit-results produces the artifact-refresh commit

🤖 Generated with Claude Code

Showcase-grade accessibility for govt clients (India / EU / US). Single source of truth (conformance.yaml) generates VPAT 2.5 INT + EN 301 549 Annex F. CI matrix runs axe + pa11y + Playwright synthetic transcripts on Linux, real VoiceOver via Guidepup on macOS, and real NVDA on Windows — all free on public-repo runners. Per-PR audio recordings of both screen readers committed to the repo. /accessibility page surfaces click-through proof per criterion plus an "audit yourself" section. V1 (~5 days): three AA blockers (lang attrs, --rule contrast, search combobox), conformance infra, CI, /accessibility page, system-pref CSS, RTL on Urdu. V2 (~1-2 weeks later): Aa picker chrome control, focus/ target-size AAA polish, glossary popovers, VPAT v1.1. Three content-type exceptions documented (3.1.3 / 3.1.5 / 3.1.6 — graduate philosophy across six languages). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address spec-review feedback: - §B.3 point at tokens.css token definitions, not global.css uses - §B.5 specify prefers-contrast handling for sepia (no override) - §C.1 YAML example uses real tokens.css line range - §C.4 pin eval-case journey to the absorbed TODOS.md item - §D.4 add audio-player accessibility requirement - §Q1 escalate: implementation plan must resolve before coding - §Q8 actions/upload-artifact v4 no longer auto-merges - §Q9 line-number drift mitigation (anchor-based vs exact) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…ks, 42 tasks) Spec → plan transition for WCAG 2.2 AA + AAA-where-feasible. Five chunks, sequential: - Chunk 1 (~1,000 lines, Tasks 1-9): apps/a11y-tools/ package, YAML schema with zod validation, verifier supporting lines + anchor evidence, conformance.yaml seed (86 SCs + 9 Section 508 + 7 EN 301 549 via one-shot seed-wcag22.ts script). - Chunk 2 (~1,150 lines, Tasks 10-20): three AA blocker fixes — contrast audit script + token bumps (B.3), system-pref CSS (B.5), bcp47Of helpers + works.json script field + variant page lang/dir emission (B.1), RTL CSS overrides (B.2), SearchDialog combobox + native clear (B.4). - Chunk 3 (~780 lines, Tasks 21-25): VPAT 2.5 INT generator + EN 301 549 Annex F generator + matrix TS module generator. HTML-only output; PDF deferred to V2. - Chunk 4 (~770 lines, Tasks 26-33b): three-platform CI matrix (Linux static + synthetic Playwright + macOS VoiceOver via Guidepup + Windows NVDA via Guidepup), 8 journey specs, commit-results bot, and the prepare-a11y-artifacts mirror that makes docs/accessibility/ servable by Astro. - Chunk 5 (~840 lines, Tasks 34-42): /accessibility page (10 sections), 5 components, filesystem reader for test-runs, footer link wiring, conformance.yaml evidence for 1.3.1 / 2.4.1 / 2.4.6 / 2.4.7. Three open questions (Q1 auto-commit strategy, Q8 download-artifact v4 behavior, Q9 lines-vs-anchor evidence refs) resolved before any code lands. Plan passed three reviewer rounds: Chunk 1 (re-reviewed for WCAG count fix + Zod schema fix), Chunk 2 (re-reviewed for contrast-value correctness + concrete diff anchors), parallel review of Chunks 3-5 (fixed broken Playwright PDF spawn, espeak cleanup, local-artifacts gitignore, critical Astro artifact-serving mirror). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

… 549

vercel · 2026-05-14T15:06:44Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
falsafa-site	Ready	Preview, Comment	May 14, 2026 4:37pm

The corpus already carries script + language fields on every variant (in docs/accessibility/specs the plan assumed works.json drove this, but the real source-of-truth is corpus/works/*/chapters/*/meta.json). Values are long-form ("arabic", "Urdu") rather than ISO 639/15924. Extending bcp47Of() with two normalization maps lets the variant page emit valid BCP-47 from corpus data with no schema migration. Includes the "other" script fallback used by Bang-e-Dara's 100 Urdu chapters — language alone (ur) still carries correct RTL direction.

…1.2)

…age)

…theme)

…er + NVDA)

…to-loaded

adoistic and others added 11 commits May 14, 2026 19:14

chore: ignore .superpowers/ brainstorm workspaces

d807e37

feat(a11y-tools): package skeleton + CLI dispatcher

e30745d

chore(a11y): add a11y:* npm scripts

1038e72

feat(a11y-tools): conformance YAML schema + validation

5a12bb5

feat(a11y-tools): YAML parser with zod validation

fcbad84

feat(a11y-tools): verifier supports lines + anchor evidence

50b041f

feat(a11y): seed conformance.yaml with 86 WCAG 2.2 SCs + 508 + EN 301…

2a11d59

… 549

docs(a11y): README + initial JAWS log seed

5438831

chore(a11y): bun.lock for a11y-tools deps (yaml, zod)

7fdf982

vercel Bot deployed to Preview May 14, 2026 15:09 View deployment

adoistic added 10 commits May 14, 2026 20:43

feat(a11y): contrast token audit script (regression gate)

e764cbe

fix(a11y): bump --rule and --accent-soft contrast to WCAG 1.4.11

9685c66

feat(a11y): honor prefers-color-scheme, prefers-contrast, forced-colors

107085d

feat(a11y): bcp47Of() + isRtl() helpers for lang attribute emission

dd219aa

feat(a11y): emit lang + dir on chapter variant pages (WCAG 3.1.1 + 3.…

b22e67e

…1.2)

feat(a11y): wrap foreign terms on /about with lang attribute

32e4db3

feat(a11y): RTL drop-cap + source-citation alignment for Urdu variants

17903ad

fix(a11y): restore native search clear button for keyboard users

1be677c

feat(a11y): SearchDialog combobox pattern (WCAG 4.1.3 + 2.1.1)

2334870

adoistic changed the title ~~feat(a11y): WCAG 2.2 AA infrastructure — Chunk 1 (bootstrap)~~ feat(a11y): WCAG 2.2 AA — Chunks 1+2 (infrastructure + AA blocker fixes) May 14, 2026

vercel Bot deployed to Preview May 14, 2026 15:33 View deployment

adoistic added 4 commits May 14, 2026 21:05

feat(a11y-tools): generator CLI dispatcher

af868d1

feat(a11y-tools): VPAT 2.5 INT generator + v1.0 artifact

ba7e383

feat(a11y-tools): EN 301 549 Annex F generator + statement v1.0

f9dfb48

feat(a11y-tools): matrix TS module generator (drives /accessibility p…

8611d2c

…age)

adoistic changed the title ~~feat(a11y): WCAG 2.2 AA — Chunks 1+2 (infrastructure + AA blocker fixes)~~ feat(a11y): WCAG 2.2 AA — Chunks 1-3 (infra + AA fixes + generators) May 14, 2026

vercel Bot deployed to Preview May 14, 2026 15:41 View deployment

adoistic added 8 commits May 14, 2026 21:20

feat(a11y): pa11y-ci + Guidepup deps + Playwright config

69858cc

feat(a11y): synthetic-transcript helper (AT-tree dumper)

6c9dce8

feat(a11y): Guidepup helpers (VoiceOver + NVDA shared lifecycle)

73e8bac

test(a11y): homepage journey (reference for other journeys)

c505f2a

test(a11y): journeys 2-8 (search, catalog, reader x2, variant, eval, …

1b03100

…theme)

feat(a11y): pa11y config + audio synthesis + merge-artifacts helpers

bed0533

ci(a11y): three-platform workflow (axe + pa11y + Playwright + VoiceOv…

d97d1a6

…er + NVDA)

test: scope bun test roots so Playwright .spec.ts journeys are not au…

3d1f1d3

…to-loaded

adoistic changed the title ~~feat(a11y): WCAG 2.2 AA — Chunks 1-3 (infra + AA fixes + generators)~~ feat(a11y): WCAG 2.2 AA — Chunks 1-4 (infra + AA fixes + generators + CI) May 14, 2026

vercel Bot deployed to Preview May 14, 2026 16:01 View deployment

adoistic added 9 commits May 14, 2026 21:58

feat(a11y): mirror docs/accessibility/ into Astro public dir for serving

6883455

feat(a11y-page): ConformanceMatrix component (4 principle groups)

0755235

feat(a11y-page): AccessibilityExceptions component

0dfb076

feat(a11y-page): AuditYourself component

eefdb4e

feat(a11y-page): test-runs table + filesystem reader

316a1af

feat(a11y-page): JawsLog component (manual verification log renderer)

94f8ec6

feat(a11y): /accessibility page — 10-section audit page

752e533

feat(a11y): footer link to /accessibility on every page

9156860

feat(a11y): evidence for 1.3.1, 2.4.1, 2.4.6, 2.4.7

30fa6b1

adoistic changed the title ~~feat(a11y): WCAG 2.2 AA — Chunks 1-4 (infra + AA fixes + generators + CI)~~ feat(a11y): WCAG 2.2 AA — V1 complete (5 chunks: infra + AA fixes + generators + CI + page) May 14, 2026

vercel Bot deployed to Preview May 14, 2026 16:37 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(a11y): WCAG 2.2 AA — V1 complete (5 chunks: infra + AA fixes + generators + CI + page)#1

feat(a11y): WCAG 2.2 AA — V1 complete (5 chunks: infra + AA fixes + generators + CI + page)#1
adoistic wants to merge 43 commits into
mainfrom
claude/elegant-sammet-f9bc5b

adoistic commented May 14, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 14, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

adoistic commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What lands

Chunk 1 — Bootstrap

Chunk 2 — AA blocker fixes

Chunk 3 — Generators

Chunk 4 — CI workflow + 8 journeys

Chunk 5 — /accessibility page + footer link

Evidence in conformance.yaml

Plan deviations (flagged)

Verification

CI first-run expectations

Out of V1

Test plan

Uh oh!

vercel Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

adoistic commented May 14, 2026 •

edited

Loading

Chunk 5 — `/accessibility` page + footer link

vercel Bot commented May 14, 2026 •

edited

Loading