Claude escreveu um DatePicker em React, mas chegar à acessibilidade WCAG levou mais 3 dias

Uma equipe de desenvolvimento pediu ao Claude um DatePicker personalizado em React para um formulário de agendamento de consultas médicas, com suporte completo a navegação por teclado e leitores de tela. A IA fez a primeira versão rapidamente. Depois vieram três dias de ajustes.

O que o Claude fez bem

O Claude gerou uma base funcional do componente: a estrutura JSX, atributos ARIA básicos (`role="dialog"`, `aria-label`, `aria-live`), manipuladores de teclas para navegar com as setas e a lógica da grade do calendário. Como ponto de partida, era bom: o código compilava, parecia correto visualmente e a verificação manual não quebrou nada.

A IA foi especialmente útil no código repetitivo: gerar as 42 células da grade, calcular o deslocamento do primeiro dia do mês e formatar as datas para o `aria-label`. É um trabalho chato de fazer à mão, e o Claude o executou com capricho.

O problema só ficou evidente depois de conectar tecnologias assistivas reais.

Onde tudo deu errado

O teste de verdade começou quando rodaram o NVDA no Windows e o VoiceOver no macOS. Apareceram vários problemas:

• A armadilha de foco não funcionava: ao navegar com Tab dentro do diálogo, o foco ia para o documento principal
• As datas eram lidas errado: o leitor de tela dizia "1" em vez de "segunda-feira, 1 de junho de 2026"
• A troca de mês era silenciosa: a região `aria-live` não era atualizada quando o mês mudava
• O Escape fechava, mas não devolvia o foco: depois de fechar o calendário, o foco se perdia em vez de voltar ao botão que o abriu
• Alto contraste do Windows: a data selecionada não se distinguia das outras, porque o componente dependia de cor CSS sem atributos de estado

Cada um desses itens parecia, no código gerado, "tem um manipulador", mas o comportamento com um leitor de tela real era diferente do esperado.

Como consertaram

A salvação foi o WAI-ARIA APG, o guia oficial do W3C com um padrão concreto para o diálogo de DatePicker. Ele não diz só "adicione `aria-modal`", mas define a sequência exata: qual elemento recebe o foco ao abrir, como manter a armadilha de foco, para onde devolvê-lo ao fechar e quais `aria-label` os botões de navegação entre meses precisam ter.

"Ler o código gerado não é o mesmo que verificar a acessibilidade.

Só um leitor de tela real mostra a verdade."

A armadilha de foco foi reescrita com `querySelectorAll`, interceptando manualmente Tab e Shift+Tab. Cada célula de dia ganhou um `aria-label` completo, como "quarta-feira, 3 de junho de 2026", além de `aria-pressed="true"` para o estado selecionado. Para o modo de alto contraste, adicionaram `aria-selected` e um contorno com `outline`, em vez de depender só da cor de fundo.

O ponto mais delicado foi o `aria-live`: a região precisa estar no DOM antes de o texto ser escrito nela; caso contrário, o leitor de tela a ignora. O Claude inseriu a região dinamicamente, e essa sutileza só apareceu no teste.

O que isso significa

O Claude acelera a escrita de código acessível, mas não substitui os testes com leitores de tela. A boa notícia: depois que a equipe entende o WAI-ARIA APG uma vez e documenta as soluções, o próximo componente acessível sai bem mais rápido. A IA assume o trabalho repetitivo, mas a verificação final com NVDA e VoiceOver não pode ser pulada.