Without A11Y.md
<div onClick={() => navigate('/checkout')}>
Finish purchase
</div>With A11Y.md
<button onClick={() => navigate('/checkout')}>
Finish purchase
</button>A11Y.md — Backed by Anthropic's Claude for Open Source Program.
Accessibility before any prompt
A file that teaches the AI you use — Cursor, Claude, Copilot — to build accessible interfaces from the very first line, following the international WCAG 2.2 standard. Nothing to install: one sentence in the right place and you're set.
[Human-centric][AI-ready][Certifiable]
When developing the frontend, follow strictly the accessibility rules in the file https://raw.githubusercontent.com/fecarrico/A11Y.md/main/docs/en/A11Y.md
Don't code? Paste the GitHub link into Lovable, v0 or Figma Make — it works the same.
- Claude for Open Source
- Smashing Magazine
- WCAG 2.2 AA
- MIT License
THE PROBLEM
We are scaling exclusion faster than ever
On one side, laws and certifications — necessary, but slow. On the other, AI creating screens at absurd speed. The numbers show who's winning:
95.9%of websites have detectable accessibility failures — and the number got worse for the first time in six years.
~30%of real barriers is all automated tests can find — even the US government admitted it trusted AI-powered fixes too much.
Inaccessible by defaultis how AI-generated interfaces are born.
10 of 10of A11Y.md journeys documented their own process unprompted — zero without it.
IN PRACTICE
What changes in the code
The most common mistake in AI-generated screens: a button that looks like a button, but isn't one. For anyone navigating by keyboard or using a screen reader, it simply doesn't exist.
The examples here are in React, but the rule holds for any technology: the AI adapts the pattern to Vue, Angular, Svelte or Solid — and on native apps (iOS, Android, React Native, Flutter) it translates the idea instead of copying the code. The web side is mature; native is under construction.
THE PROOF
This page follows its own standard
This page was built following A11Y.md itself, under its most demanding profile (Shield). It passed every automated test: zero violations, full keyboard navigation, 200% zoom without breaking anything. But machines don't close the loop: AI gets things wrong, and A11Y.md itself requires a person to validate with a screen reader before the page can be declared approved. The report shows what passed, what's missing, and why.
QUICK START
Under two minutes
AI tools read files like CLAUDE.md and AGENTS.md automatically. Accessibility doesn't have a canonical file like that yet — your rule creates that layer. And you don't copy anything: the AI reads A11Y.md straight from the source, always the latest version.
- 01
Point your AI to the standard
Add one small rule to the instructions of the AI tool you create with — Cursor, Claude Code, Copilot or similar.
- 02
Set the profile
Pick how demanding it should be: Shield (the maximum), Standard (the default) or Launchpad (for prototypes). If you don't pick one, the AI asks before it starts.
- 03
Use it as a reviewer
Ask the AI to review what already exists — finished code or Figma screens — using A11Y.md as the yardstick.
.cursorrules
> Add to your agent's rules file:"When developing the frontend, follow strictlythe accessibility rules in the filehttps://raw.githubusercontent.com/fecarrico/A11Y.md/main/docs/en/A11Y.md"✔ Accessibility context loaded✔ WCAG 2.2 AA — Standard profile active✔ Reference guides loaded only when neededYour environment now knows accessibility is a baseline requirement.A ready-made request for designers, QA and product
A11Y.md works for people who don't write code. Copy the request for your role and paste it into the AI you already use.
Designer
Paste the standard's link into Lovable, v0 or Figma Make and the AI designs inside the rules from the start.
Paste into your AI
Before proposing this component or screen, follow the accessibility rules in the file https://raw.githubusercontent.com/fecarrico/A11Y.md/main/docs/en/A11Y.md. Say which compliance profile you are using and what you could not verify.
QA and testing
Every guide in the standard says what must happen by keyboard and what the screen reader must announce. That is a test script.
Paste into your AI
Read the guide for this component in https://raw.githubusercontent.com/fecarrico/A11Y.md/main/docs/en/A11Y.md and list, scenario by scenario, what must happen by keyboard and what the screen reader must announce, on desktop and on a phone. Separate what you verified in the code from what needs a person.
Product
Accessibility acceptance criteria come from the standard, not from the memory of whoever writes the task.
Paste into your AI
Read A11Y.md at https://raw.githubusercontent.com/fecarrico/A11Y.md/main/docs/en/A11Y.md. Based on it, write the accessibility acceptance criteria for this delivery: what is mandatory under the Standard profile, what becomes a recorded exception, and who must validate with a screen reader.
HOW IT WORKS
What A11Y.md does when it's called
The main file is light on purpose: it stays in the AI's memory at all times, and the supporting material only comes in when it's needed.
A11Y.md is loaded
Is it a website or an app? Which component are we building?
The AI answers these questions first and fetches only the right guide for that case. If it's an app, it adapts the guidance to the platform instead of copying solutions made for the web
references/Generates the UI
Does the project already have this component? Was this choice made before?
Instead of building everything from scratch, the AI reuses what the project already has. And every decision gets written down, so the next components follow the same pattern
A11Y-DECISIONS.mdValidation phase
Does it pass the chosen level's criteria?
Every requirement is checked against the international standard, criterion by criterion. When A11Y.md asks for more than the standard does, that shows up labeled as a house rule
WCAG 2.2Generates the report
Found a problem? Missing a human test?
Whatever wasn't solved becomes a formal pending record. And what only a person can validate — like the screen reader test — gets flagged in the report: the AI is forbidden from faking that test
EXCEPTIONS.md
IN THE WILD
What people are saying
“Felipe A. Carriço created A11Y.md, a context system for building accessible software by default.”
Institutional endorsement
OZeWAI
The Australian organisation for web accessibility and inclusion
OZeWAI listed A11Y.md in its Weekly Reading List of 27 July 2026.
Weekly Reading List · 27 July 2026 (opens in a new tab)“AI doesn't fix inaccessible systems. It scales what it finds.”
“That is the product here: wiring accessibility into the build process so it changes what gets generated.”
Also on the radar of Frontend Focus (opens in a new tab)en<able> (opens in a new tab)Jury Vetrov (opens in a new tab)Design Fragments (opens in a new tab)Frontend Dogma (opens in a new tab)Muzli (opens in a new tab)Mike Gifford (opens in a new tab)Branon Eusebio (opens in a new tab)Diyor Khakimov (opens in a new tab)
Sources
What feeds the standard
Every rule in A11Y.md comes from a document that exists outside it. This is the list of what was consulted and used to build version 2.4.0. It holds 35 documents, with country and version, for anyone who wants to check at the source.
Technical standards and guidelines
Legislation
| Document | Country | Version |
|---|---|---|
| Lei Brasileira de Inclusão da Pessoa com Deficiência (Lei 13.146/2015) (opens in a new tab) | Brazil | 2015 |
| Lei 10.436/2002 (reconhecimento da Libras) (opens in a new tab) | Brazil | 2002 |
| Decreto 5.626/2005 (regulamentação da Libras) (opens in a new tab) | Brazil | 2005 |
| European Accessibility Act (Directive (EU) 2019/882) (opens in a new tab) | European Union | 2019 · in force since 2025 |
| General Data Protection Regulation (Regulation (EU) 2016/679) (opens in a new tab) | European Union | 2016 |
| Americans with Disabilities Act (ADA) (opens in a new tab) | United States | 1990 · 2024 web rule |
| Section 508 of the Rehabilitation Act (opens in a new tab) | United States | 2017 revision |
Evaluation and conformance
| Document | Country | Version |
|---|---|---|
| Website Accessibility Conformance Evaluation Methodology (WCAG-EM) 1.0 (opens in a new tab) | International (W3C) | 1.0 · 2014 |
| WCAG-EM Report Tool (opens in a new tab) | International (W3C) | living document |
| Developing an Accessibility Statement (opens in a new tab) | International (W3C) | living document |
| Voluntary Product Accessibility Template (VPAT) (opens in a new tab) | United States (ITI) | 2.5Rev · 2025 |
| axe-core (opens in a new tab) | United States (Deque) | 4.13.0 · pinned in the benchmark |
| WAVE Web Accessibility Evaluation Tool (opens in a new tab) | United States (WebAIM) | living document |
| AccessMonitor (opens in a new tab) | Portugal (AMA) | living document |
| Lighthouse (opens in a new tab) | United States (Google) | living document |
Platforms, libraries and supporting documents
| Document | Country | Version |
|---|---|---|
| Apple Human Interface Guidelines (opens in a new tab) | United States (Apple) | living document |
| Material Design 3 (opens in a new tab) | United States (Google) | 3 |
| Apple Developer Documentation: UIKit and SwiftUI accessibility (opens in a new tab) | United States (Apple) | living document |
| Android Developers: accessibility semantics in Compose (opens in a new tab) | United States (Google) | living document |
| React Native documentation: Accessibility (opens in a new tab) | United States (Meta) | living document |
| Flutter API documentation: Semantics (opens in a new tab) | United States (Google) | living document |
| eBay MIND Patterns (opens in a new tab) | United States (eBay) | living document |
| Hand Talk: documentação do plugin de tradução para Libras (opens in a new tab) | Brazil | living document |
| VLibras: suíte de tradução para Libras do governo federal (opens in a new tab) | Brazil | living document |
| Nota de Repúdio 02/2025 à utilização de software de tradução automática (Febrapils) (opens in a new tab) | Brazil | May 2025 |
History
Every rule has a story
This standard doesn't evolve by roadmap; it evolves by response. A field post-mortem became a release, an independent test became an anti-pattern, a community question became a rule. The timeline shows that whole conversation — from the first star to today.
Explore the project's historyWant to build this together?
A11Y.md is not just a file; it's a starting point. It's open source because accessibility doesn't ask for permission, it asks for collaboration.
Adopt it in your project
One sentence in your environment and the standard applies from then on.
Integration guide (opens in a new tab)Contribute
Improve the guides, point out mistakes — or send an example you solved.
Open the Wiki (opens in a new tab)Send your findings
Tried the method on a project of yours? Tell us what worked — and what didn't.
Open an issue (opens in a new tab)
“Accessibility cannot be a badge at the end of the process. It needs to be the constraint at the beginning.”
Design edition
Make your screens and components accessible before the first pixel with DA11Y.md
The Figma agent reads DA11Y.md by link and applies the same rules and the same numbers as A11Y.md while the screen is being drawn. It is also in the Figma Community, as a skill.
Explore DA11Y.md (opens in a new tab)In the background, DA11Y.md's hero drawn in ASCII, with the dally.md logotype.