shadcn/ui

Uma framework para construir interfaces de usuário, componentes e sistemas de design. Os componentes são adicionados como código-fonte ao 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 gerenciador correto para o seu projeto.

Quando Usar

• Use ao adicionar novos componentes do shadcn/ui ou de registros da comunidade.
• Use ao estilizar, compor ou depurar componentes existentes do shadcn/ui.
• Use ao inicializar um novo projeto ou trocar presets de sistema de design.
• Use para obter documentação de componentes, exemplos e referências de API.

Contexto Atual do Projeto

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`

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

Princípios

1. Use componentes existentes primeiro. Use npx shadcn@latest search para verificar os registros antes de escrever UI personalizada. Verifique também os registros da comunidade.
2. Componha, não reinvente. Página de configurações = Tabs + Card + controles de formulário. Dashboard = Sidebar + Card + Chart + Table.
3. Use variantes integradas antes de estilos personalizados. variant="outline", size="sm", etc.
4. 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 se conecta 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 forem iguais. size-10 e não w-10 h-10.
• Use a abreviação truncate. Não overflow-hidden text-ellipsis whitespace-nowrap.
• Sem sobrescrita manual de cores dark:. Use tokens semânticos (bg-background, text-muted-foreground).
• Use cn() para classes condicionais. Não escreva ternários manuais em template literals.
• Sem z-index manual em componentes de sobreposição. Dialog, Sheet, Popover, etc. cuidam de sua própria 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 use 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 um div com um título.
• Validação de campo usa data-invalid + aria-invalid. data-invalid em Field, aria-invalid no controle. Para desabilitado: data-disabled em 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 Título. DialogTitle, SheetTitle, DrawerTitle são necessários para acessibilidade. Use className="sr-only" se visualmente oculto.
• Use composição completa de Card. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Não despeje 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 falha ao carregar.

Use Componentes, Não Markup Personalizado → composition.md

• Use componentes existentes antes de markup personalizado. Verifique se um componente existe antes de escrever um div estilizado.
• Callouts usam Alert. Não construa divs estilizados personalizados.
• Estados vazios usam Empty. Não construa markup de estado vazio personalizado.
• Toast via sonner. Use toast() de sonner.

…