Operational Templates

Operational Templates

A11Y.md provides three templates in the templates/ folder: REPORT.md, EXCEPTIONS.md, and A11Y-DECISIONS.md.

These are not documentation files for you to read. They are active process tools meant to be integrated into your development lifecycle, acting as the bridge between the AI's generated code and human validation.

1. REPORT.md (The QA Checklist)

While the AI can generate accessible code, accessibility ultimately requires human validation. You cannot automate empathy or perceptual testing with 100% accuracy.

Before merging a Pull Request (PR) for a new feature, a developer should copy the REPORT.md template into the PR description or ticket.

It forces the developer to manually verify the 5-step workflow:

• The linter passes.
• The Tab key was manually tested.
• Screen reader feedback was verified for dynamic events.
• Text resizes to 200% (SC 1.4.4) and content reflows at 320 CSS px — equivalent to 400% zoom on a 1280px viewport (SC 1.4.10) — without breaking the layout.
• The interface is still understandable in grayscale.

2. EXCEPTIONS.md (The Debt Ledger)

This is the most critical template if you are using the Launchpad (A) Profile.

When a startup is moving fast, they might decide that shipping text below the 4.5:1 contrast ratio (SC 1.4.3) on a dense dashboard is acceptable for now, because fixing it requires a design overhaul. They consciously decide to accept the technical debt.

The Rule: If you skip a WCAG Success Criterion at your target level, you MUST document it in EXCEPTIONS.md. (Relaxing a House Rule† — like dropping from the 44x44px design target to the 24x24px WCAG floor of SC 2.5.8 — is a product decision instead, recorded in A11Y-DECISIONS.md.)

Why is this powerful?

1. Traceability: It proves that the team didn't just "forget" accessibility; they made a conscious, temporary business decision.
2. Audit Defense: If a client asks for a VPAT (Accessibility Conformance Report), a populated EXCEPTIONS.md shows maturity and a roadmap for remediation.
3. The AI Context: Because EXCEPTIONS.md lives in the repository, the AI knows what technical debt exists. When you eventually command the AI to "Upgrade our project from Launchpad to Standard Profile," it can read the EXCEPTIONS.md file and know exactly which components to refactor first.

3. A11Y-DECISIONS.md (The Pattern Memory)

New in 1.1.0, this template is the AI's cross-turn memory of choices between equally conformant alternatives. Two implementations can both pass A11Y.md and axe and still diverge (different role, focus pattern, announcement wording) — twenty compliant modals, zero coherence.

The Rules: One line per decision, indexed by pattern, never by screen (e.g., "Destructive confirmation modal → alertdialog"). Only record what is not derivable from A11Y.md or the code itself, and keep it lean — tens of lines, not hundreds, since it shares the context budget with Lazy Loading.

Why is this powerful?

1. Coherence: Before generating any interactive component, the AI reads this log and reuses the recorded pattern (see Component Reuse and Decision Memory in the Behavioral Contract) instead of re-deriving it.
2. House Rule Ledger: Relaxing a House Rule† (a product decision, unlike skipping a WCAG SC) is recorded here — keeping EXCEPTIONS.md reserved for true normative debt.
3. Escalation: The Complex Component Protocol ends here — once a human validates an exotic component, the resolved pattern is recorded so future components inherit it.