Escreva regras em um repositório de regras de frontend e verifique-as antes de publicar

## Antes de mudar uma regra, separe os arquivos-fonte editáveis dos gerados Trate um repositório de regras de frontend como um produto composto por conteúdo-fonte, esquemas, APIs, ferramentas de revisão, páginas renderizadas e índices gerados. Antes de alterá-lo, identifique qual camada é responsável pelo comportamento e examine essa camada e seus consumidores diretos. - Mapeie o pacote de conteúdo, os tipos e esquemas compartilhados, as superfícies da aplicação, o servidor de ferramentas e as saídas geradas. - Quando disponíveis, use as ferramentas de revisão e busca de regras do repositório em vez de inventar orientações de memória. - Revise o código examinado antes de recomendar correções e pesquise o conjunto de regras antes de fazer afirmações sobre acessibilidade, desempenho, SEO, segurança, privacidade, internacionalização ou testes. - Faça auditorias amplas apenas quando a tarefa exigir uma auditoria ampla. - Diferencie fontes editáveis de artefatos gerados e projeções renderizadas. Derive as orientações de compatibilidade da política de navegadores declarada e de dados respaldados por pacotes. Não dependa de tabelas de compatibilidade lembradas nem trate silenciosamente uma visualização gerada como fonte da verdade. ## Defina os metadados que toda regra precisa ter Toda regra precisa de um contrato de metadados estável que permita análise, busca, pontuação, revisão e renderização. Mantenha o conjunto obrigatório pequeno o bastante para ser aplicado de modo consistente. Os metadados obrigatórios devem incluir: - um título legível por pessoas entre aspas e uma descrição de uma frase; - uma categoria, prioridade e dificuldade permitidas; - uma estimativa inteira de esforço com uma unidade declarada; - instruções acionáveis para verificar, corrigir e explicar a regra. Metadados opcionais úteis incluem subcategoria, conclusões concisas, impacto para o usuário ou para o negócio, fontes de evidência, recursos complementares, regras relacionadas, ferramentas, etiquetas, uma instrução de revisão de código e contexto para revisão automatizada. Valide categorias e enumerações em relação às listas canônicas permitidas. Coloque entre aspas os valores que contêm pontuação relevante para a sintaxe. Não adicione campos apenas porque parecem úteis; adicione-os somente quando forem consumidos pelo analisador, pela interface, pela camada de busca ou pelo gerador. As instruções devem nomear o objeto a examinar e a correção esperada. Rejeite marcadores provisórios como “verifique esta regra”, que não oferecem uma estratégia de revisão executável. ## Separe evidências, leituras extras e links para regras relacionadas Mantenha as evidências autoritativas nos metadados estruturados da fonte. Mantenha leituras e ferramentas opcionais nos metadados de recursos, e a navegação entre regras nos metadados de regras relacionadas. Não substitua uma função por outra. - Forneça a cada regra pelo menos 2 fontes relevantes, com 2 funções de fonte distintas e pelo menos 1 autoridade primária. - Use identificadores estáveis para evidências quando o fluxo oferecer suporte a eles. - Não inclua linhas genéricas como “Veja também” e “Referência” no corpo. - Crie um link para uma ferramenta nomeada em sua primeira menção relevante quando ela ajudar de fato e já constar nos metadados de recursos ou ferramentas. Os links incorporados devem sustentar uma afirmação específica ou uma escolha de implementação. Um padrão útil é usar de 2 a 5 links por regra, com 0 ou 1 na introdução e de 1 a 3 ao longo das orientações principais. Na maioria dos casos, mantenha entre 0 e 1 link interno para regras e use 2 apenas em temas excepcionalmente interligados. Prefira textos de link descritivos a rótulos como “saiba mais”. Permita que as ferramentas de compilação deduzam os campos que puderem derivar com segurança, mas nunca use a inferência para justificar evidências fracas ou irrelevantes. ## Em cada regra, coloque os exemplos de código antes dos motivos e a verificação no fim Escreva cada regra em uma ordem estável para que pessoas, agentes e validadores encontrem as mesmas informações: 1. uma introdução curta em linguagem simples; 2. um exemplo de código realista ou um conjunto de exemplos; 3. uma explicação da importância da regra; 4. todas as orientações de implementação necessárias; 5. uma seção final de verificação. Coloque os exemplos antes da justificativa e mantenha a verificação como a última seção de nível superior. Posicione seções opcionais, como práticas recomendadas, erros comuns, exemplos de frameworks, ferramentas, limites, exceções, compatibilidade com navegadores, normas e notas de implementação, entre elas. Adicione exceções somente quando houver ressalvas válidas ou falsos positivos. Divida a verificação em checagens automatizadas e manuais apenas quando ambas forem relevantes. Adicione uma nota visível sobre normas ou compatibilidade quando elas alterarem a decisão de implementação. Prefira instruções de aprovação ou reprovação a conselhos genéricos. Declare como uma pessoa de engenharia pode verificar a regra, quais evidências contam e qual condição faz a checagem falhar. ## Dê às regras de frontend limites mensuráveis de aprovação ou reprovação Use limites mensuráveis sempre que uma regra puder ser testada: - orçamentos de desempenho, como `LCP <= 2.5s`, `CLS <= 0.1` ou limites de tamanho de ativos; - critérios de acessibilidade, como taxas de contraste, tamanhos de alvos, comportamento do teclado, zoom e refluxo; - estados de SEO, como indexabilidade, códigos de status e comportamento da URL canônica; - requisitos de segurança, como condições de transporte e de cabeçalhos de resposta. Atribua a prioridade conforme a consequência: reserve o nível mais alto para falhas que interrompam o site ou violem requisitos de segurança ou legais; use níveis mais baixos para experiência degradada, práticas recomendadas e aprimoramentos opcionais. Os exemplos devem ser realistas o bastante para revelar o modo de falha. Inclua exceções importantes e restrições de compatibilidade, mas não adicione todas as seções opcionais a todas as regras. Trate a verificação como parte da regra, não como uma tarefa editorial posterior. Uma recomendação sem uma checagem reproduzível está incompleta. ## Mantenha os componentes de interface compartilhados no sistema de design, não em cada página Coloque tipografia, ícones, cores semânticas, componentes reutilizáveis e outras questões comuns a várias aplicações em um sistema de design compartilhado. As aplicações devem configurar a integração específica do framework enquanto consomem o contrato compartilhado. - Reutilize componentes existentes antes de criar variantes específicas de uma página. - Aplique uma funcionalidade compartilhada a todas as superfícies relevantes, não apenas à primeira página que a solicitou. - Mantenha os controles secundários operáveis ao usar padrões de cartões com link expandido. - Centralize ícones de marca e exportações de ícones do framework; os consumidores não devem contornar o limite do sistema de design. - Prefira tokens semânticos de tema com o contraste integral pretendido a modificadores arbitrários de opacidade. - Restaure explicitamente os marcadores de lista quando uma redefinição de CSS os remover de textos ricos. Não suprima avisos de hidratação entre servidor e cliente para ocultar uma divergência. Corrija o limite de estado, por exemplo adiando o estado exclusivo do cliente até depois da montagem. Mantenha a proteção originada no navegador nas mutações e nos formulários do navegador. Não aplique verificações de bots do lado do cliente a endpoints programáticos de API que não possam concluir um desafio do navegador. ## Conecte uma ferramenta nova por completo, da definição aos testes Uma nova ferramenta ou funcionalidade entre pacotes só está completa quando sua definição, exportação, registro, despacho, implementação, testes e documentação estão de acordo. Para uma ferramenta invocável: 1. defina um nome específico, uma descrição e um esquema de entrada; 2. exporte-a no limite do pacote; 3. registre-a no catálogo de ferramentas do servidor; 4. conecte-a ao caminho de despacho; 5. teste descoberta, validação, roteamento e comportamento. Use arquivos agregadores apenas nos limites dos pacotes; arquivos agregadores internos acrescentam etapas de navegação e ocultam responsabilidades. Mantenha centralizadas as versões de dependências compartilhadas quando vários pacotes as utilizarem e organize os scripts por finalidade, com um índice mantido. Respeite os contratos específicos da versão de cada biblioteca. Por exemplo, use a forma atual dos erros do validador instalado, crie clientes de consulta com estado por meio da fábrica aprovada pelo repositório e mantenha os contêineres de configuração assíncrona em uma ordem que preserve todas as propriedades retornadas. Reinicie os serviços depois de alterar configurações carregadas na inicialização. Uma edição bem-sucedida não é evidência até que o processo em execução a tenha carregado. ## Rode todas as verificações antes de publicar, sem pular nenhuma Execute a cadeia canônica de qualidade do repositório depois de alterar uma regra ou sua infraestrutura: - valide os metadados obrigatórios, os valores de categoria, a qualidade das fontes e a estrutura da regra; - pontue instruções acionáveis, evidências, exemplos, profundidade do corpo, verificação, limites e seções condicionais aplicáveis; - execute formatação, análise estática, verificações de tipos, verificações de pacotes, testes específicos e toda a compilação exigida pela superfície alterada; - regenere índices ou habilidades e confirme que a saída gerada está sincronizada. Não ignore as checagens de pré-commit. Corrija falhas de documentação, coerções de tipo inseguras, complexidade, limites de importação, código não utilizado e cobertura em vez de usar um caminho sem verificação. Trate a pontuação automatizada como um controle de qualidade, não como prova de correção semântica. Revise o resultado renderizado e o resultado voltado às ferramentas, além do arquivo-fonte. Antes da publicação, confirme que as instruções obrigatórias são acionáveis, que as evidências são autoritativas, que os exemplos correspondem à recomendação, que a verificação vem por último e que não resta nenhuma diferença gerada. Publique somente depois que toda a cadeia for aprovada.