shadcn

Visão geral da skill shadcn

Para que serve a skill shadcn

A skill shadcn ajuda um assistente de IA a trabalhar corretamente dentro de projetos reais com shadcn/ui: localizar componentes, instalá-los com a CLI certa, montar telas a partir de primitivas já existentes e evitar erros comuns de API entre presets e famílias de componentes. Ela é mais útil quando você precisa de algo além de “gere um botão” e quer uma saída que respeite components.json, os itens de registry já instalados, seu template e as diferenças entre base e radix.

Quem deve usar esta skill shadcn

Os perfis com melhor aderência são:

• desenvolvedores que já usam shadcn/ui
• times adotando um fluxo de UI baseado em preset ou registry
• pessoas pedindo à IA para adicionar ou refatorar formulários, dialogs, páginas de configuração, dashboards ou temas
• qualquer pessoa que queira que o assistente inspecione o contexto do projeto antes de escrever JSX

Se você não usa shadcn/ui, components.json nem a CLI do shadcn, esta skill provavelmente é específica demais para o seu caso.

O trabalho real que ela resolve

Os usuários não querem apenas um resumo do repositório. Eles querem que o assistente:

1. detecte como o projeto está configurado com shadcn,
2. escolha componentes existentes antes de inventar novos,
3. use os comandos de CLI corretos e flags documentadas,
4. componha a UI seguindo os padrões preferidos da biblioteca,
5. evite quebras sutis, como composição errada de trigger, wrappers de grupo ausentes ou integração incorreta de validação em formulários.

É aí que esta skill shadcn entrega mais valor do que um prompt genérico de UI.

O que diferencia o shadcn de um prompt genérico

Os principais diferenciais são práticos:

• ela parte do contexto do projeto via npx shadcn@latest info --json
• prioriza search, view e docs antes de partir para implementação customizada
• incorpora regras do projeto a partir de arquivos como rules/composition.md, rules/forms.md, rules/styling.md e rules/base-vs-radix.md
• cobre temas e troca de preset, não só snippets de componentes
• inclui orientações de MCP para fluxos de busca em registry e instalação

Em resumo, a skill shadcn é menos sobre “escrever React” e mais sobre “escrever o React certo para esta configuração de shadcn”.

Restrições importantes para adoção

Antes de depender da skill, leve em conta estas restrições:

• ela assume acesso à CLI do shadcn via o runner de pacotes do projeto: npx, pnpm dlx ou bunx --bun
• ela está limitada às flags documentadas da CLI; a própria skill alerta contra inventar flags
• muitas boas saídas dependem de um components.json válido
• detalhes de API podem variar por preset e entre base e radix, então reutilizar exemplos às cegas pode dar errado

Como usar a skill shadcn

Contexto de instalação da skill shadcn

Adicione a skill ao seu ambiente de IA usando o fluxo padrão de instalação do diretório e depois use-a em um repositório que realmente tenha — ou pretenda ter — uma configuração shadcn. Na prática, o requisito do lado do repositório é mais importante do que o comando de instalação da skill: o assistente precisa ter acesso aos arquivos do projeto e deve conseguir executar comandos da CLI do shadcn.

Dentro do projeto de destino, os comandos de runtime relevantes são:

• npx shadcn@latest info --json
• npx shadcn@latest search <query>
• npx shadcn@latest view <item>
• npx shadcn@latest docs <component>
• npx shadcn@latest add <component>

Substitua por pnpm dlx shadcn@latest ou bunx --bun shadcn@latest se isso corresponder ao gerenciador de pacotes do projeto.

Leia estes arquivos primeiro antes de pedir qualquer saída

Para usar a skill shadcn com rapidez e precisão, inspecione estes arquivos mais ou menos nesta ordem:

1. SKILL.md
2. cli.md
3. rules/composition.md
4. rules/base-vs-radix.md
5. rules/forms.md
6. rules/styling.md
7. customization.md
8. mcp.md

Por que essa ordem funciona:

• SKILL.md define condições de acionamento e o fluxo de trabalho
• cli.md evita comandos e flags chutados
• os arquivos em rules/ capturam erros que geradores de código genéricos costumam cometer
• customization.md é importante quando você precisa de estilização segura para temas, não hacks com cores cruas do Tailwind
• mcp.md é importante quando seu assistente consegue navegar por registries via MCP em vez de depender apenas de shell

Comece toda tarefa com shadcn descobrindo o projeto

O melhor primeiro passo, disparado, é:

npx shadcn@latest info --json

Isso informa ao assistente o que já está configurado, incluindo o contexto de componentes e do projeto. É especialmente útil para:

• verificar se components.json existe
• identificar componentes já instalados
• detectar detalhes de configuração que mudam quais escolhas de código são válidas
• confirmar o runner de pacotes e evitar exemplos de comando incorretos

Se você pular essa etapa, a skill shadcn fica muito mais próxima de um prompt genérico.

Transforme um objetivo vago em um prompt shadcn forte

Prompt fraco:

Build me a profile dialog with shadcn.

Prompt melhor:

In this existing shadcn/ui app, inspect components.json and run npx shadcn@latest info --json first. We use the radix setup and lucide-react. Create a profile edit dialog using existing shadcn components only where possible. Include avatar, name, bio, Save/Cancel actions, accessible title, semantic tokens, and no raw color classes. If a component is missing, tell me the exact shadcn add command before generating code.

Por que este prompt é mais forte:

• ele força a descoberta do projeto
• especifica comportamentos sensíveis ao preset
• explicita restrições de ícones e estilização
• pede etapas de instalação quando faltarem dependências

Use search e docs antes de escrever código customizado

Um fluxo de trabalho shadcn de alta qualidade é:

1. buscar componentes existentes nos registries,
2. inspecionar docs e exemplos,
3. adicionar o que estiver faltando,
4. compor a tela.

Comandos práticos:

npx shadcn@latest search dialog
npx shadcn@latest docs dialog
npx shadcn@latest view @shadcn/dialog

Isso é especialmente importante para formulários, overlays, navegação e empty states, em que as regras da skill preferem padrões da biblioteca em vez de estruturas improvisadas com div.

Monte telas a partir de blocos já existentes

A skill shadcn funciona melhor quando você pede composição, não uma UI customizada monolítica. Boas formas de enquadrar a tarefa incluem:

• “settings page = Tabs + Card + form controls”
• “dashboard = Sidebar + Card + Chart + Table”
• “empty state = Empty component, not a custom centered div”
• “callout = Alert, not hand-rolled border boxes”

Isso espelha o fluxo preferido da skill: usar componentes existentes primeiro e só depois adaptar variantes e wrappers quando realmente necessário.

Respeite as diferenças entre base e radix

Um dos maiores bloqueios na adoção é assumir que todos os exemplos de shadcn são intercambiáveis. Não são.

A skill traz orientações explícitas para base vs radix, incluindo:

• asChild vs render
• diferenças na composição de trigger
• nativeButton={false} em casos específicos exclusivos de base
• diferenças de API em componentes como Select, ToggleGroup, Slider e Accordion

Se o seu prompt não disser qual setup está em uso, peça ao assistente para detectar isso com npx shadcn@latest info.

Use uma orientação de styling que sobreviva ao tema

Em shadcn para UI Design, os melhores resultados vêm de tokens semânticos e theming orientado por variáveis CSS, não de cores Tailwind fixas no código.

Prefira:

• bg-background
• text-foreground
• text-muted-foreground
• text-destructive

Evite recorrer por padrão a:

• bg-red-500
• text-gray-400
• um monte de overrides manuais com dark:

Isso importa porque customization.md explica que os componentes herdam de variáveis CSS. Se o assistente usar tokens semânticos, seu design escala com muito mais limpeza entre temas claro/escuro e diferentes presets.

Trate formulários do jeito shadcn

As evals e as regras mostram que a qualidade de formulários é um foco real. Em geral, um uso forte de shadcn para formulários significa:

• usar os padrões de layout de campo fornecidos, em vez de empilhar divs crus
• marcar estado inválido com data-invalid e aria-invalid
• usar Switch para preferências independentes de liga/desliga
• preferir espaçamento com gap-* em vez de space-y-* quando as regras pedirem isso

Se a sua tarefa inclui validação, diga isso explicitamente. Caso contrário, muitos assistentes geram formulários visualmente plausíveis, mas inconsistentes com a biblioteca.

Use MCP quando seu editor oferecer suporte

Se o seu ambiente oferecer suporte a MCP, a skill shadcn pode ficar mais confiável para operações de registry. mcp.md documenta ferramentas para:

• listar registries do projeto
• buscar itens de registry
• visualizar detalhes dos itens e conteúdo dos arquivos
• obter exemplos
• instalar itens

Isso é útil quando você quer que o assistente navegue pelos registries de forma conversacional, em vez de depender apenas da saída da CLI. Ainda assim, isso não substitui info --json para configuração do projeto.

Template prático de prompt para usar a skill shadcn

Use este template quando quiser uma saída de maior qualidade:

Use the shadcn skill for this task. First inspect the project with `npx shadcn@latest info --json` and read `components.json` if present. Confirm whether this project uses `base` or `radix`. Search for existing components before building custom UI. If something is missing, give the exact documented `shadcn add` command. Then generate the component using semantic tokens, correct composition rules, and the project’s icon library.

Goal: [what you want to build]
Screen context: [page/dialog/form/dashboard/etc.]
Existing components: [if known]
Framework/template: [Next.js/Vite/Astro/etc.]
Constraints: [icons, validation, dark mode, accessibility, no raw colors, no guessed APIs]
Output needed: [component code, install commands, explanation, refactor diff]

FAQ da skill shadcn

Esta skill shadcn serve só para instalar componentes?

Não. Tarefas de shadcn install fazem parte do escopo, mas a skill vai além: inspeção do projeto, busca em registry, composição de componentes, theming, debugging, troca de preset e refactors corretos do ponto de vista da API também entram no pacote.

A skill shadcn é amigável para iniciantes?

Sim, se você já tem alguma familiaridade com React e com um gerenciador de pacotes. A skill reduz tentativas no escuro ao direcionar o assistente para os comandos e regras certos. Ela é menos amigável para iniciantes se você precisa de uma introdução completa a React, Tailwind ou design systems do zero.

Quando vale mais usar shadcn do que um prompt normal?

Use a skill shadcn quando a correção depende do contexto do projeto:

• components.json existente
• compatibilidade com os componentes já instalados
• comportamento de base vs radix
• uso apenas de flags documentadas da CLI
• preservação de tokens de tema e regras de composição da biblioteca

Um prompt normal pode gerar JSX plausível, mas tem mais chance de ignorar etapas de instalação ou usar incorretamente as APIs dos componentes.

Quando você não deve usar a skill shadcn?

Ignore esta skill se:

• seu projeto não usa shadcn/ui
• você só precisa de mockups genéricos em HTML/CSS
• você quer uma resposta agnóstica de design system
• o assistente não consegue inspecionar arquivos nem executar comandos, e você não consegue fornecer manualmente o contexto necessário

Nesses casos, uma skill de frontend mais ampla pode ser a melhor escolha.

A skill ajuda em decisões de shadcn para UI Design?

Sim, especialmente em composição e theming. Ela direciona o assistente para primitivas reutilizáveis, tokens de cor semânticos, padrões corretos de overlay e estruturas de componentes que são mais fáceis de manter do que layouts artesanais feitos caso a caso.

O que costuma quebrar o uso de shadcn nas saídas de IA?

Falhas comuns incluem:

• inventar flags de CLI que não existem
• usar composição de trigger errada para base vs radix
• criar UI customizada em vez de usar um componente já existente no registry
• estilizar com cores cruas que brigam com o sistema de temas
• omitir subcomponentes obrigatórios, como titles, groups ou fallbacks

São exatamente esses pontos que esta skill foi feita para apertar.

Como melhorar a skill shadcn

Dê à skill shadcn o contexto que está faltando logo de início

A melhoria de maior impacto é fornecer uma entrada melhor. Inclua:

• framework ou template (next, vite, astro etc.)
• se components.json existe
• base ou radix, se isso já for conhecido
• conjunto atual de ícones
• componente ou tela alvo
• se a tarefa envolve instalação, refactor ou correção de bug

Mesmo uma única frase com contexto concreto já pode evitar que o assistente escolha APIs erradas.

Peça os comandos antes do código quando componentes puderem estar faltando

Se o seu projeto talvez ainda não tenha o componente necessário instalado, use um prompt assim:

Before writing code, check whether the required shadcn components are already present. If not, give me the exact add command and wait.

Isso melhora a saída porque separa mudanças de ambiente da implementação, deixando o resultado mais confiável e mais fácil de aplicar.

Force uma saída orientada por regras para tipos de componente mais frágeis

Para formulários, dialogs, dropdowns, sheets, drawers e selects, peça explicitamente que o assistente siga os arquivos de regras. Exemplo:

Follow the shadcn rules for composition, forms, and base-vs-radix differences. Do not simplify structure if it changes the component API.

Isso importa porque muitas gerações de baixa qualidade parecem corretas à primeira vista, mas quebram acessibilidade ou os contratos de composição.

Melhore o uso de shadcn especificando restrições de design

Um bom prompt de UI não é só “deixe moderno”. Inclua restrições como:

• usar apenas tokens semânticos
• nada de utilities de paleta crua
• o modo escuro precisa funcionar sem overrides manuais
• usar variantes já existentes antes de criar classes customizadas
• preferir empty states, alerts, separators, badges e skeletons da própria biblioteca

Esses detalhes melhoram de forma concreta a qualidade da primeira tentativa em trabalhos de shadcn para UI Design.

Itere com correções direcionadas, não com reescritas completas

Depois da primeira saída, evite dizer apenas “tente de novo”. Em vez disso, diga:

• “Refactor this to use installed shadcn components only.”
• “Make this valid for base, not radix.”
• “Replace raw color classes with semantic tokens.”
• “Add the missing title/fallback/group wrappers required by shadcn.”
• “Show the exact shadcn add commands for anything assumed.”

Isso preserva o que já está bom enquanto corrige as partes com maior chance de erro.

Valide com os sinais mais fortes do repositório

Para aumentar a confiança, compare a saída com:

• cli.md para comandos e flags
• rules/composition.md para estrutura
• rules/base-vs-radix.md para correção de API
• rules/forms.md para padrões de validação e layout
• rules/styling.md e customization.md para styling seguro em temas
• evals/evals.json para entender, na prática, o que parece uma boa saída

Esse é o caminho mais rápido para saber se a skill shadcn está produzindo algo alinhado ao repositório, em vez de apenas código de UI genérico.