Accessibility Review

Accessibility review (orchestrator)

You are the orchestrator. Plan and delegate; do not bulk-review the repo yourself. Follow skill agent-orchestration (orchestrator plans; workers implement; readonly verifier validates).

Compliance floor: WCAG 2.2 AA everywhere, mapped to EN 301 549 and aligned with BITV 2.0 expectations. Selected AAA-inspired enhancements on critical administrative journeys only — not full-site AAA unless the client contract explicitly requires it.

Never claim legal compliance, BITV certification, or EN 301 549 conformance. Produce evidence-backed findings, fixes, and residual-risk notes only.

References: legal-context-germany.md | stack-rules.md | review-output-format.md | client-clarification.md

Background research (not workflow): docs/research-aa-vs-aaa-report.md | docs/research-ai-agent-landscape.md | repo evaluations in references/evaluations/

Hard rules (encode in every worker prompt)

Every issue must set manual_verification_required (usually true). AI review is not final conformance proof.

Before starting

If the client requirement mentions "AAA" or procurement conformance, run client-clarification.md first. Record answers in the review plan.

Orchestrated workflow

0. Clarify (if needed)
1. Inventory        → explore subagent
2. Classify risk    → orchestrator
3. Chunk            → orchestrator
4. Per chunk:
     a. Review/fix worker
     b. Readonly code-review verifier
     c. finish-work (bun run check + commit)
5. Runtime verify   → browser / Playwright / axe where possible
6. Evidence pack    → issue register + coverage matrix + residual risks

1. Inventory the app

Delegate to an explore subagent. Scan routes, layouts, shared primitives, and integrations. Record:

• Routes and route families
• Forms (TanStack Form), dialogs, uploads, auth flows
• Maps (React Map GL), PDF/download outputs, emails if in scope
• Shared components: field wrappers, error summaries, modals, route shell

Output: inventory table with route path, workflow type, stack surfaces (form / map / PDF / upload / auth).

2. Classify routes by risk

Administrative form, auth, upload, review-submit, map, and output = high risk minimum.

3. Split into meaningful chunks

Group by route family or feature area (e.g. auth, antrag/wohngeld, map-picker). One chunk = one worker session (~5–15 routes or one complex flow). Prioritize critical/high risk first. Parallelize independent chunks; serialize when shared primitives change.

4. Per chunk: review → verify → finish-work

For each chunk:

1. Review/fix worker — spawn implementer or dedicated a11y worker. Load stack-rules.md and review-output-format.md. Apply fixes in scope; emit YAML findings per route.
2. Readonly verifier — spawn code-review subagent (readonly: true). Skeptic-check: evidence present, fixes correct, map-only paths flagged critical, no certification claims, every issue has manual_verification_required.
3. finish-work — run skill finish-work on that chunk: bun run check, fix failures, commit with user-facing message. One commit per completed chunk.

Workers must not skip verifier or finish-work unless the user explicitly asked for review-only.

5. Runtime verification

Where possible, verify with browser automation (skill playwright-skill, agent-browser MCP, axe-core):

• Keyboard-only path through the flow
• Focus order after navigation, dialog open/close, submit errors
• SPA route title and focus reset
• Map flow via non-map equivalent path
• Error summary announcement

When AI or automation cannot confirm behavior (screen reader, PDF readability, contrast in all themes), set manual_verification_required: true and add items to the manual test checklist in review-output-format.md.

6. Evidence pack (final deliverables)

Produce:

1. Issue register — YAML per route using schema in review-output-format.md
2. Route coverage matrix — every inventoried route: reviewed (yes/no), risk level, issue count by severity, runtime-tested (yes/no/manual)
3. Residual-risk notes — what remains unverified, map/PDF risks, client clarification gaps, recommended human audit (BIK/BITV-style, usability tests)

Include executive summary: quick wins, design-system fixes, manual test checklist. Do not state legal compliance.

Tiered delivery model

AI usage boundaries

Good for: route/component inventory, static JSX/ARIA review, Tailwind contrast/focus review, form wiring inspection, checklist reviews, fix suggestions, Playwright/axe test generation, audit drafts.

Not for: final conformance authority, sole proof, screen-reader sign-off, user testing, or legal interpretation.

Related skills

Sources

• BITV 2.0
• BFIT — gesetzliche Verpflichtungen
• WCAG 2.2
• Understanding WCAG 2.2
• BIK BITV test