Home

A11Y.md: Accessibility Before Any Prompt

What if accessibility wasn't something you merely validate at the end of a sprint, but something the system already knows from the start?

Welcome to the A11Y.md Wiki! This project was born from a simple realization: in the age of AI-assisted "vibe coding", interfaces are being generated at an unprecedented speed, but they are leaving people behind even faster. Accessibility is typically treated as a final checklist — a review step. By the time it reaches the reviewer, the code is already fundamentally flawed.

A11Y.md flips this paradigm. It is a persistent context architecture. Its goal is to ensure that accessibility is in the DNA of your project before the very first prompt.

The Provocation: Why isn't accessibility canonical?

Anthropic introduced CLAUDE.md as a canonical file to give AI agents persistent context on how to write code for a specific project. We treat linting configurations and code style guidelines as canonical truths that live in the root of our repositories.

A11Y.md is a provocation: Accessibility could and should be canonical too.

1. Check out the Setup and Integration page to learn how to hook A11Y.md into your AI tools (Cursor, Claude, etc).

By deliberately injecting A11Y.md into your AI agents (Cursor, Claude, Copilot, Gemini), you artificially create that canonical layer. You establish a universal governance that forces the AI to adhere to accessibility standards natively, from genesis.

The Origin & The Author

The project and its founding manifesto were created by Felipe A. Carriço — a UX Design Specialist and AI Product Builder.

As a colorblind professional, Felipe built this project with a lived understanding of how digital barriers impact users. The guidelines, especially those regarding color, contrast, and semantic redundancy, are not just theoretical WCAG copies; they are deeply informed by real-world friction and tested extensively with AI agents.

Open Source & Community

A11Y.md is fundamentally an open-source initiative. Felipe does not claim to be a definitive accessibility expert, but rather a curious advocate deeply invested in the intersection of inclusion and artificial intelligence.

The 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".

If you have ideas on how to improve the AI Behavioral Contract or the Reference Guides, your contributions and Pull Requests are deeply appreciated.

Projects that shipped with A11Y.md in the loop are collected in the Project Gallery — the first entry is live, and submissions are open.

Why use it?

1. Accessibility from Genesis: Your AI agents are conditioned to prioritize semantic HTML and ARIA patterns before they even start writing styles.
2. Deterministic Context: AI models hallucinate when instructions are vague. A11Y.md provides strict, unambiguous rules that agents can follow. (See Practical Examples).
3. Task Completion is the Metric: Accessibility here is not about chasing audit scores; it's a precondition for use. If a user cannot complete a task, the feature is broken.