FrancoisChastel/a11y-eval

Corretor de Acessibilidade

Você está executando correções de acessibilidade. Sua entrada é uma ordem de serviço de mitigação (mitigations.md, produzida por a11y-eval); sua saída são mudanças mínimas no código-fonte que fazem as descobertas desaparecerem para usuários reais, verificadas pela reexecução do avaliador.

Se ainda não existir uma ordem de serviço, gere uma primeiro: node src/cli.ts --repo <dir> (ou --url para uma aplicação em execução) em um checkout do a11y-eval, ou node src/cli.ts mitigate --report <dir> a partir de um relatório existente.

Instruções de correção

Corrija violações de acessibilidade com a menor mudança que restaure o acesso real, nesta ordem de preferência:

1. Semântica nativa primeiro. Substitua widgets falsos por elementos reais: div onclick → <button type="button">, span de navegação → <a href>, entrada sem rótulo → <label for> + input. Elementos nativos trazem operabilidade por teclado, papéis, nomes e estados de graça — adaptações ARIA são o plano B, nunca o primeiro movimento.
2. Conteúdo sobre atributos. Texto alternativo, rótulos, texto de link e mensagens de erro devem transmitir a informação real ("Receita do Q3 subiu 12%"), não reafirmar o elemento ("gráfico", "imagem", "link"). Escreva a partir do contexto circundante; sinalize para um humano se o significado não for inferível.
3. Corrija no nível do token/componente. Quando a mesma regra dispara em várias páginas, encontre a causa compartilhada — uma propriedade personalizada CSS, um componente base, um wrapper de layout — e corrija-a uma vez. Nunca corrija quarenta pontos de chamada quando um componente é a causa raiz.
4. Preserve tudo que o usuário pode fazer ou ler. Conteúdo textual, capacidades interativas e hierarquia visual devem sobreviver à correção. Excluir um recurso, ocultar um elemento (display:none, aria-hidden) ou remover a focalização para silenciar uma descoberta é uma correção falha.
5. Contraste é aritmético, não estético. Calcule a proporção (≥4,5:1 texto normal, ≥3:1 texto grande/componentes de interface); escolha a tonalidade mais próxima que passe do matiz pretendido, em vez de pular para preto/branco.
6. O foco deve ser visível em todos os lugares. Remova outline: none abrangente; adicione contornos :focus-visible (≥2px, deslocamento, ≥3:1 contra o entorno). Verifique usando a tecla Tab.
7. Um grupo da ordem de serviço por conjunto de alterações. Corrija cada instância listada do grupo, depois verifique antes de iniciar o próximo. Agrupar conjuntos não relacionados torna as regressões impossíveis de rastrear.
8. Cada NÃO FAÇA na ordem de serviço é vinculativo. Quando uma correção e uma armadilha entrarem em conflito, a armadilha vence — pare e repense a abordagem.

Fluxo de trabalho

1. Leia a ordem de serviço de cima a baixo. Os grupos são ordenados por impacto e alcance — respeite a ordem.
2. Localize cada instância no código-fonte: descobertas estáticas trazem arquivo:linha:coluna; descobertas em tempo de execução trazem um seletor CSS e um trecho HTML — pesquise no repositório pelo trecho, nomes de classe ou texto próximo.
3. Aplique a correção do grupo a cada instância, seguindo as instruções de correção acima e as etapas/armadilhas do grupo.
4. Verifique o lote: reexecute o comando de verificação da ordem de serviço (a avaliação original + --baseline <relatório anterior>). O grupo é limpo quando sua regra aparece em "corrigido" com zero descobertas novas.
5. Seções de falha manual: a evidência do revisor é a especificação. Derive a mudança dela, aplique, e observe que o critério precisa de nova revisão humana/agente — a automação não pode confirmá-lo.
6. Condições de parada: uma instância cujo significado você não consegue inferir (texto alternativo para uma imagem desconhecida, um rótulo para um campo ambíguo) recebe um comentário TODO(a11y) mais uma anotação no seu resumo — um palpite errado é pior que uma lacuna sinalizada.
7. Relatório: pontuação antes → depois, grupos limpos, novas descobertas (devem ser zero), itens sinalizados para humanos.

Grupos suspeitos VLM

Ordens de serviço podem conter grupos vlm-* (apenas quando a avaliação foi executada com --vlm). Suas linhas de instância trazem o raciocínio do modelo de visão — para vlm-alt-quality-suspect, um texto alternativo proposto. Trate a proposta como um rascunho: verifique-a contra a imagem real antes de aplicar, e nunca aplique uma mudança proposta pelo VLM que você não possa confirmar a partir da própria página.

O que não fazer

• FALHA: tabindex + manipuladores de tecla embutidos em uma div quando um elemento nativo funciona
• FALHA: alt="" em imagens informativas; aria-label duplicando texto visível com discrepâncias
• FALHA: suprimir regras, excluir elementos ou aria-hidden para fazer descobertas desaparecerem
• FALHA: ajustes de contraste feitos a olho sem calcular a proporção
• FALHA: afirmar que está pronto sem uma reexecução de verificação mostrando as regras ausentes

Skills relacionadas

• a11y-evaluator — produz o relatório e a ordem de serviço que esta skill consome