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 defined in A11Y.md: https://github.com/fecarrico/A11Y.md/blob/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.
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 defined in A11Y.md:https://github.com/fecarrico/A11Y.md/blob/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.Don't code? Paste the GitHub link into Lovable, v0 or Figma Make — it works the same.
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.”
“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.”
Want 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.”