shadcn/ui Skill: componentes sem sobrescrever mudanças locais

ANÁLISE EDITORIAL

A Skill oficial do shadcn/ui ensina um agente a trabalhar com componentes que pertencem ao próprio projeto, em vez de tratar a biblioteca como uma caixa preta. Ela começa lendo a configuração real, consulta a documentação adequada ao estilo e ao framework, procura componentes existentes e compara a mudança antes de escrever arquivos.

Esse detalhe importa porque o shadcn/ui distribui código-fonte para dentro da aplicação. O componente passa a ser editável pela equipe, mas uma adição ou atualização descuidada pode substituir mudanças locais. A Skill reduz improviso, não elimina a necessidade de revisão. Esta página explica um caminho seguro, com projeto de teste, --dry-run, --diff e confirmação humana antes de sobrescrever código.

O que esta Skill faz de verdade

O SKILL.md oficial organiza o uso do CLI shadcn e da documentação do projeto. Primeiro manda executar npx shadcn@latest info --json para descobrir framework, estilo, biblioteca base, ícones, aliases e componentes já instalados. Depois orienta a consultar documentação e exemplos, pesquisar registries, compor a interface e só então adicionar ou atualizar arquivos.

A Skill também contém regras para formulários, ícones, estilização, composição, chat e a diferença entre projetos baseados em Radix e Base UI. Ela não gera uma interface automaticamente e não garante que qualquer exemplo servirá no seu projeto. Seu papel é fornecer um procedimento e restrições para que o agente trabalhe com o contexto correto.

O ponto mais útil é a proteção de código local. A fonte recomenda examinar mudanças com --dry-run e --diff e pedir confirmação antes de sobrescrever um componente. Isso é especialmente relevante em aplicações onde arquivos adicionados pelo CLI foram adaptados para acessibilidade, identidade visual ou regras de negócio.

Para quem serve

Ela serve a desenvolvedores e equipes de produto que usam shadcn/ui em projetos React compatíveis e querem delegar parte da descoberta, instalação ou composição de componentes a um agente. É útil quando o repositório já tem components.json, convenções próprias e componentes locais que precisam ser preservados.

Também ajuda quem está começando um projeto e precisa evitar uma mistura incoerente de estilos, bibliotecas base ou conjuntos de ícones. O agente pode ler o estado real antes de sugerir comandos. Para uma equipe experiente, o ganho está na disciplina: registrar o componente solicitado, a documentação consultada, o diff e a decisão de aplicar.

Não é uma boa escolha para projetos sem React compatível, para quem espera componentes hospedados e imutáveis ou para fluxos que autorizam escrita cega em produção. Se a equipe não revisa código de terceiros nem mantém testes de interface, a Skill não corrige essa lacuna.

Compatibilidade e pré-requisitos

A compatibilidade depende do CLI e das opções atuais do shadcn/ui, não apenas do arquivo da Skill. Antes de qualquer alteração, confirme o framework, o gerenciador de pacotes e o arquivo components.json. A documentação oficial de components.json explica campos como estilo, aliases, CSS, biblioteca base e configuração de ícones.

• Node.js e um gerenciador de pacotes compatíveis com o projeto.
• Um repositório de teste ou branch de trabalho, nunca a produção sem revisão.
• Permissão para baixar o pacote executado por npx e acessar registries aprovados.
• Conhecimento do framework, do CSS global e dos aliases usados na aplicação.
• Testes ou roteiro visual para conferir comportamento, responsividade e acessibilidade.
• Um cliente capaz de carregar Agent Skills, caso o uso seja feito por agente.

O projeto oficial documenta a instalação em diferentes frameworks na área de instalação. Verifique essa página no dia do uso. O commit auditado registra o conteúdo da Skill, mas não congela o pacote resolvido por @latest.

Instalação recomendada

Comece em uma cópia controlada do projeto e faça commit do estado limpo. Em seguida, inspecione o ambiente sem adicionar componente:

npx shadcn@latest info --json

Esse comando pode baixar e executar uma versão do pacote por meio do npx. Revise a origem e a política da sua organização antes de aceitar o download. Para conhecer as opções atuais, consulte a referência oficial do CLI.

A instalação da Skill no agente depende do cliente usado. O pacote local do Bastidores é documental. Ele não instala Node.js, o CLI, componentes, dependências ou registries. Abra o ZIP, leia o SKILL.md e as referências e copie apenas os documentos necessários para o diretório de Skills do seu cliente.

Configuração antes do primeiro uso

Leia o resultado de info --json e compare com o repositório. Confirme o estilo, a biblioteca base, o conjunto de ícones, os aliases de componentes e utilitários, o caminho do CSS e a lista de itens já instalados. Se o arquivo estiver ausente ou incoerente, pare e corrija o projeto antes de pedir ao agente que componha uma tela.

Registries merecem uma decisão explícita. O shadcn/ui aceita fontes além do catálogo padrão, e um registry pode entregar código que será incorporado ao projeto. A documentação oficial de registries mostra o formato e os casos de uso. Trate cada origem como fornecedora de código: aprove domínio, revise licença, leia arquivos e fixe uma referência quando o processo exigir reprodutibilidade.

Defina também o limite do agente. Uma política prática permite leitura, pesquisa e geração de diff, mas exige confirmação para instalar pacotes, escrever componentes, substituir arquivos, mudar CSS global ou alterar configuração. O repositório e o CI continuam sendo a fonte de verdade.

Primeiro uso seguro

Escolha um componente pequeno em uma branch descartável. Peça ao agente para descrever a intenção e identificar a documentação antes de executar. Depois use a prévia:

npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff

As opções disponíveis podem mudar. Confirme na ajuda do CLI e não presuma que todo comando oferece o mesmo conjunto de flags. O objetivo é enxergar arquivos, dependências e diferenças antes da escrita.

Se o projeto já tem um botão local, compare o código existente com a proposta. Preserve variantes, testes e contratos públicos. Autorize a aplicação somente quando o diff estiver compreendido. Depois rode lint, testes, build e uma revisão visual real em larguras de tela relevantes.

Como o fluxo deve funcionar

1. O agente lê components.json e executa info --json.
2. Ele consulta a documentação ou o registry aplicável, sem inventar API.
3. Ele pesquisa se o projeto já possui componente equivalente.
4. Ele propõe a composição com arquivos, dependências e riscos declarados.
5. Ele usa prévia e diff antes de qualquer sobrescrita.
6. Uma pessoa aprova a escrita e revisa o resultado no Git.
7. A equipe executa testes técnicos e inspeção visual em ambiente de desenvolvimento.

A Skill oficial reforça composição em vez de grandes componentes monolíticos. Para exemplos e APIs atuais, use a lista oficial de componentes. Não copie uma demonstração sem adaptar dados, estados vazios, loading, erros, teclado e leitores de tela.

Resultado esperado

Ao final de um primeiro uso bem-sucedido, você deve ter uma alteração pequena e explicável: componente correto para o estilo do projeto, dependências conhecidas, diff revisado, build funcional e evidência visual em ambiente de teste. O agente deve conseguir dizer quais fontes consultou e quais arquivos tocou.

O resultado esperado não é uma interface perfeita em um comando. shadcn/ui entrega blocos que a equipe possui e adapta. Qualidade continua dependendo de conteúdo, hierarquia, responsividade, estados, acessibilidade e consistência com o produto.

Permissões, privacidade e riscos

npx shadcn@latest pode acessar a rede, baixar e executar um pacote, ler a configuração do projeto e, em comandos de adição, escrever código e instalar dependências. Registries externos podem fornecer arquivos executáveis no contexto da aplicação. Aprove as origens e nunca trate um nome familiar como prova de segurança.

O agente pode ler código proprietário, nomes internos e caminhos do projeto. Evite enviar o repositório a serviços não aprovados. Não coloque tokens de registry, variáveis de ambiente ou dados de usuário no prompt. Se um componente lida com autenticação, pagamentos ou dados pessoais, amplie a revisão de segurança.

Há também risco de regressão silenciosa. Uma atualização pode substituir acessibilidade, eventos, classes ou contratos que não aparecem numa captura. Proteja o estado com Git, diff, testes e confirmação humana. A Skill oficial fixada no commit é a referência auditada nesta página.

Erros comuns

O agente usa componentes ou APIs inexistentes. Pare e exija consulta à documentação atual. Use o comando de documentação indicado pela Skill e confira a documentação oficial.

O CLI quer sobrescrever um arquivo modificado. Não confirme automaticamente. Gere o diff, preserve as alterações locais e integre manualmente quando necessário.

O estilo visual não combina com o projeto. Verifique components.json, CSS global, tokens e biblioteca base. Não misture exemplos de configurações diferentes sem adaptação.

Um registry não responde ou entrega código inesperado. Interrompa a instalação, valide o domínio, a documentação e a licença. Não substitua por outra origem só para concluir a tarefa.

O build passa, mas a interface quebra. Teste estados de foco, teclado, conteúdo longo, telas pequenas, carregamento e erro. Build não substitui revisão visual e acessibilidade.

Versão, licença e origem verificadas

A curadoria consultou o repositório oficial em 01/09/2026. O projeto registrava 122.709 estrelas na API pública do GitHub, acima do piso editorial de 1.000. Estrelas são um sinal de adoção, não uma auditoria de segurança. O repositório estava ativo e identificava licença MIT.

O conteúdo foi fixado no commit 63c1308d112b6b1205d86244a156cca1abef5087, no caminho skills/shadcn. Consulte o diretório oficial da Skill no commit, o registro do commit e a licença MIT fixada.

O ZIP local contém somente doze documentos: SKILL.md, cli.md, customization.md, registry.md, seis regras, LICENSE.md e ORIGEM.md. Não inclui CLI, componentes, código do produto, imagens, configurações de agente, avaliações, dependências, executáveis, segredos ou dados. SHA-256 do arquivo: f5fa484c0aa1ef6ae1904eb711844a0c9390258151296b6aca4a91beeb911280.

Checklist antes de automatizar

• Confirme que o projeto e o framework são compatíveis.
• Leia components.json e o resultado de info --json.
• Aprove a origem de cada registry e dependência.
• Trabalhe em branch ou projeto de teste com estado limpo no Git.
• Use --dry-run e --diff quando o comando suportar.
• Não autorize sobrescrita sem revisar mudanças locais.
• Rode lint, testes, build, inspeção visual e acessibilidade.
• Registre commit, comando, arquivos alterados e decisão humana.

Fontes primárias

• Repositório oficial shadcn/ui.
• Skill oficial fixada no commit auditado.
• CLI oficial.
• Configuração oficial de components.json.
• Registries oficiais.