A11Y.md: accessibility context for AI-assisted development

The 2026 WebAIM Million found detectable WCAG failures on 95.9% of home pages — the first regression in six years — at the exact moment AI agents became the majority of HTML traffic. Coding agents learned from that web, so inaccessible markup is their statistical default. A11Y.md changes that default at generation time instead of auditing it afterwards: a persistent context file the agent reads before writing the first line of UI code.

How it works

Point your AI agent at one file. It stays loaded as persistent context and the agent pulls deeper guides only when the task calls for them, keeping the token cost low. Works with Cursor, Claude Code, GitHub Copilot, Gemini/Antigravity and Windsurf — the setup is a single rule in the agent's configuration file.

Key features

• 11-rule AI Behavioral Contract: deterministic constraints that stop the common failure modes — clickable divs, unlabeled inputs, ARIA soup — and add three rules most context files miss: Platform Awareness (identify the target platform before loading any reference), Component Reuse (extend what the project already has instead of generating a parallel implementation) and Decision Memory (record choices between equally conformant alternatives so twenty modals don't ship with twenty focus patterns).
• Modular compliance profiles: Shield (AAA), Standard (AA) and Launchpad (A). Every rule cites its WCAG 2.2 Success Criterion, and anything stricter than the target level is explicitly labeled a House Rule — so teams always know what the standard requires and what is this project's own ergonomic policy.
• Lazy context loading: 21 reference guides (WAI-ARIA APG-based) that the agent loads on demand, not upfront.
• Operational governance: EXCEPTIONS.md for accountable dispensations (risk owner, approver, tracking issue, expiry date), REPORT.md as a definition of done, and A11Y-DECISIONS.md as cross-turn pattern memory. Policy, dispensation and verdict in one loop, ready for VPAT and audit preparation.

Platform scope

The normative layer — Principle Zero, POUR, compliance profiles, severity model, governance — is platform-agnostic, as WCAG 2.2 is written to be. The technical references are web-first and mature. Native targets (iOS/SwiftUI, Android/Compose, React Native, Flutter) are covered by a translation guide that maps semantic intent across platforms, so the agent never transposes ARIA or CSS pixels where they don't exist.

Practical impact

Without accessibility context, agents produce <div onClick> handlers that break keyboard use, modals that trap or lose focus, and error messages screen readers never announce. With it, native elements are the default, focus is managed across SPA routing, and dynamic feedback is exposed through live regions.

Grounded in field data, and measured

Every hard rule answers something measured in the field, cited with its source on the wiki's Evidence & Research page — including the ARIA Soup anti-pattern, a response to the WebAIM finding that pages now average 133+ ARIA attributes, six times the 2019 figure, with more ARIA correlating with more detected errors. The repository also carries a pre-registered benchmark: the methodology and prompts for measuring whether A11Y.md reduces automatically detectable violations in generated UI were published before any data collection, with scope honestly limited to what automation can detect.

Documentation

Full architecture, protocols and examples live in the GitHub Wiki, with a project site and complete documentation in English and Brazilian Portuguese.

Community

A11Y.md is open source under MIT and was selected in July 2026 for Anthropic's Claude for Open Source program. Its author, Felipe A. Carriço, is a product designer who doesn't claim to be a definitive accessibility expert, but rather someone invested in the intersection of inclusion and AI — the project depends on people with deeper accessibility engineering experience to challenge and refine it. Pull requests to improve the reference guides or the behavioral contract are actively encouraged.