Criar Regras de um Verificador de Acessibilidade que Retornem Aprovado, Falha ou Incompleto

## Trate Lint e Testes como Parte de Cada Mudança, Não como Limpeza Trate formatação, lint, testes, documentação e convenções de commit como parte da mudança, não como limpeza posterior à implementação. ### Verificações obrigatórias - Execute o formatador e o linter do repositório antes de fazer o commit. - Execute o conjunto completo de testes antes da conclusão, com cobertura unitária e de integração para mudanças de comportamento. - Siga as exceções documentadas somente para mudanças que não possam afetar o comportamento em tempo de execução. - Mantenha o trabalho não resolvido no rastreador de problemas do projeto, em vez de escondê-lo em mudanças não relacionadas. - Não inclua no commit registros temporários nem configurações locais de depuração. ### Convenções de código - Trate erros e casos extremos logo no início para que o caminho bem-sucedido continue fácil de acompanhar. - Siga a posição estabelecida de export, as regras de nomenclatura e o estilo de import. - Dê nomes consistentes a arquivos e identificadores de regras; diferencie funções, booleanos e constantes conforme as convenções do projeto. - Declare as variáveis perto do primeiro uso. - Documente APIs exportadas, parâmetros, valores de retorno e lógica complexa. - Mantenha a refatoração separada de uma funcionalidade ou correção com escopo específico. ## Escolha entre Nós Virtuais e DOM Real e Mantenha as Dependências em um Só Sentido Escolha de forma deliberada entre uma abstração de árvore virtual e nós DOM reais. A abstração é eficiente para atributos e propriedades armazenados em cache, enquanto o DOM real é necessário para APIs do navegador e comportamento de layout. ### Seleção de nós - Prefira nós virtuais para acesso a atributos, propriedades armazenadas em cache, percurso de árvores e trabalho com seletores. - Use nós DOM reais para layout, geometria, busca da raiz, comportamento calculado pelo navegador e outras APIs nativas. - Resolva entradas ambíguas por meio de um único limite de conversão documentado. - Mantenha utilitários gerais baseados em entradas e saídas de DOM real, a menos que uma dependência de nó virtual ofereça vantagem clara de API ou desempenho. - Não espalhe a lógica de conversão por regras individuais. ### Direção das dependências - Mantenha as definições de padrões como dados puros, sem import em tempo de execução. - Permita que utilitários de baixo nível dependam apenas de código-base de nível inferior e de dados de padrões por caminhos explícitos. - Centralize o import de módulos de terceiros em uma camada adaptadora designada. - Permita que auxiliares de domínio compartilhados usem utilitários de baixo nível, mas nunca inverta essa dependência. - Permita que verificações e regras de alto nível combinem camadas inferiores sem criar ciclos. - Imponha esses limites mecanicamente com regras de lint ou de compilação. ## Retorne Aprovado, Falha ou Incompleto e Guarde as Mensagens nos Metadados Torne explícito o contrato de resultados para que os consumidores possam diferenciar conformidade, falha e evidência insuficiente. ### Resultados das verificações - Retorne `pass` quando a condição testada for atendida. - Retorne `fail` quando a condição testada for violada. - Retorne `incomplete` quando o mecanismo não conseguir determinar o resultado com segurança. - Anexe dados estruturados para modelos de mensagens e para explicar resultados `incomplete`. - Não force a incerteza a se tornar `pass` ou `fail` apenas para produzir uma resposta binária. ### Definições de regras - Combine verificações com grupos explícitos `all`, `any` e `none`. - Delimite os elementos candidatos com um seletor e um comparador adicional opcional. - Restrinja o impacto aos valores de gravidade declarados pelo projeto. - Leia as definições de HTML e ARIA em dados de padrões centralizados, em vez de codificar listas diretamente nas verificações. ### Mensagens para o usuário - Mantenha as mensagens nos metadados da regra ou da verificação, não no código de implementação. - Use espaços reservados de dados nomeados, cujos valores sejam fornecidos pelo resultado da verificação. - Forneça variantes no singular e no plural quando a gramática exigir. - Atualize o modelo de localização sempre que uma mensagem de origem mudar. ## Revise com Cuidado Extra o Contraste de Cores e a Validação de Papéis Alguns resultados de acessibilidade dependem de informações incompletas do navegador ou de padrões em rápida evolução. Essas áreas exigem resultados conservadores e revisão direcionada. ### Cor e visibilidade - Considere os formatos de cor compatíveis, a opacidade, a mistura, os contextos de empilhamento e os efeitos de texto. - Retorne `incomplete` quando não for possível determinar o fundo efetivo ou o contraste. - Avalie semanticamente a visibilidade para leitores de tela, em vez de depender apenas da visibilidade de CSS. - Inclua atributos de estado oculto, árvores compostas e limites de Shadow DOM. ### Padrões semânticos - Mantenha a validação de `role` e de atributos sincronizada com a especificação de acessibilidade atual. - Resolva separadamente `role` implícitos e explícitos. - Consulte definições centralizadas de `role` e de atributos para que todas as regras usem a mesma fonte de verdade. - Adicione casos de regressão para atualizações da especificação e para marcações classificadas incorretamente no passado. - Exija uma revisão direcionada quando uma mudança puder alterar resultados em várias regras. ## Teste Cada Regra em Páginas Realistas, Incluindo Shadow DOM Reproduza a estrutura do código-fonte na árvore de testes unitários para que a responsabilidade pela implementação e pelos testes continue evidente. ### Testes unitários e de verificações - Use o contexto de verificação padrão ou o harness fornecido pelo projeto. - Redefina somente o estado pertencente ao teste quando o harness já tiver limpado os fixtures compartilhados e as árvores virtuais. - Teste os resultados `pass`, `fail` e `incomplete`, incluindo os dados de mensagem anexados. - Adicione casos direcionados para condições extremas antes de ampliar a cobertura de integração. ### Testes de integração - Associe cada fixture de regra a resultados esperados estruturados. - Use a representação canônica de seletores do mecanismo, incluindo seletores aninhados para frames. - Use uma página HTML completa quando o comportamento no nível do documento não puder ser representado por um fragmento. - Adicione um caso de open Shadow DOM para cada regra ou verificação relevante. - Atualize a cobertura de regras virtuais quando uma mudança afetar a avaliação da árvore virtual. - Execute testes direcionados durante a iteração e o conjunto completo e oficial antes da entrega. ## Regere os Modelos de Tradução no Mesmo Commit das Mensagens Diferencie os pacotes de versão gerados dos artefatos de código-fonte gerados que o repositório acompanha intencionalmente. ### Política de artefatos - Não edite diretamente a saída de versão empacotada ou minificada. - Gere novamente os modelos ou artefatos de código-fonte acompanhados por meio da compilação aprovada. - Inclua o modelo de localização gerado na mesma mudança que a mensagem de origem que o produziu. - Não divida atualizações sincronizadas do código-fonte e dos itens gerados em commits separados. - Mantenha os pacotes de publicação ignorados fora dos commits comuns de funcionalidades. ### Verificação - Examine o diff gerado em busca de mudanças inesperadas em mensagens, localidades ou regras. - Confirme que cada novo espaço reservado exista nos dados da verificação que o produz. - Execute a validação de localização e de compilação após mudanças nas mensagens. - Documente quais artefatos são gerados, quais são acompanhados e quais se destinam apenas a versões. ## Atualize o Changelog e a Documentação da API e Evite Mudanças Incompatíveis Mantenha cada mudança focada e torne suas consequências públicas visíveis para revisores e consumidores. ### Documentação das mudanças - Atualize o registro de alterações ao adicionar uma regra ou modificá-la de forma substancial. - Atualize em conjunto a documentação da API e as definições de tipos quando uma interface pública mudar. - Use o formato de conventional commit exigido pelo repositório, com um assunto conciso e a motivação no corpo. - Vincule o problema resolvido pelo footer aceito ou pelos metadados da solicitação de pull. - Conclua a lista de revisão do projeto antes da entrega. ### Compatibilidade - Evite mudanças incompatíveis quando os formatos antigo e novo puderem ter suporte simultâneo. - Marque claramente as APIs obsoletas e forneça um caminho de migração. - Quando uma quebra for inevitável, identifique-a de forma explícita nos metadados da versão e no registro de alterações. - Inclua orientações de migração, testes atualizados, arquivos gerados sincronizados e evidências visíveis aos revisores. - Não afirme que a mudança está pronta até que a formatação, o lint, os testes direcionados, os testes de integração, o conjunto completo e as verificações de documentação tenham resultados reais.