Crie ou altere componentes em uma biblioteca de componentes de UI com temas

## Encontre os arquivos que uma alteração de componente afeta Atue como uma pessoa colaboradora cuidadosa em uma biblioteca de componentes reutilizável, adaptável a temas e acessível. Antes de editar, identifique o comportamento solicitado, o componente ou utilitário afetado e todas as áreas diretamente relacionadas. Use a estrutura real do repositório, mas considere que uma alteração de componente pode abranger algumas destas áreas: - Componentes de execução e composables. - Tipos públicos e exportações. - Receitas de tema, variantes e valores padrão. - Testes unitários, de renderização, de snapshot e de acessibilidade. - Documentação e exemplos para usuários. - Um ambiente de experimentação local ou uma página de demonstração. Não presuma que todas as áreas precisam mudar. Rastreie o componente existente e seu equivalente mais próximo e, depois, liste apenas as áreas exigidas pela solicitação. Restrinja as convenções de código-fonte e de testes a esses diretórios; não as aplique indiscriminadamente à documentação, aos exemplos ou às ferramentas. Preserve o comportamento público existente, a menos que a tarefa o altere explicitamente. Trate o encaminhamento de atributos, a resolução de valores padrão, a semântica de acessibilidade, o comportamento da direita para a esquerda e as APIs documentadas como contratos, não como detalhes de implementação. ## Leia só os guias necessários e comece pelo gerador Leia primeiro as orientações de contribuição do repositório e, depois, carregue apenas as referências relevantes para a tarefa. Por exemplo, use as orientações de estrutura de componentes para props, slots, events e padrões de template; as orientações de tema para slots e variants; as orientações de testes para renderização, snapshots e acessibilidade; e as orientações de documentação para exemplos e marcação. Não carregue todas as referências apenas porque elas existem. Comece pelo arquivo afetado, examine uma implementação recente e comparável e abra orientações adicionais somente quando a alteração alcançar aquela questão. Use os scripts de pacote declarados pelo projeto e o gerenciador de pacotes compatível. Depois de instalar as dependências, execute qualquer etapa obrigatória de preparação ou geração de tipos antes de iniciar um ambiente de experimentação, o site de documentação ou as verificações. Use o ambiente local adequado para a alteração: o ambiente de experimentação do aplicativo principal, um ambiente para outro framework, um ambiente focado na reprodução do problema ou o site de documentação. Ao criar um componente, prefira o gerador aprovado pelo repositório. Revise os arquivos gerados antes de editá-los e solicite apenas os templates necessários para a tarefa. Se nenhum gerador for aplicável, reproduza manualmente a disposição de arquivos e as convenções de nomenclatura estabelecidas. ## Preserve a ordem dos padrões do tema e o layout da direita para a esquerda Siga de forma consistente as convenções de código estabelecidas pela biblioteca: - Mantenha separadas as importações exclusivas de tipos quando a cadeia de ferramentas ou o guia de estilo exigirem. - Defina os valores padrão das props em tempo de execução por meio do helper padrão e documente os valores padrão públicos na API voltada a tipos. - Adicione marcadores de slot estáveis aos elementos renderizados. No elemento raiz, um marcador fornecido pelo chamador deve prevalecer sobre o valor alternativo do componente; os elementos internos mantêm seus próprios marcadores. - Quando a propagação automática de atributos estiver desativada, ordene ou resolva os vínculos da raiz para que os atributos do chamador não sejam sobrescritos silenciosamente. - Crie uma saída de tema reativa por meio do mecanismo computado padrão, em vez de avaliar o estado do tema apenas uma vez. - Resolva os valores padrão por toda a cadeia de precedência: entrada explícita do componente, contexto de grupo ou campo mais próximo, substituições de tema no nível da biblioteca, valores padrão do componente e, por fim, configuração do aplicativo conforme definida pelo projeto. - Passe entradas brutas aos helpers de contexto quando convertê-las em proxies alteraria a precedência de injeção. Quando não houver um contexto mais próximo, use o valor resolvido do componente como alternativa, em vez de descartar um valor padrão do tema. - Encaminhe as props e events da biblioteca de primitivas pelo adaptador do projeto compatível com proxies para preservar os valores padrão resolvidos. Use tokens de design semânticos, não valores brutos da paleta. Use propriedades lógicas de espaçamento, posição, borda, raio e alinhamento de texto para que os layouts funcionem tanto em contextos da esquerda para a direita quanto da direita para a esquerda. Adicione alternativas explícitas que considerem a direção para transformações, cursores, gradientes ou transições quando as propriedades lógicas não puderem expressar o comportamento. Mantenha a implementação alinhada aos padrões existentes. Não introduza um sistema de valores padrão, um caminho de encaminhamento de props nem uma camada de resolução de temas concorrente para um único componente. ## Crie o componente com uma lista de verificação, do tema aos testes e à documentação Acompanhe um novo componente ou uma funcionalidade substancial de componente com uma lista de verificação: 1. Gere a estrutura inicial ou crie o componente no local padrão de execução. 2. Implemente o comportamento, as props públicas, os slots, os events e a semântica de acessibilidade. 3. Adicione ou atualize a receita de tema, incluindo slots, variants, variants compostas e tokens semânticos. 4. Exporte os tipos públicos e registre qualquer interface de valores padrão de componente exigida pelo sistema de temas. 5. Adicione testes específicos para comportamento, props, slots, encaminhamento de atributos, direcionalidade e acessibilidade, conforme aplicável. 6. Atualize a documentação para usuários com instruções de uso, exemplos e detalhes da API. 7. Adicione ou atualize um exemplo no ambiente de experimentação que demonstre o comportamento alterado. 8. Execute a análise estática, as verificações estáticas de tipos e o conjunto de testes relevante. Use snapshots apenas quando o projeto os tratar como um contrato útil e revise as alterações geradas, em vez de aceitá-las automaticamente. Mantenha os testes concentrados no comportamento externamente significativo e nas regras de precedência conhecidas. Quando a documentação for implantada antes do lançamento de um pacote, preserve o marcador de pré-lançamento aprovado pelo projeto nos títulos ou exemplos afetados. O marcador comunica intencionalmente que a documentação já integrada pode descrever uma funcionalidade que será disponibilizada no próximo lançamento; não o remova nem o informe como inconsistente sem verificar a política de lançamento. ## Rode o lint e os testes e abra o pull request com os resultados reais Compare o diff final com os padrões estabelecidos mais próximos e com a solicitação original. Verifique: - A estrutura do componente, os tipos públicos e as exportações são consistentes. - O código do tema usa tokens semânticos e preserva toda a cadeia de precedência dos valores padrão. - Os atributos da raiz e os marcadores de slot respeitam as substituições do chamador. - As propriedades lógicas ou variantes explícitas de direção abrangem o comportamento da direita para a esquerda. - Os testes abrangem as props, os slots, os comportamentos e os requisitos de acessibilidade alterados. - A documentação contém as instruções de uso, os exemplos e as alterações de API necessárias. - Os marcadores intencionais de pré-lançamento na documentação permanecem intactos. Execute os comandos de análise estática, verificação de tipos e testes relevantes do repositório e informe os resultados reais. Não afirme que as verificações foram aprovadas apenas com base em inspeção. Atualize a documentação quando o comportamento público mudar. Use a convenção obrigatória do repositório para mensagens de commit e o template de pull request. Vincule o item de trabalho relevante, identifique o tipo de alteração, descreva o comportamento e a verificação e conclua apenas os itens da lista de verificação respaldados por evidências. Não reescreva, faça `rebase`, use `force-push` nem compacte o histórico de commits de uma pessoa colaboradora apenas para deixá-lo organizado. Vários commits de desenvolvimento podem ser aceitáveis quando o repositório realiza um squash merge; siga a política real de merge do repositório e a autorização do usuário.