corrigindo-acessibilidade

Quando Usar

Use esta habilidade quando precisar auditar e corrigir problemas de acessibilidade em HTML, incluindo rótulos ARIA, navegação por teclado, gerenciamento de foco, contraste de cores e erros de formulário. Use ao adicionar controles interativos, formulários, caixas de diálogo ou ao revisar a conformidade com as WCAG.

Corrija problemas de acessibilidade.

Como Usar

• /fixing-accessibility Aplique estas restrições a qualquer trabalho de UI nesta conversa.

• /fixing-accessibility <file> Revise o arquivo em relação a todas as regras abaixo e relate:

  • violações (cite a linha ou trecho exato)
  • por que importa (uma frase curta)
  • uma correção concreta (sugestão em nível de código)

Não reescreva grandes partes da UI. Prefira correções mínimas e direcionadas.

Quando Aplicar

Consulte estas diretrizes ao:

• adicionar ou alterar botões, links, campos de entrada, menus, caixas de diálogo, abas, menus suspensos
• construir formulários, validação, estados de erro, texto de ajuda
• implementar atalhos de teclado ou interações personalizadas
• trabalhar em estados de foco, aprisionamento de foco ou comportamento modal
• renderizar controles apenas com ícones
• adicionar interações apenas com hover ou conteúdo oculto

categorias de regras por prioridade

referência rápida

1. nomes acessíveis (crítico)

• todo controle interativo deve ter um nome acessível
• botões apenas com ícones devem ter aria-label ou aria-labelledby
• todo campo de entrada, select e textarea deve ser rotulado
• links devem ter texto significativo (sem “clique aqui”)
• ícones decorativos devem ser aria-hidden

2. acesso por teclado (crítico)

• não use div ou span como botões sem suporte completo por teclado
• todos os elementos interativos devem ser alcançáveis por Tab
• o foco deve ser visível para usuários de teclado
• não use tabindex maior que 0
• Escape deve fechar caixas de diálogo ou sobreposições quando aplicável

3. foco e caixas de diálogo (crítico)

• modais devem prender o foco enquanto abertos
• restaure o foco para o gatilho ao fechar
• defina o foco inicial dentro das caixas de diálogo
• abrir uma caixa de diálogo não deve rolar a página inesperadamente

4. semântica (alto)

• prefira elementos nativos (button, a, input) em vez de hacks baseados em role
• se um role for usado, os atributos aria necessários devem estar presentes
• listas devem usar ul ou ol com li
• não pule níveis de cabeçalho
• tabelas devem usar th para cabeçalhos quando aplicável

5. formulários e erros (alto)

• erros devem ser vinculados aos campos usando aria-describedby
• campos obrigatórios devem ser anunciados
• campos inválidos devem definir aria-invalid
• texto de ajuda deve ser associado aos campos de entrada
• ações de envio desabilitadas devem explicar o motivo

6. anúncios (médio-alto)

• erros críticos de formulário devem usar aria-live
• estados de carregamento devem usar aria-busy ou texto de status
• toasts não devem ser a única forma de transmitir informações críticas
• controles expansíveis devem usar aria-expanded e aria-controls

7. contraste e estados (médio)

• garanta contraste suficiente para texto e ícones
• interações apenas com hover devem ter equivalentes de teclado
• estados desabilitados não devem depender apenas de cor
• não remova contornos de foco sem um substituto visível

8. mídia e movimento (baixo-médio)

• imagens devem ter texto alt correto (significativo ou vazio)
• vídeos com fala devem fornecer legendas quando relevante
• respeite prefers-reduced-motion para movimento não essencial
• evite mídia com som em autoplay

9. limites da ferramenta (crítico)

• prefira mudanças mínimas, não refatore código não relacionado
• não adicione aria quando a semântica nativa já resolve o problema
• não migre bibliotecas de UI a menos que solicitado

correções comuns

<!-- icon-only button: add aria-label -->
<!-- before --> <button><svg>...</svg></button>
<!-- after -->  <button aria-label="Close"><svg aria-hidden="true">...</svg></button>

<!-- div as button: use native element -->
<!-- before --> <div onclick="save()">Save</div>
<!-- after -->  <button onclick="save()">Save</button>

<!-- form error: link with aria-describedby -->
<!-- before --> <input id="email" /> <span>Invalid email</span>
<!-- after -->  <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">Invalid email</span>

orientação de revisão

• corrija primeiro os problemas críticos (nomes, teclado, foco, limites da ferramenta)

…