A11Y.md

A11Y.md is an open-source accessibility context system created by Felipe A. Carriço that integrates with AI coding agents — Cursor, Claude Code, GitHub Copilot, and similar tools — to enforce WCAG 2.2 AA compliance from the very first line of generated UI code. The project was selected for Anthropic's Claude for Open Source program in July 2026 and has been featured in Smashing Magazine's newsletter. It requires no installation: a single sentence added to an AI agent's rules file points the tool to the A11Y.md standard, and the AI reads and applies it automatically.

What It Is

A11Y.md is a persistent context architecture — a governance layer for accessibility that works the same way .gitignore or eslint configs work for code quality. Rather than a static guideline document, it is a structured set of deterministic behavioral rules that force AI coding agents to act as semantic translators, reuse existing project components, and avoid generating inaccessible anti-patterns like clickable <div> elements instead of native <button> elements. The core file stays lightweight in the AI's context window at all times, while 21 modular reference guides (based on WAI-ARIA APG) are lazy-loaded only when needed for a specific component or platform.

How the Compliance Profiles Work

A11Y.md ships with three tiered compliance profiles that teams can select based on their project stage:

• Shield — the most demanding profile, targeting WCAG 2.2 AAA plus additional house rules
• Standard — the default, targeting WCAG 2.2 AA and ADA/EAA compliance
• Launchpad — designed for rapid MVP prototyping; relaxes visual constraints while preserving critical semantic structure

If no profile is specified, the AI proactively asks before generating any UI. Each profile maps every rule to a specific WCAG 2.2 Success Criterion, enabling direct traceability for formal audits and VPATs.

The AI Behavioral Contract

The core of A11Y.md is an 11-rule behavioral contract that constrains how AI agents generate frontend code:

• Framework Adaptation — the AI translates accessibility patterns to the target framework (React, Vue, Angular, Svelte, Solid) rather than copying web solutions verbatim
• Platform Awareness — for native apps (iOS, Android, React Native, Flutter), the AI adapts guidance instead of porting web patterns
• Component Reuse + Decision Memory — the AI checks for existing project components before generating new ones, and writes decisions to A11Y-DECISIONS.md so subsequent components follow the same pattern
• Anti-pattern blocking — the AI is forbidden from generating "clickable divs" and other known inaccessible constructs
• Human validation gate — the AI is explicitly prohibited from faking screen reader test results; unresolved issues are logged to EXCEPTIONS.md

Setup Path

Integration takes under two minutes. Developers add one rule to their agent's configuration file (.cursorrules, CLAUDE.md, AGENTS.md, or copilot-instructions.md):

"When developing the frontend, follow strictly the accessibility rules defined in A11Y.md: https://github.com/fecarrico/A11Y.md/blob/main/docs/en/A11Y.md"

No files need to be copied into the project. The AI reads A11Y.md directly from the source repository, always pulling the latest version. Teams that prefer an offline or pinned copy can copy the core file and optional reference folders into their own repository and point the rule at the local path. No-code users can paste the GitHub link directly into tools like Lovable, v0, or Figma Make.

Update: v1.1.0 — Normative Precision, Platform Awareness & Component Reuse

Version 1.1.0 was published on July 20, 2026, and represents the first major release after the project's April 2026 launch. The release focused on normative precision in rule language, the introduction of the Platform Awareness behavioral rule for native app development, and the Component Reuse + Decision Memory system. The repository shows 287 stars and 12 forks as of the latest data, with active maintenance through July 2026.