Crie um sistema de design que a IA saiba usar e confira os componentes que ela gera

## Descubra quais pacotes cuidam dos componentes e da documentação antes de mudar algo Trate o sistema de design como um contrato de produto compartilhado, não como uma coleção de fragmentos visuais. Identifique os pacotes responsáveis por componentes, documentação, exemplos, superfícies de pré-visualização, estruturas de teste e utilitários de migração antes de alterar qualquer coisa. Use o ramo atual do repositório como autoridade para as APIs e convenções disponíveis. Não deduza que há suporte com base no conhecimento geral da plataforma Web, em outro ramo ou em uma versão mais recente da biblioteca. Mantenha o gerenciador de pacotes, o ambiente de execução, o formato de módulos e o executor de testes configurados, a menos que a tarefa altere explicitamente o conjunto de ferramentas. ## Leia a documentação e a lista de componentes do ramo atual antes de começar Antes de trabalhar em um componente: 1. Leia as instruções do repositório e do pacote que regem o alvo. 2. Consulte a ajuda local da linha de comando e liste os tópicos de documentação disponíveis. 3. Carregue os princípios de design, tokens, regras de tema e inventário de componentes. 4. Examine os modelos de página quando a tarefa tratar do layout, e não de um único elemento básico. 5. Leia a API atual, as variantes, a anatomia, os exemplos e as restrições do componente alvo. Repita essa preparação em cada ramo, pois a documentação gerada e as APIs compatíveis podem ser diferentes. Depois de atualizar uma dependência do sistema de design, execute o utilitário de migração do repositório antes de fazer alterações manuais sem relação com a atualização. ## Atualize juntos o cabeçalho de cada arquivo e a documentação do componente Mantenha duas camadas complementares de documentação. Coloque metadados concisos de entrada, saída e posição arquitetônica no cabeçalho de cada arquivo-fonte. Mantenha propriedades detalhadas, recursos, exemplos, observações de acessibilidade e orientação de composição em um arquivo de documentação pertencente ao componente. Quando a implementação mudar, atualize as duas camadas e siga os marcadores de sincronização que identificam arquivos vinculados. Use o formato de documentação que o renderizador realmente aceita; por exemplo, use blocos de exemplo sem indicação de linguagem quando blocos identificados por linguagem quebrarem o analisador ativo de documentação automática. Verifique o resultado renderizado em vez de supor que uma sintaxe válida no código-fonte gera documentação válida. ## Registre quais recursos de CSS a ferramenta de estilos suporta de fato Registre a versão do mecanismo de estilos e o suporte verificado a at-rules, pseudoclasses, pseudoelementos, seletores compostos, valores, animações, variáveis, temas, valores dinâmicos e seletores condicionais. Diferencie a sintaxe compatível daquela que compila, mas produz CSS inválido ou inutilizável. Prefira soluções nativas de CSS quando a matriz confirmar o suporte. Entre os candidatos comuns estão consultas de mídia, de recursos e de contêiner; estilos iniciais; escopo; pseudoclasses de interação e estrutura; pseudoelementos de conteúdo gerado; funções modernas de cor e dimensionamento; transições; e quadros-chave. Não crie uma solução alternativa em JavaScript apenas porque uma tabela antiga de capacidades não incluía o recurso. ## Mantenha os efeitos de hover e foco dentro do próprio componente Represente o estado de ancestrais, descendentes e irmãos por meio do mecanismo de seletores condicionais aceito pelo sistema de estilos. Quando esse mecanismo exigir um marcador, aplique-o ao ancestral real e mantenha a definição do marcador próxima do componente responsável. Use marcadores limitados ao componente em controles de formulário e outros elementos interativos aninhados. Nunca use um marcador global padrão quando popovers, painéis ou contêineres externos puderem fazer o estado de hover ou foco vazar para o controle. Respeite contratos de seletores, como condições de ancestral compostas apenas por pseudoclasses, e não simule aninhamento CSS incompatível. Proteja efeitos exclusivos de hover com uma consulta de mídia que detecte essa capacidade, para que dispositivos de toque não herdem estados de interação persistentes. Preserve o foco pelo teclado e o comportamento do estado desativado independentemente do hover. ## Use CSS para layout e animação em vez de JavaScript Use diretamente grid, flexbox com espaçamentos, proporções, controles de transbordamento e propriedades de barra de rolagem quando houver suporte. Prefira consultas de contêiner para o comportamento responsivo de componentes em vez de medir elementos com observadores, e use pseudoclasses estruturais para faixas alternadas em vez de JavaScript baseado em índices. Implemente transições de entrada com suporte a starting-style, e não com estado combinado a uma orquestração de quadros de animação. Expresse fallbacks CSS ordenados pela abstração de fallback do sistema de estilos em vez de detecção manual durante a execução. Use suporte especializado de posicionamento somente quando o CSS gerado tiver sido verificado no conjunto de navegadores compatíveis. ## Deixe links e temas trocáveis para que ninguém precise copiar componentes Encaminhe valores dependentes da execução por funções de estilo tipadas, e não por estilos inline. Componha estilos condicionais pelo mecanismo de propriedades de estilo do sistema, em vez de alternar nomes de classes improvisados. Mantenha variáveis de tema e a criação de temas nos tipos de arquivo exigidos pelo compilador e use variáveis tipadas ou constantes de compilação quando melhorarem a validação. Renderize a navegação por uma abstração de link injetável, em vez de fixar elementos de âncora. Isso permite que consumidores forneçam seu roteador sem bifurcar componentes. Siga os contratos do repositório para ativos, fontes, caminho público e provedor de tema, para que os componentes empacotados continuem portáveis. ## Teste se a IA cria componentes corretos, também no fim de uma conversa longa Meça se a orientação ao agente ajuda os modelos a gerar código de componente válido. Execute o conjunto completo de prompts ou uma amostra estratificada para obter retorno rápido. Para cada prompt, use um worker isolado que leia a tarefa, gere um componente com o sistema documentado, identifique por conta própria as vias de escape e salve tanto o código quanto os metadados de avaliação. Adicione um modo de degradação para a retenção de contexto ao longo de uma conversa de 10 turnos com turnos de preenchimento, distração e recuperação. Avalie pontos representativos, como os turnos 0, 6, 8 e 10, e compare a trajetória de cada prompt em vez de informar somente o turno final. Vincule prompts de teste, resultados gerados e capturas de tela a um identificador de iteração estável. Paralelize prompts independentes, mas não permita que workers compartilhem arquivos mutáveis de resultados. ## Salve cada resultado de teste e ache onde a IA contornou o sistema de design Armazene metadados estruturados suficientes para reproduzir e comparar cada caso: identificadores de iteração e prompt, carimbo de data e hora, modelo, persona, categoria do prompt, profundidade da trajetória, prompt, resposta gerada, julgamento de sucesso, componentes usados e vias de escape detectadas. Crie páginas de pré-visualização e capture telas antes da agregação. Avalie tanto o sucesso funcional quanto se a saída contornou o sistema de design por meio de elementos brutos, estilos inline, navegação fixa, seletores incompatíveis, elementos básicos duplicados ou soluções alternativas em JavaScript para CSS compatível. Trate a autoavaliação do modelo como um sinal, não como prova. Combine verificações mecânicas, evidências da pré-visualização e revisão humana por amostragem. Use resultados agregados para melhorar a documentação ou as APIs somente depois de localizar o padrão recorrente de falha. ## Faça checagens pequenas após cada mudança e relate quais foram aprovadas Antes de modificar um componente, examine a documentação atual e decida se a necessidade é mais bem atendida por configuração, composição, uma nova variante ou uma ejeção explícita do código-fonte para personalização profunda. Preserve os contratos públicos e evite criar um elemento básico paralelo quando já existir um ponto de extensão estabelecido. Depois da alteração, atualize a documentação sincronizada e execute os menores testes unitários, verificações de tipos e lint, análise de capacidades de estilo e pré-visualização do componente que sejam pertinentes. Amplie para o conjunto completo somente quando a alteração atravessar contratos compartilhados. Se a versão do pacote principal mudar, execute a etapa de migração documentada e examine seu diff. Informe o comportamento alterado, a documentação atualizada, as verificações aprovadas, qualquer capacidade incompatível descoberta e qualquer validação que não pôde ser executada.