shadcn/ui

Um framework para construir UI, componentes e sistemas de design. Os componentes são adicionados como código-fonte no projeto do usuário via CLI.

IMPORTANTE: Execute todos os comandos da CLI usando o gerenciador de pacotes do projeto: npx shadcn@latest, pnpm dlx shadcn@latest, ou bunx --bun shadcn@latest — com base no packageManager do projeto. Os exemplos abaixo usam npx shadcn@latest mas substitua pelo executor correto para o projeto.

Contexto do Projeto Atual

!`npx shadcn@latest info --json`

O JSON acima contém a configuração do projeto e os componentes instalados. Use npx shadcn@latest docs <componente> para obter URLs de documentação e exemplos para qualquer componente.

Princípios

Use componentes existentes primeiro. Use npx shadcn@latest search para verificar registros antes de escrever UI personalizada. Verifique também os registros da comunidade.
Componha, não reinvente. Página de configurações = Tabs + Card + controles de formulário. Dashboard = Sidebar + Card + Chart + Table.
Use variantes nativas antes de estilos personalizados. variant="outline", size="sm", etc.
Use cores semânticas. bg-primary, text-muted-foreground — nunca valores brutos como bg-blue-500.

Regras Críticas

Estas regras são sempre aplicadas. Cada uma vincula a um arquivo com pares de código Incorreto/Correto.

Estilização & Tailwind → styling.md

className para layout, não para estilização. Nunca sobrescreva cores ou tipografia de componentes.
Sem space-x-* ou space-y-*. Use flex com gap-*. Para pilhas verticais, flex flex-col gap-*.
Use size-* quando largura e altura são iguais. size-10 não w-10 h-10.
Use o atalho truncate. Não overflow-hidden text-ellipsis whitespace-nowrap.
Sem substituições manuais de dark:. Use tokens semânticos (bg-background, text-muted-foreground).
Use cn() para classes condicionais. Não escreva ternários manuais de template literal.
Sem z-index manual em componentes de sobreposição. Dialog, Sheet, Popover, etc. gerenciam seu próprio empilhamento.

Formulários & Inputs → forms.md

Formulários usam FieldGroup + Field. Nunca use div bruto com space-y-* ou grid gap-* para layout de formulário.
InputGroup usa InputGroupInput/InputGroupTextarea. Nunca Input/Textarea brutos dentro de InputGroup.
Botões dentro de inputs usam InputGroup + InputGroupAddon.
Conjuntos de opções (2–7 escolhas) usam ToggleGroup. Não faça loop de Button com estado ativo manual.
FieldSet + FieldLegend para agrupar checkboxes/radios relacionados. Não use uma div com um título.
Validação de campo usa data-invalid + aria-invalid. data-invalid no Field, aria-invalid no controle. Para desabilitado: data-disabled no Field, disabled no controle.

Estrutura de Componentes → composition.md

Itens sempre dentro de seu Grupo. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
Use asChild (radix) ou render (base) para gatilhos personalizados. Verifique o campo base de npx shadcn@latest info. → base-vs-radix.md
Dialog, Sheet e Drawer sempre precisam de um Title. DialogTitle, SheetTitle, DrawerTitle obrigatório para acessibilidade. Use className="sr-only" se estiver visualmente oculto.
Use a composição completa de Card. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Não coloque tudo em CardContent.
Button não tem isPending/isLoading. Componha com Spinner + data-icon + disabled.
TabsTrigger deve estar dentro de TabsList. Nunca renderize gatilhos diretamente em Tabs.
Avatar sempre precisa de AvatarFallback. Para quando a imagem falhar ao carregar.

Use Componentes, Não Marcação Personalizada → composition.md

Use componentes existentes antes de marcação personalizada. Verifique se um componente existe antes de escrever uma div estilizada.
Callouts usam Alert. Não construa divs estilizadas personalizadas.
Estados vazios usam Empty. Não construa marcação de estado vazio personalizada.
Toast segue a base do projeto. Use toast do componente toast para projetos Base UI. Use toast() de sonner para projetos Radix e React Aria.
Use Separator em vez de <hr> ou <div className="border-t">.
Use Skeleton para placeholders de carregamento. Sem divs animate-pulse personalizadas.
Use Badge em vez de spans estilizados personalizados.

Ícones → icons.md

Ícones em Button usam data-icon. data-icon="inline-start" ou data-icon="inline-end" no ícone.
Sem classes de dimensionamento em ícones dentro de componentes. Os componentes lidam com o dimensionamento de ícones via CSS. Sem size-4 ou w-4 h-4.
Passe ícones como objetos, não chaves de string. icon={CheckIcon}, não uma pesquisa de string.

Chat & Mensagens → chat.md

Chat UI compõe os primitivos de chat. Conversas usam MessageScroller, linhas usam Message, superfícies usam Bubble. Nunca divs de bolha feitas à mão ou um contêiner de rolagem bruto.
MessageScroller é dono do comportamento de rolagem. Acompanhamento de streaming, ancoragem e salto para o mais recente (MessageScrollerButton) são nativos. Não escreva um hook useStickToBottom/ResizeObserver.
Anexos usam Attachment; notas de sistema e divisores usam Marker. Não cartões Item ou Separator + um rótulo.

CLI

Nunca decodifique códigos de preset ou construa URLs de preset manualmente. Use npx shadcn@latest preset decode <código>, preset url <código>, ou preset open <código>. Para detecção de preset ciente do projeto, use npx shadcn@latest preset resolve.
Aplique códigos de preset diretamente com a CLI. Use npx shadcn@latest apply <código> para projetos existentes, ou npx shadcn@latest init --preset <código> ao inicializar.

Padrões Chave

Estes são os padrões mais comuns que diferenciam o código shadcn/ui correto. Para casos extremos, veja os arquivos de regras vinculados acima.

// Layout de formulário: FieldGroup + Field, não div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validação: data-invalid no Field, aria-invalid no controle.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Email inválido.</FieldDescription>
</Field>

// Ícones em botões: data-icon, sem classes de dimensionamento.
<Button>
  <SearchIcon data-icon="inline-start" />
  Pesquisar
</Button>

// Espaçamento: gap-*, não space-y-*.
<div className="flex flex-col gap-4">  // correto
<div className="space-y-4">           // errado

// Dimensões iguais: size-*, não w-* h-*.
<Avatar className="size-10">   // correto
<Avatar className="w-10 h-10"> // errado

// Cores de status: variantes de Badge ou tokens semânticos, não cores brutas.
<Badge variant="secondary">+20.1%</Badge>    // correto
<span className="text-emerald-600">+20.1%</span> // errado

Seleção de Componentes

Necessidade	Use
Botão/ação	`Button` com variante apropriada
Inputs de formulário	`Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider`
Alternar entre 2–5 opções	`ToggleGroup` + `ToggleGroupItem`
Exibição de dados	`Table`, `Card`, `Badge`, `Avatar`
Navegação	`Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`
Sobreposições	`Dialog` (modal), `Sheet` (painel lateral), `Drawer` (folha inferior), `AlertDialog` (confirmação)
Feedback	`toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner`
Paleta de comandos	`Command` dentro de `Dialog`
Gráficos	`Chart` (envolve Recharts)
Layout	`Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`
Estados vazios	`Empty`
Menus	`DropdownMenu`, `ContextMenu`, `Menubar`
Dicas/informações	`Tooltip`, `HoverCard`, `Popover`
UI de chat / conversa	`MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker`

Campos Chave

O contexto do projeto injetado contém estes campos chave:

aliases → use o prefixo de alias real para importações (ex: @/, ~/), nunca codifique.
isRSC → quando true, componentes que usam useState, useEffect, manipuladores de eventos ou APIs de navegador precisam de "use client" no topo do arquivo. Sempre consulte este campo ao aconselhar sobre a diretiva.
tailwindVersion → "v4" usa blocos @theme inline; "v3" usa tailwind.config.js.
tailwindCssFile → o arquivo CSS global onde as variáveis CSS personalizadas são definidas. Sempre edite este arquivo, nunca crie um novo.
style → tratamento visual do componente (ex: nova, vega).
base → biblioteca de primitivos (radix ou base). Afeta as APIs do componente e as props disponíveis.
iconLibrary → determina as importações de ícone. Use lucide-react para lucide, @tabler/icons-react para tabler, etc. Nunca presuma lucide-react.
resolvedPaths → destinos exatos do sistema de arquivos para componentes, utilitários, hooks, etc.
framework → roteamento e convenções de arquivo (ex: Next.js App Router vs Vite SPA).
packageManager → use este para qualquer instalação de dependência que não seja shadcn (ex: pnpm add date-fns vs npm install date-fns).
preset → código de preset resolvido e valores para o projeto atual. Use npx shadcn@latest preset resolve --json quando você precisar apenas de informações de preset.

Veja cli.md — comando info para a referência completa de campos.

Documentação, Exemplos e Uso de Componentes

Execute npx shadcn@latest docs <componente> para obter as URLs da documentação, exemplos e referência de API de um componente. Busque essas URLs para obter o conteúdo real.

npx shadcn@latest docs button dialog select

Ao criar, corrigir, depurar ou usar um componente, sempre execute npx shadcn@latest docs e busque as URLs primeiro. Isso garante que você esteja trabalhando com a API correta e os padrões de uso, em vez de adivinhar.

Fluxo de Trabalho

Obtenha o contexto do projeto — já injetado acima. Execute npx shadcn@latest info novamente se precisar atualizar.
Verifique os componentes instalados primeiro — antes de executar add, sempre verifique a lista de components do contexto do projeto ou liste o diretório resolvedPaths.ui. Não importe componentes que não foram adicionados e não readicione aqueles já instalados.
Encontre componentes — npx shadcn@latest search.
Obtenha docs e exemplos — execute npx shadcn@latest docs <componente> para obter URLs, depois busque-as. Use npx shadcn@latest view para navegar pelos itens do registro que você não instalou. Para visualizar alterações em componentes instalados, use npx shadcn@latest add --diff.
Instale ou atualize — npx shadcn@latest add. Ao atualizar componentes existentes, use --dry-run e --diff para visualizar as alterações primeiro (veja Atualizando Componentes abaixo).
Corrija importações em componentes de terceiros — Após adicionar componentes de registros da comunidade (ex: @bundui, @magicui), verifique os arquivos não-UI adicionados para caminhos de importação codificados como @/components/ui/.... Eles não corresponderão aos aliases reais do projeto. Use npx shadcn@latest info para obter o alias ui correto (ex: @workspace/ui/components) e reescreva as importações de acordo. A CLI reescreve importações para seus próprios arquivos UI, mas componentes de registro de terceiros podem usar caminhos padrão que não correspondem ao projeto.
Revise os componentes adicionados — Após adicionar um componente ou bloco de qualquer registro, sempre leia os arquivos adicionados e verifique se estão corretos. Verifique subcomponentes ausentes (ex: SelectItem sem SelectGroup), importações ausentes, composição incorreta ou violações das Regras Críticas. Substitua também quaisquer importações de ícone pela iconLibrary do projeto a partir do contexto do projeto (ex: se o item do registro usa lucide-react mas o projeto usa hugeicons, troque as importações e nomes de ícones de acordo). Corrija todos os problemas antes de prosseguir.
Registro deve ser explícito — Quando o usuário pedir para adicionar um bloco ou componente, não adivinhe o registro. Se nenhum registro for especificado (ex: o usuário diz "adicione um bloco de login" sem especificar @shadcn, @tailark, owner/repo, etc.), pergunte qual registro usar. Nunca escolha um registro padrão em nome do usuário.
Alternando presets — Pergunte primeiro ao usuário: substituir, parcial, mesclar ou pular?
- Inspecione o preset atual: npx shadcn@latest preset resolve. Use --json quando precisar de valores estruturados.
- Inspecione o preset recebido: npx shadcn@latest preset decode <código>. Use preset url <código> ou preset open <código> para compartilhar ou abrir o construtor de presets.
- Substituir: npx shadcn@latest apply <código>. Substitui componentes, fontes e variáveis CSS detectados.
- Parcial: npx shadcn@latest apply <código> --only theme,font. Atualiza apenas as partes selecionadas do preset sem reinstalar componentes de UI. Os valores suportados são theme e font; combinações separadas por vírgula são permitidas. icon intencionalmente não é suportado, porque alterações de ícone podem exigir reinstalação completa do componente.

Atualizando Componentes

Sempre visualize as alterações de atualização antes de confirmá-las:

npx shadcn@latest add <componente> --dry-run --diff

Depois prossiga com:

npx shadcn@latest add <componente>

O modo Diff mostra uma prévia lado a lado, ajudando a detectar conflitos de personalização.

Registros de Componentes

Use npx shadcn@latest search para listar itens de todos os registros disponíveis. Para registrar um registro personalizado, veja registry.md.

Contexto

Esta skill fornece regras e contexto abrangentes para construir aplicações shadcn/ui. O contexto do projeto é injetado automaticamente (veja npx shadcn@latest info --json) e contém a configuração do seu projeto, componentes instalados e aliases de caminho. Use npx shadcn@latest docs <componente> para buscar documentação e exemplos atualizados antes de usar qualquer componente.

shadcn-ui/ui

O que é ui?

Perguntar na sua IA favorita

Documentação