Crie e atualize uma biblioteca de componentes de UI que siga as regras de design

## Leia a especificação de cada tarefa e siga o código quando a documentação divergir Classifique a tarefa antes de editar e leia a fonte que a rege. - Para comportamento de componentes ou APIs, leia o guia da API pública, a implementação e um componente próximo já aprovado. - Para estilos, leia a especificação detalhada de estilos, o arquivo de tokens de tempo de compilação, o arquivo de tema de tempo de execução e os estilos com escopo adjacentes. - Para mudanças de build, leia a configuração de build e o contrato de cada plugin personalizado antes de alterar o pipeline. - Para testes, leia a configuração dedicada de testes e os testes próximos; para documentação, leia a matriz de sincronização. - Resolva conflitos nesta ordem: código-fonte e configuração ativa, regras do repositório, documentação especializada e, por fim, experiência geral. - Quando o código-fonte e a documentação divergirem, siga o código-fonte e corrija a documentação desatualizada dentro do mesmo escopo aprovado. - Trate tabelas de referência rápida como indicações para as seções oficiais, não como cópias independentes das regras. - Nunca invente uma API nem dependa da memória para comportamentos sensíveis à versão; verifique a versão instalada e a documentação fornecida com ela. Antes da implementação, liste as exportações, os estilos, os testes, os registros de demos, os documentos e os invariantes de build afetados. ## Dê a cada componente uma pasta própria com código, estilos e testes Dê a cada componente uma pasta própria contendo sua implementação, seu arquivo de estilos com escopo, seu ponto de entrada de exportação e seu teste unitário colocado junto ao código. Adicione separadamente as exportações públicas de valores e de tipos e registre qualquer superfície de demo necessária. - Use componentes funcionais tipados, defina valores padrão na desestruturação dos parâmetros e estabeleça um nome de exibição estável. - Estenda os atributos do elemento nativo adequado e omita apenas os campos conflitantes. - Mantenha os nomes de componentes e tipos na capitalização canônica do repositório, os arquivos de estilo no formato de nome configurado e os nomes de classes com escopo na convenção de classes configurada. - Preserve a verificação estrita de null e as regras de módulos isolados; evite escapes sem tipagem e use exportações explícitas somente de tipos. - Mantenha os import no topo, use os aliases de projeto configurados e não coloque seletores globais em estilos de componentes com escopo. - Componha classes por meio do mapa de estilos com escopo ou do auxiliar de classes aprovado, em vez de codificar diretamente os nomes de classe gerados. - Mantenha os auxiliares reutilizáveis focados e coloque-os onde a convenção do repositório determina. Não altere a interface pública de um componente sem atualizar em conjunto suas exportações, seus testes, seus exemplos e a documentação da API. ## Use valores de design comuns para cores e cantos em vez de valores soltos Mantenha camadas de tokens separadas para funções diferentes: variáveis de tempo de compilação dão suporte a cálculos e mixins, enquanto propriedades CSS personalizadas em tempo de execução permitem que os consumidores substituam temas. Não trate as duas camadas como intercambiáveis. - Mantenha consistentes entre as configurações de build e de teste tanto a nomenclatura de CSS Modules quanto a injeção de tokens. - Prefira tokens semânticos de tempo de execução nos estilos dos componentes; use variáveis de tempo de compilação somente quando o pré-processamento for necessário. - Expresse cor, foco, raio, elevação, tipografia, peso e movimento pelos papéis semânticos do sistema, não por valores brutos isolados. - Evite extremos puros e padrões genéricos frios quando a linguagem visual definir superfícies tonalizadas, texto de cores quentes ou estados de foco próprios da marca. - Preserve silhuetas intencionais dos componentes, tratamentos de estado e regras de sombra, em vez de achatá-los em um único padrão genérico. - Mantenha fontes globais, variáveis de tema e redefinições atrás de um único ponto de entrada de estilos globais. - Respeite as preferências por movimento reduzido e preserve foco visível, uso pelo teclado, contraste legível e papéis de acessibilidade documentados. Obtenha os valores exatos e as exceções específicas dos componentes na especificação visual oficial e no código-fonte atual, nunca na memória. ## Teste o teclado e a acessibilidade de cada componente Use a configuração dedicada de testes do repositório com o ambiente DOM, os arquivos de preparação, os matchers, os aliases e o processamento de CSS Modules que ela declara. Não mova configurações de teste para uma configuração de build que o executor de testes ativo ignore. - Coloque os testes junto aos componentes e use os utilitários aprovados de renderização, consulta e interação do usuário. - Cubra renderização, classes orientadas por props, callbacks, comportamento desabilitado, mudanças de estado e papéis de acessibilidade relevantes. - Exercite o comportamento do teclado com as teclas exigidas pelo padrão do componente, incluindo movimento de foco, ativação, fechamento e controle direcional. - Verifique classes com escopo por meio do mapa de estilos importado, não por literais de string gerados. - Teste APIs imperativas invocando-as dentro do limite de estado do framework de testes e aguardando o resultado montado; não renderize como JSX uma API que não seja um componente. - Centralize os utilitários de teste compartilhados e use interações realistas do usuário em vez de atalhos de eventos de nível inferior. - Atinja os limites de cobertura configurados e documente qualquer exclusão intencional, em vez de inflar a cobertura com casos de pouco valor. Para um defeito, execute primeiro um teste focado que falhe, depois a suíte afetada e, por fim, toda a suíte obrigatória antes de concluir. ## Mantenha o build modular para carregar só os componentes usados Trate plugins de build personalizados, exportações de pacotes e regras de recursos como contratos com os consumidores. - Preserve saídas separadas de ES-module e CommonJS, com os limites dos módulos intactos, para que componentes não utilizados continuem removíveis por tree shaking. - Mantenha externos o framework e os pacotes auxiliares aprovados quando forem peer dependencies; não adicione runtime dependencies sem uma exigência explícita. - Preserve a divisão do código CSS e o mecanismo que associa os estilos de cada componente ao seu ponto de entrada JavaScript. - Mantenha completo o ponto de entrada da folha de estilos global e, ao mesmo tempo, impeça que recursos de componentes não utilizados entrem nos bundles dos consumidores. - Siga a política do repositório para cópia e incorporação de recursos, incluindo os requisitos de formato de fonte e public path. - Mantenha os mapas de exportação do pacote, os arquivos publicados e as declarações de efeitos colaterais alinhados com a estrutura gerada. - Altere a lógica de build somente depois de ler os contratos dos plugins personalizados e, em seguida, verifique tanto os import no nível dos componentes quanto o ponto de entrada de estilos globais. Os diretórios gerados de distribuição, build de demos e cobertura são saídas, não superfícies de autoria, e não devem ser incluídos em commits, a menos que a política do repositório determine explicitamente o contrário. ## Atualize a documentação e as demos sempre que um componente mudar Atualize toda superfície oficial afetada por uma mudança em um componente. - Mudanças em API ou props atualizam o manual da API a partir do código-fonte; mudanças de estilo atualizam a especificação detalhada de estilos. - Mudanças na linguagem visual atualizam o resumo de design, e novos componentes atualizam o prompt voltado ao usuário ou a especificação do catálogo. - Mudanças na quantidade de componentes ou na cobertura atualizam cada readme espelhado por meio do gerador aprovado. - O registro de demos pode estar dividido entre metadados de rota, um mapa de renderizadores e um catálogo da página inicial; atualize cada registro independente. - Derive contagens legíveis por máquina dos metadados oficiais, em vez de duplicá-las manualmente. - Execute o verificador de sincronização da documentação e entenda quais superfícies de demo ou geradas ele não inspeciona. - Regenere os artefatos rastreados por meio do comando aprovado, em vez de editar diretamente a saída gerada. Após mudanças de registro, verifique se a seleção da rota de demo renderiza a página pretendida; um menu destacado com a área principal vazia geralmente indica a ausência de uma entrada de registro. ## Evite falhas conhecidas como substituições em massa e páginas de demo em branco Use operações restritas e verificáveis em mudanças que possam corromper silenciosamente muitos arquivos. - Em substituições feitas por scripts, verifique cada alvo imediatamente, leve em conta que operações de string são imutáveis e evite padrões que falhem ao atravessar marcação entre aspas. - Quando uma ferramenta de teste gravar uma saída estruturada, forneça o caminho de saída exigido, em vez de pressupor um arquivo padrão. - Na captura de DOM para imagem, incorpore as declarações de fonte necessárias na raiz da captura quando o mecanismo de renderização não conseguir ler o registro de fontes do documento. - Não refatore dependências internas intencionais dos componentes apenas para melhorar uma métrica superficial de tree shaking. - Otimize o tamanho do pacote preservando import sob demanda e impedindo que recursos grandes, fontes e componentes não utilizados entrem nos bundles dos consumidores. - Diagnostique páginas de demo em branco verificando cada registro independente de páginas antes de alterar a implementação do componente. Converta cada falha recorrente confirmada em uma verificação automatizada e focada quando o repositório oferecer um local estável para ela. ## Passe em todas as verificações de CI antes de entregar a mudança Execute a verificação documentada do formatador, lint, testes unitários e o build da biblioteca na ordem exigida pelo repositório. Execute o comando completo de CI antes de propor uma contribuição. Confirme que: - todos os componentes, as exportações, os testes, a documentação e os registros de demos alterados estejam sincronizados; - os selos de cobertura ou de quantidade de componentes tenham sido regenerados quando suas entradas mudaram; - nenhuma runtime dependency nem saída gerada sem aprovação tenha entrado na mudança; - os contratos de saída modular, divisão de CSS e carregamento de recursos continuem válidos; - a mudança visual corresponda às especificações atuais de tokens e componentes; - a diferença final contenha somente as mudanças pretendidas no código-fonte e na documentação. Se qualquer verificação obrigatória falhar, corrija a falha e execute novamente o controle relevante antes de apresentar a diferença. Use o formato de contribuição do repositório e execute fluxos de lançamento ou publicação somente quando a tarefa os incluir explicitamente. Informe as verificações exatas executadas e quaisquer verificações mais amplas deixadas intencionalmente fora do escopo.