Sem A11Y.md
<div onClick={() => navigate('/checkout')}>
Finish purchase
</div>Com A11Y.md
<button onClick={() => navigate('/checkout')}>
Finish purchase
</button>A11Y.md — Apoiado pelo Claude for Open Source Program, da Anthropic.
Acessibilidade antes de qualquer prompt
Um arquivo que ensina a IA que você usa — Cursor, Claude, Copilot — a construir interfaces acessíveis desde a primeira linha, seguindo o padrão internacional WCAG 2.2. Nada para instalar: uma frase no lugar certo e pronto.
[Focado no humano][Pronto para IA][Certificável]
Ao desenvolver o frontend, siga estritamente as regras de acessibilidade definidas no A11Y.md: https://github.com/fecarrico/A11Y.md/blob/main/docs/pt-BR/A11Y.md
Não programa? Cole o link do GitHub no Lovable, no v0 ou no Figma Make — funciona igual.
- Claude for Open Source
- Smashing Magazine
- WCAG 2.2 AA
- Licença MIT
O PROBLEMA
Estamos escalando exclusão mais rápido do que nunca
De um lado, leis e certificações — necessárias, mas lentas. Do outro, a IA criando telas em velocidade absurda. Os números mostram quem está ganhando:
95,9%dos sites da web têm falhas de acessibilidade detectáveis — e o número piorou pela primeira vez em seis anos.
~30%das barreiras reais é o que os testes automáticos conseguem encontrar — até o governo dos EUA admitiu ter confiado demais em correções por IA.
Inacessível por padrãoé como nascem as interfaces geradas por IA.
NA PRÁTICA
O que muda no código
O erro mais comum em telas geradas por IA: um botão que parece botão, mas não é. Para quem navega por teclado ou usa leitor de tela, ele simplesmente não existe.
Os exemplos aqui são em React, mas a regra vale para qualquer tecnologia: a IA adapta o padrão para Vue, Angular, Svelte ou Solid — e, em aplicativos nativos (iOS, Android, React Native, Flutter), traduz a ideia em vez de copiar o código. A parte web já está madura; a nativa está em construção.
A PROVA
Esta página segue o próprio padrão
Esta página foi construída seguindo o próprio A11Y.md, no perfil mais exigente (Shield). Passou em todos os testes automáticos: zero violações, navegação completa por teclado, zoom de 200% sem quebrar nada. Mas máquina não fecha o ciclo: a IA erra, e o próprio A11Y.md exige que uma pessoa valide com leitor de tela antes de declarar a página aprovada. O relatório mostra o que passou, o que falta e por quê.
QUICK START
Menos de dois minutos
Ferramentas de IA leem arquivos como CLAUDE.md e AGENTS.md automaticamente. Acessibilidade ainda não tem um arquivo canônico assim — a sua regra cria essa camada. E você não copia nada: a IA lê o A11Y.md direto da fonte, sempre na versão mais atual.
- 01
Aponte a IA para o padrão
Adicione uma pequena regra às instruções da ferramenta de IA que você usa para criar — Cursor, Claude Code, Copilot ou similar.
- 02
Defina o perfil
Escolha o nível de exigência: Shield (o máximo), Standard (o padrão) ou Launchpad (para protótipos). Se você não escolher, a IA pergunta antes de começar.
- 03
Use como revisor
Peça para a IA revisar o que já existe — código pronto ou telas do Figma — usando o A11Y.md como régua.
.cursorrules
> Adicione ao arquivo de regras do seu agente:"Ao desenvolver o frontend, siga estritamenteas regras de acessibilidade definidas no A11Y.md:https://github.com/fecarrico/A11Y.md/blob/main/docs/pt-BR/A11Y.md"✔ Contexto de acessibilidade carregado✔ WCAG 2.2 AA — perfil Standard ativo✔ Guias de referência carregados sob demandaSeu ambiente agora sabe que acessibilidade é requisito básico.Não programa? Cole o link do GitHub no Lovable, no v0 ou no Figma Make — funciona igual.
COMO FUNCIONA
O que o A11Y.md faz quando é chamado
O arquivo principal é leve de propósito: fica sempre presente na memória da IA, e o material de apoio só entra quando é necessário.
A11Y.md é carregado
É um site ou um aplicativo? Que componente vamos construir?
A IA responde essas perguntas antes de tudo e busca só o guia certo para aquele caso. Se for um aplicativo, ela adapta a orientação para a plataforma em vez de copiar soluções feitas para a web
references/Gera a interface
O projeto já tem esse componente? Essa escolha já foi feita antes?
Em vez de criar tudo do zero, a IA reaproveita o que o projeto já tem. E cada decisão tomada fica anotada, para que os próximos componentes sigam o mesmo padrão
A11Y-DECISIONS.mdFase de validação
Passa nos critérios do nível escolhido?
Cada exigência é conferida contra a norma internacional, critério por critério. Quando o A11Y.md pede mais do que a norma, isso aparece identificado como regra da casa
WCAG 2.2Gera o relatório
Encontrou algum problema? Falta teste humano?
O que não foi resolvido vira um registro formal de pendência. E o que só uma pessoa pode validar — como o teste com leitor de tela — fica apontado no relatório: a IA é proibida de fingir esse teste
EXCEPTIONS.md
REPERCUSSÃO
O que estão dizendo
“Felipe A. Carriço criou o A11Y.md, um sistema de contexto para construir software acessível por padrão.”
“A IA não conserta sistemas inacessíveis. Ela escala o que encontra.”
“O produto é isso: ligar a acessibilidade ao processo de construção de modo que ela mude o que é gerado.”
Bora construir juntos?
O A11Y.md não é apenas um arquivo; é um ponto de partida. É open source porque acessibilidade não pede permissão, pede colaboração.
Adote no seu projeto
Uma frase no seu ambiente e o padrão passa a valer dali em diante.
Guia de integração (abre em nova aba)Contribua
Melhore os guias, aponte erros — ou mande um exemplo que você resolveu.
Abrir a Wiki (abre em nova aba)Mande seus achados
Testou o método num projeto seu? Conta o que funcionou — e o que não.
Abrir uma issue (abre em nova aba)
“Acessibilidade não pode ser um selo no final do processo. Precisa ser a restrição no começo.”