Two weeks ago I did something slightly terrifying: I put my own open source project inside a formal study — two preregistered, placebo-controlled experiments measuring whether A11Y.md actually changes what AI agents build. I published everything, including the parts where I didn't win.
Version 2.0 is what the numbers ordered. Not a roadmap I dreamed up — a release where every major change traces to a measured finding.
What is A11Y.md, in one paragraph
Interfaces are being generated at unprecedented speed, and they are leaving people behind even faster. A11Y.md is a context file that AI coding tools — Cursor, Claude, Copilot — read before generating interfaces, so accessibility stops being a review step and becomes a premise: core rules always loaded, component guides loaded on demand, real-world norms (WCAG 2.2, ADA, EN 301 549, ABNT NBR 17225) behind them. Built for the people the speed is leaving behind. Nothing to install: one sentence in the right place and you're set.
What the studies ordered — and v2.0 shipped
Contrast became arithmetic. Contrast failed in every uninstructed condition of the study — and it's the web's largest audit debt (WebAIM: 83.9% of home pages), the barrier low-vision and colorblind users hit first. It is also, literally, arithmetic. So v2.0 ships a deterministic contrast checker (stdlib Python, gates CI), and the standard now says: ratios are computed, never estimated — at the moment the palette is born, not at audit time.
One anti-pattern got a kill order. Nearly all remaining violations in the guided arm came from a single half-climbed ARIA pattern replicated site-wide — the kind that announces capabilities to a screen reader user and then doesn't deliver them. The new rule: native HTML first; when a composite ARIA pattern is genuinely needed, it ships complete or not at all. And the declared kill criterion: this class of error must disappear in the next benchmark round, or the rule failed.
Governance was hardened by its own evidence. With A11Y.md, agents spontaneously produced a verification report and a decision log in 10 of 10 journeys — zero of 20 without it. That pair is now named in the Definition of Done, and the report gained an interactive-states inventory (because a broken menu once survived a report no navigation ever opened).
Brazil became a first-class citizen. ABNT NBR 17225:2025 — Brazil's digital accessibility norm — is mapped into the compliance profiles. And there's a guide I couldn't find in any other checklist: how to build interfaces that work with automatic sign-language translators (Hand Talk, VLibras). Sign language is many deaf users' first language and written text their second — and an unknown acronym reaches them fingerspelled, letter by letter. The guide also draws the line the deaf community itself draws: where an avatar must give way to a human interpreter.
And it got cheaper. The studies measured a 1.4–2× token cost. An evidence-gated diet (spoiler: the fashionable compression tricks lose to measurement — "caveman" prompts saved 8.5% in paired trials, not the advertised 65%) cut ~56 KB across the corpus with zero obligations lost. Net effect: all of the above fits within +1.5% of the previous version's cost.
There's also a nice side effect worth one line: AI agents happen to operate pages through the same accessibility tree a screen reader uses, so interfaces built under this standard test dramatically better with browser agents too. A corollary, not the reason — this project is about people, and that order is written into the standard itself.
What happens next
v2.0.0 is frozen by hash and goes into round 2 of the benchmark — measured against the previous version, protocol registered before any data is collected. If any change cost quality, it won't be settled by "I think it's better." This project no longer runs on hunches.
- Try it: fecarrico.github.io/a11ymd — one sentence, and your environment treats accessibility as a premise
- The studies: full report, with open data
- Release notes: v2.0.0
Feedback, field reports and skepticism are all welcome — skepticism especially. It's what built this version.
