A11y.md – A context system for building accessible software A11Y.md, created by Felipe Arriada Carrio, is a persistent context system and accessibility validation protocol that integrates with AI coding agents such as Cursor, Claude, and Copilot to enforce WCAG 2.2 AA and ADA compliance from the first line of generated code. The system includes an 11-rule AI behavioral contract, modular compliance profiles (Shield AAA, Standard AA, Launchpad A), and lazy context loading of 21 WAI-ARIA APG reference guides, and can be adopted by adding a single rule to an agent's configuration file. 🇧🇷 Read in Portuguese: ./README.pt-BR.md The Persistent Context System for Accessibility 📖 Read the Official Wiki https://github.com/fecarrico/A11Y.md/wiki | 🌐 Official Website https://fecarrico.github.io/a11ymd/ | 📝 Read the Manifesto Substack https://open.substack.com/pub/felipearriadacarrio340730/p/a11ymd-accessibility-before-any-prompt A11Y.md is not a guideline.It is an accessibility validation protocol and apersistent context architecturefor developing accessible software with AI. It is designed to integrate with AI agent systems Cursor, Claude, Copilot to ensure certifiable compliance from genesis. We treat .gitignore , eslint , and CLAUDE.md as canonical truths in our repositories. But why isn't accessibility canonical? A11Y.md translates accessibility rules into a portable governance layer: a platform-agnostic normative core POUR, compliance profiles, severity, governance with mature web references and a native translation layer iOS, Android, React Native, Flutter . Instead of generic coding advice, it forces any coding agent to strictly adhere to WCAG 2.2 AA and ADA standards from the very first line of generated UI code. - 🧠 11-Rule AI Behavioral Contract: A strict set of deterministic constraints that force the AI to act as a semantic translator Framework Adaptation, Platform Awareness , reuse the project's existing components instead of recreating them Component Reuse + Decision Memory , and stop generating dangerous anti-patterns like "clickable divs" . - 🛡️ Modular Compliance Profiles: Support for Shield AAA , Standard AA , and Launchpad A — each separating what WCAG actually requires cited by Success Criterion from this standard's stricter House Rules . The Launchpad profile allows startups to build rapid MVPs by relaxing visual constraints without ever sacrificing critical semantic structure. - 📚 Lazy Context Loading: 21 reference guides WAI-ARIA APG that act as an actionable database. The AI is programmed to load only the guides it needs on-demand, saving tokens and maintaining sharp focus. Reading about accessibility is the first step, injecting it into your code is the real goal. Do this right now in your project: - Point your AI to the Standard: Add one rule to your agent's configuration file .cursorrules , CLAUDE.md , AGENTS.md , 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 https://github.com/fecarrico/A11Y.md/blob/main/docs/en/A11Y.md "That's it — no files copied. The AI reads the core file and lazy-loads only the reference guides it needs, always up to date. Prefer Portuguese? Point to docs/pt-BR/A11Y.md instead. - Prefer an offline or pinned copy? Copy docs/en/A11Y.md into your repository root, docs/ , anywhere — optionally with the references/ and templates/ folders — and point the rule at the local path. If you copy only the core file, the AI falls back to this repository's guides via their upstream URLs. - Set the Profile: The AI will proactively ask you which Compliance Profile Shield, Standard, or Launchpad to use if you don't specify one. 👉 Read the full Setup and Integration guide on our Wiki. https://github.com/fecarrico/A11Y.md/wiki/Setup-and-Integration The complete architecture, protocols, and practical examples are thoroughly documented in our GitHub Wiki. Inside, you will find: The Command Center: How the core A11Y.md file works. Anti-patterns & Protocol: Real-world examples of AI hallucinations being fixed. Reference Library: The taxonomy of the 21 engineering guides. Evidence & Research: The field data the standard responds to — published benchmarks and studies, with sources. Governance & Compliance: Preparing for VPATs and formal audits. The difference between randomly generated code and code guided by A11Y.md : ❌ Without A11y Context: - AI generating