Como colocar regras de acessibilidade dentro de uma skill de design do Claude?

Fala aí, beleza? O Claude gera uma tela bonita, espaçamento certinho, paleta agradável… e entrega um botão que some quando você navega pelo Tab

Não é burrice do modelo, é falta de instrução: se nada no contexto pede contraste, foco visível ou teclado, ele otimiza pelo que você pediu, que era "bonito"

É aí que entra a skill de design do Claude: em vez de repetir "lembra da acessibilidade" em todo prompt, você escreve a regra UMA vez, num arquivo, e ela passa a valer sempre que a skill dispara

Neste post eu mostro quais checagens fazem sentido virar regra escrita (com o critério e o número que tornam a regra verificável), como redigir cada uma pro Claude conseguir aplicar na geração, e o que continua dependendo de olho humano

O que você precisa antes de escrever a skill

Antes de sair digitando, vale entender a anatomia da coisa

Uma skill no Claude Code é uma pasta com um arquivo SKILL.md dentro, que pode morar em ~/.claude/skills/<nome-da-skill>/SKILL.md (pessoal), em .claude/skills/<nome-da-skill>/SKILL.md (do projeto) ou vir por plugin, segundo a documentação oficial de skills

O arquivo tem duas partes: o frontmatter YAML entre marcadores --- (o "quando usar") e o corpo em Markdown (o "como fazer")

As propriedades permitidas no frontmatter são allowed-tools, compatibility, description, license, metadata e name, sendo name e description obrigatórias

Que divulgação progressiva? É o detalhe que mais muda a forma de escrever: no início da sessão, só o name e a description de cada skill entram no system prompt

O corpo do SKILL.md só é lido quando a skill dispara, e os arquivos anexos só sob demanda

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Ou seja: quem coloca sua regra de contraste em cena é a description casando com o pedido… por isso ela é o gatilho, e não um resuminho bonito

Description bem escrita, cobrindo os contextos de tela, componente, formulário e CSS, é justamente o que faz a regra valer em toda geração de interface

Se quiser comparar com a outra rota de escrita, tem o post sobre regra em skill ou no CLAUDE.md

Depois, escolha o escopo. Skill pessoal, skill do projeto ou plugin

O comando /plugin abre o gerenciador de plugins do Claude Code (com abas navegáveis por Tab), o /plugin marketplace add <owner/repo> adiciona um catálogo, e a instalação te deixa escolher entre escopo de usuário (todos os projetos), de projeto (todos os colaboradores do repositório) ou local (só você, só naquele repositório)

Quem prefere partir de algo pronto: existe uma skill oficial da Anthropic chamada frontend-design, cujo SKILL.md vive em plugins/frontend-design/skills/frontend-design/SKILL.md dentro do repositório anthropics/claude-code

Mesma lógica vale pra quem olha coleções de skills de terceiros: serve de ponto de partida, não te livra de escrever a sua regra

E a referência técnica precisa ser a certa: a WCAG 2.2 é Recomendação do W3C desde 05/10/2023 e é a versão vigente

A WCAG 3.0 seguia como Working Draft (rascunho de trabalho) em março de 2026, então NÃO é padrão final e não é o que você deve citar dentro da skill

Quais checagens de acessibilidade valem virar regra escrita na skill

A régua pra decidir o que entra é simples: entra o que tem número, critério nomeado ou comportamento esperado

Regra checável o Claude consegue aplicar. "Faça acessível" ele não consegue, porque não existe estado final verificável ali

São quatro famílias que cobrem o grosso do que aparece em tela gerada

Contraste: onde entram o 4,5:1 e o 3:1

O 1.4.3 Contraste (Mínimo), nível AA, pede pelo menos 4,5:1 entre texto normal e fundo, e 3:1 pra texto grande (18pt, ou 14pt em negrito, e maiores)

Só que texto não é a tela inteira, né?

Borda de input, ícone clicável, traço de gráfico: isso cai no 1.4.11 Contraste de Não Texto, também AA, com mínimo de 3:1 entre o componente (ou objeto gráfico significativo) e as cores adjacentes

Esses dois viram regra fácil porque são número puro: o Claude consegue escolher token de cor com esse alvo em mente na hora de gerar o CSS

Foco visível: o que é AA e o que é AAA?

Aqui mora a pegadinha que eu mais vejo em skill mal escrita

O 2.4.7 Foco Visível é AA: precisa existir pelo menos um modo de operação em que o indicador de foco do teclado fique visível, sem limite de tempo

O 2.4.11 Foco Não Obscurecido (Mínimo) também é AA e é novidade da WCAG 2.2: o componente que recebe foco não pode ficar INTEIRAMENTE escondido por conteúdo criado pelo autor, tipo barra fixa no rodapé ou cookie banner

Agora o cuidado: o 2.4.13 Aparência do Foco (área de pelo menos o perímetro de 2 pixels CSS do componente e contraste mínimo de 3:1 entre o estado focado e o não focado) é nível AAA, não AA

Se você escrever isso na skill como se fosse AA, você criou uma regra mais dura do que o alvo que o time combinou… e depois vai discutir com o designer por causa de um número que você mesmo errou de nível

Escreva como opcional, marcando o nível, e pronto

Navegação por teclado: alcançar tudo e não ficar preso

O 2.1.1 Teclado é nível A: toda funcionalidade disponível por ponteiro precisa estar disponível por interface de teclado

O 2.1.2 Sem Bloqueio de Teclado, também A, é o complemento: o foco tem que conseguir SAIR de qualquer componente usando só o teclado (o clássico modal que engole o Tab e não devolve)

Junto com eles entra o 2.5.8 Tamanho do Alvo (Mínimo), AA na 2.2, que pede alvos de pelo menos 24 por 24 pixels CSS, com cinco exceções previstas (espaçamento, equivalente, em linha, controle do agente de usuário e essencial)

Essa regra é boa de escrever porque ataca direto o ícone miúdo que a IA adora colocar como botão de fechar

Rótulos e semântica: nome, função, valor

O 3.3.2 Rótulos ou Instruções é nível A e exige rótulo ou instrução identificando os controles de formulário, incluindo cada opção de radio, checkbox e combobox

O 4.1.2 Nome, Função, Valor, também A, é o que garante que o componente tenha nome determinável programaticamente, além de função, estado e valor

É o critério que transforma aquele div com onClick em algo que a tecnologia assistiva entende

E fecha com o 1.4.1 Uso da Cor, nível A: cor não pode ser o único meio visual pra transmitir informação, indicar ação ou distinguir um elemento

E o 4.1.1 Parsing? Ficou de fora

Esse não entra na sua skill

O 4.1.1 Análise (Parsing) está marcado como obsoleto e removido na WCAG 2.2, porque navegadores e tecnologias assistivas modernas já lidam com aqueles erros de código

Se você copiar uma checklist velha da internet, ele vem junto e você vai gastar geração do modelo com regra aposentada

Passo a passo: escrevendo as regras de acessibilidade no SKILL.md

Bora ver na prática?

1. Crie a pasta da skill. Em skill pessoal ou de projeto, o nome da PASTA é o que manda no comando, enquanto o campo name define só o rótulo exibido na listagem

mkdir -p ~/.claude/skills/design-acessivel

O erro comum deste passo: batizar a pasta de um jeito e o name de outro, e depois estranhar que o comando não é o que você escreveu no frontmatter

2. Escreva a description como gatilho. Ela precisa dizer o que a skill faz E em quais contextos usar, porque é contra ela que o Claude compara o pedido

---
name: Design acessível
description: Gera e revisa interface web aplicando as regras de acessibilidade do time (contraste, foco visível, navegação por teclado e rótulos), com base na WCAG 2.2. Use quando o pedido envolver criar ou alterar tela, componente, formulário, modal, tema ou CSS.
---

O erro comum deste passo: escrever "skill de design" e deixar todo o "quando usar" pro corpo do arquivo

Não funciona: no começo da sessão só name e description estão carregados, então o "quando usar" tem que estar TODO ali

3. Redija as regras do corpo em forma de restrição checável. Valor numérico, critério nomeado, comportamento esperado. Conselho vago não gera decisão

## Contraste

- Texto normal: mínimo de 4,5:1 com o fundo (WCAG 2.2, 1.4.3, AA)
- Texto grande (18pt, ou 14pt em negrito, e maiores): mínimo de 3:1
- Borda de input, ícone de ação e traço de gráfico: mínimo de 3:1 com a cor adjacente (1.4.11, AA)
- Cor nunca é o único sinal de erro, seleção ou estado (1.4.1, A): sempre acompanha texto ou ícone

## Foco e teclado

- Todo elemento interativo tem indicador de foco visível (2.4.7, AA). Se remover `outline`, substitua por outro indicador
- Modal, drawer e menu devolvem o foco com Esc e com Tab (2.1.2, A)
- Toda ação de clique tem equivalente por teclado (2.1.1, A)
- Alvo clicável com pelo menos 24 x 24 pixels CSS (2.5.8, AA)
- Barra fixa e banner não podem esconder por completo o elemento focado (2.4.11, AA)

## Rótulos

- Todo controle de formulário tem rótulo associado, incluindo radio, checkbox e combobox (3.3.2, A)
- Componente customizado expõe nome, função, estado e valor (4.1.2, A)
- Ícone sem texto visível recebe nome acessível descrevendo a AÇÃO, não o desenho

O erro comum deste passo: escrever "siga a WCAG" e achar que resolveu. Vira instrução sem alvo, e o resultado varia a cada geração

4. Diga o que fazer quando a regra bate de frente com o design. Sem ordem de prioridade explícita, o modelo escolhe sozinho… e normalmente escolhe o que é mais bonito

## Conflito entre regra e estética

1. Critério AA da WCAG 2.2 vence preferência visual
2. Se o token de cor da marca não alcança 4,5:1, ajuste a luminosidade do token e informe o valor usado
3. Nunca remova o indicador de foco sem colocar outro no lugar
4. Se não der pra resolver no código, gere assim mesmo e liste no fim da resposta qual critério ficou pendente e por quê

O erro comum deste passo: não prever o conflito. Aí a paleta da marca entra em rota de colisão com o contraste e ninguém sabe quem ganha

5. Mantenha o SKILL.md abaixo de 500 linhas. A recomendação oficial de autoria é essa, e ao se aproximar do limite você quebra o conteúdo em arquivos de referência com ponteiros claros

Regras completas de foco e teclado: leia `foco-teclado.md`
Tokens de cor já aprovados com os valores de contraste: leia `contraste-tokens.md`

Joga a seu favor: arquivo extra só é lido sob demanda, então tabela gigante de token não precisa ficar pesando no corpo principal

O erro comum deste passo: quebrar em arquivos e esquecer o ponteiro. Arquivo que ninguém aponta é arquivo que não é lido

6. Decida sobre allowed-tools sabendo do limite. Esse campo só é suportado no Claude Code via CLI e NÃO vale quando a skill é usada pelo SDK

---
name: Design acessível
description: Gera e revisa interface web aplicando as regras de acessibilidade do time...
allowed-tools: Read, Edit, Grep
---

O erro comum deste passo: montar a segurança da skill em cima do allowed-tools e levar o mesmo arquivo pro SDK achando que a restrição foi junto

O que a skill não resolve e continua exigindo verificação humana

Agora o veredito honesto, porque prometer que a skill resolve acessibilidade seria mentira

Regra escrita ORIENTA a geração, ela não PROVA o resultado

E olha que nem ferramenta automática prova tudo: um estudo da Deque sobre dados anonimizados de mais de 2.000 auditorias e mais de 13.000 páginas, cobrindo perto de 300.000 problemas, encontrou que em média 57% dos problemas de acessibilidade foram totalmente cobertos por teste automatizado com a suíte axe

Se a automação madura fica nessa faixa em auditoria humana comparada, texto de instrução dentro de um arquivo Markdown não vai fechar a conta sozinho

O caminho é empilhar camada: a skill na geração, e uma checagem automatizada depois. O axe-core é a biblioteca de regras open source, mantida pela Deque Labs, que alimenta essa suíte

E o que fica obrigatoriamente com gente:

• Ordem de tabulação que faz sentido. Dá pra ter tudo focável e ainda assim o Tab pular de um jeito que não segue a lógica da tela
• Texto de rótulo que descreve a ação certa. "Botão" passa em checagem de existência de nome e não ajuda ninguém
• Foco não obscurecido em tela real. Barra fixa, cookie banner e toast só mostram o problema com conteúdo de verdade e viewport de verdade
• Uma passada de teclado de ponta a ponta. Entrar no fluxo, completar a tarefa e sair, sem mouse

Nada disso é caro. É chato, mas não é caro 🙂

Conclusão

A sacada de colocar acessibilidade dentro da skill de design do Claude é essa: ela deixa de ser revisão de última hora e vira padrão da geração

O que dá pra escrever é o que tem número e critério: contraste (1.4.3 e 1.4.11), foco (2.4.7 e 2.4.11), teclado (2.1.1, 2.1.2 e 2.5.8) e rótulos (3.3.2, 4.1.2 e 1.4.1), tudo na régua da WCAG 2.2

O que não dá é julgamento: ordem, clareza do texto e comportamento em tela real

Próximo passo concreto: monte um SKILL.md curto só com essas quatro famílias, roda numa tela real do seu projeto e compara o resultado com uma passada de teclado e uma checagem automatizada

Os furos que aparecerem viram as próximas regras… e é assim que o arquivo cresce com motivo, em vez de crescer por achismo

até o próximo post!