{"slug": "a11y-md-a-context-system-for-building-accessible-software", "title": "A11y.md – A context system for building accessible software", "summary": "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.", "body_md": "🇧🇷 Read in Portuguese: ./README.pt-BR.md\n\n**The Persistent Context System for Accessibility**\n\n[📖 Read the Official Wiki](https://github.com/fecarrico/A11Y.md/wiki)|\n\n[🌐 Official Website](https://fecarrico.github.io/a11ymd/)|\n\n[📝 Read the Manifesto (Substack)](https://open.substack.com/pub/felipearriadacarrio340730/p/a11ymd-accessibility-before-any-prompt)\n\nA11Y.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.\n\nWe treat `.gitignore`\n\n, `eslint`\n\n, and `CLAUDE.md`\n\nas canonical truths in our repositories. But why isn't accessibility canonical? `A11Y.md`\n\ntranslates 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.\n\n- 🧠\n**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\"). - 🛡️\n**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. - 📚\n**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.\n\nReading about accessibility is the first step, injecting it into your code is the real goal. Do this **right now** in your project:\n\n-\n**Point your AI to the Standard:** Add**one rule** to your agent's configuration file (`.cursorrules`\n\n,`CLAUDE.md`\n\n,`AGENTS.md`\n\n,`copilot-instructions.md`\n\n…):*\"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\n\n`docs/pt-BR/A11Y.md`\n\ninstead.) -\n**Prefer an offline or pinned copy?** Copy`docs/en/A11Y.md`\n\ninto your repository (root,`docs/`\n\n, anywhere) — optionally with the`references/`\n\nand`templates/`\n\nfolders — 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. -\n**Set the Profile:** The AI will proactively ask you which Compliance Profile (Shield, Standard, or Launchpad) to use if you don't specify one.\n\n👉 [Read the full Setup and Integration guide on our Wiki.](https://github.com/fecarrico/A11Y.md/wiki/Setup-and-Integration)\n\nThe complete architecture, protocols, and practical examples are thoroughly documented in our GitHub Wiki.\n\nInside, you will find:\n\n**The Command Center:** How the core`A11Y.md`\n\nfile 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.\n\nThe difference between randomly generated code and code guided by `A11Y.md`\n\n:\n\n**❌ Without A11y Context:**\n\n- AI generating\n`<div onClick={...}>`\n\n(breaking keyboard interactions). - Modals impossible to close with\n`ESC`\n\n(Inverted and inaccessible Focus Trap). - Visual error messages that are not announced by Screen Readers.\n\n**✅ With Active A11y Context:**\n\n- Native\n`<button>`\n\nelements used as a strict rule. - Focus managed automatically after routing transitions in SPAs.\n- Precise\n`aria-live`\n\ninjections for immediate reading of dynamic data.\n\nOur philosophy dictates that web accessibility should never be an \"afterthought polish\", but a **technical precondition for use**. The structure rests on three pillars:\n\n- 👤\n**Human-Centric:** Strictly designed to guarantee real autonomy to users with disabilities. - 🤖\n**AI-Ready:** Deterministic guidelines specifically created to anchor the behavior of coding Agents, nipping \"invention\" (technical hallucinations) in the bud. - ⚖️\n**Certifiable:** Each guideline in`A11Y.md`\n\nis mapped to WCAG 2.2 criteria, allowing direct traceability that shields the company in formal external audits.\n\nA11Y.md is fundamentally an open-source initiative. In July 2026, the project was selected for **Anthropic's Claude for Open Source** program, which supports open-source maintainers worldwide.\n\nFelipe does not claim to be a definitive accessibility expert, but rather a curious advocate deeply invested in the intersection of inclusion and artificial intelligence.\n\nThe goal of this project is to be a living, breathing architecture. It relies on the open-source community — people far smarter and more experienced in accessibility engineering — to contribute, refine the reference library, and make this system robust enough to fundamentally change how digital solutions are created in the era of \"vibe coding\".\n\n**Pull Requests to improve the reference guides or the AI Behavioral Contract are highly encouraged!**", "url": "https://wpnews.pro/news/a11y-md-a-context-system-for-building-accessible-software", "canonical_source": "https://github.com/fecarrico/A11Y.md", "published_at": "2026-08-02 13:05:30+00:00", "updated_at": "2026-08-02 13:22:34.346672+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "ai-policy", "developer-tools"], "entities": ["Felipe Arriada Carrio", "Cursor", "Claude", "Copilot", "WCAG 2.2 AA", "ADA", "WAI-ARIA APG"], "alternates": {"html": "https://wpnews.pro/news/a11y-md-a-context-system-for-building-accessible-software", "markdown": "https://wpnews.pro/news/a11y-md-a-context-system-for-building-accessible-software.md", "text": "https://wpnews.pro/news/a11y-md-a-context-system-for-building-accessible-software.txt", "jsonld": "https://wpnews.pro/news/a11y-md-a-context-system-for-building-accessible-software.jsonld"}}