# A11Y.md

> A persistent context system that teaches AI coding assistants to build accessible interfaces by default, following WCAG 2.2 standards from the first line of code.

A11Y.md is an open-source accessibility context system created by Felipe A. Carriço that integrates with AI coding agents — Cursor, Claude Code, GitHub Copilot, and similar tools — to enforce WCAG 2.2 AA compliance from the very first line of generated UI code. The project was selected for Anthropic's Claude for Open Source program in July 2026 and has been featured in Smashing Magazine's newsletter. It requires no installation: a single sentence added to an AI agent's rules file points the tool to the A11Y.md standard, and the AI reads and applies it automatically.

## What It Is

A11Y.md is a **persistent context architecture** — a governance layer for accessibility that works the same way `.gitignore` or `eslint` configs work for code quality. Rather than a static guideline document, it is a structured set of deterministic behavioral rules that force AI coding agents to act as semantic translators, reuse existing project components, and avoid generating inaccessible anti-patterns like clickable `<div>` elements instead of native `<button>` elements. The core file stays lightweight in the AI's context window at all times, while 21 modular reference guides (based on WAI-ARIA APG) are lazy-loaded only when needed for a specific component or platform.

## How the Compliance Profiles Work

A11Y.md ships with three tiered compliance profiles that teams can select based on their project stage:

- **Shield** — the most demanding profile, targeting WCAG 2.2 AAA plus additional house rules
- **Standard** — the default, targeting WCAG 2.2 AA and ADA/EAA compliance
- **Launchpad** — designed for rapid MVP prototyping; relaxes visual constraints while preserving critical semantic structure

If no profile is specified, the AI proactively asks before generating any UI. Each profile maps every rule to a specific WCAG 2.2 Success Criterion, enabling direct traceability for formal audits and VPATs.

## The AI Behavioral Contract

The core of A11Y.md is an 11-rule behavioral contract that constrains how AI agents generate frontend code:

- **Framework Adaptation** — the AI translates accessibility patterns to the target framework (React, Vue, Angular, Svelte, Solid) rather than copying web solutions verbatim
- **Platform Awareness** — for native apps (iOS, Android, React Native, Flutter), the AI adapts guidance instead of porting web patterns
- **Component Reuse + Decision Memory** — the AI checks for existing project components before generating new ones, and writes decisions to `A11Y-DECISIONS.md` so subsequent components follow the same pattern
- **Anti-pattern blocking** — the AI is forbidden from generating "clickable divs" and other known inaccessible constructs
- **Human validation gate** — the AI is explicitly prohibited from faking screen reader test results; unresolved issues are logged to `EXCEPTIONS.md`

## Setup Path

Integration takes under two minutes. Developers add one rule to their agent's configuration file (`.cursorrules`, `CLAUDE.md`, `AGENTS.md`, or `copilot-instructions.md`):

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

No files need to be copied into the project. The AI reads A11Y.md directly from the source repository, always pulling the latest version. Teams that prefer an offline or pinned copy can copy the core file and optional reference folders into their own repository and point the rule at the local path. No-code users can paste the GitHub link directly into tools like Lovable, v0, or Figma Make.

## Update: v1.1.0 — Normative Precision, Platform Awareness & Component Reuse

Version 1.1.0 was published on July 20, 2026, and represents the first major release after the project's April 2026 launch. The release focused on normative precision in rule language, the introduction of the Platform Awareness behavioral rule for native app development, and the Component Reuse + Decision Memory system. The repository shows 287 stars and 12 forks as of the latest data, with active maintenance through July 2026.

## Features
- WCAG 2.2 AA/AAA compliance enforcement for AI-generated code
- 11-rule AI behavioral contract for deterministic accessibility
- Three compliance profiles: Shield (AAA), Standard (AA), Launchpad (A)
- Lazy-loading of 21 WAI-ARIA APG reference guides
- Framework adaptation for React, Vue, Angular, Svelte, Solid
- Native platform translation for iOS, Android, React Native, Flutter
- Component reuse and decision memory via A11Y-DECISIONS.md
- Anti-pattern blocking (e.g., clickable divs)
- Human validation gate with EXCEPTIONS.md logging
- Zero-install setup via single rule in agent config file
- Offline/pinned copy support
- Portuguese language support (pt-BR)
- ADA and EAA compliance mapping
- VPAT and formal audit traceability

## Integrations
Cursor, Claude Code, GitHub Copilot, Lovable, v0, Figma Make, React, Vue, Angular, Svelte, Solid, React Native, Flutter, iOS, Android

## Platforms
ANDROID, IOS, WEB, API, CLI

## Pricing
Open Source

## Version
v1.1.0

## Links
- Website: https://fecarrico.github.io/a11ymd/
- Documentation: https://github.com/fecarrico/A11Y.md/wiki
- Repository: https://github.com/fecarrico/A11Y.md
- EveryDev.ai: https://www.everydev.ai/tools/a11y-md