shadcn/ui

O que ui faz?

Você é um especialista em shadcn/ui — uma coleção de componentes React lindamente projetados, acessíveis e customizáveis, construídos sobre as primitivas Radix UI e Tailwind CSS. Os componentes são adicionados diretamente ao seu código-fonte, e não instalados como uma dependência.

Conceito Chave

shadcn/ui não é uma biblioteca de componentes no sentido tradicional. Você não a instala como um pacote. Em vez disso, o CLI copia o código-fonte do componente para dentro do seu projeto, dando a você total propriedade e capacidade de customização.

Comandos do CLI

Inicializar (não interativo — SEMPRE use este)

IMPORTANTE: shadcn init é interativo por padrão. Sempre use -d (padrões) para inicialização não interativa:

# Inicialização não interativa com padrões — USE ESTE
npx shadcn@latest init -d

# Inicialização não interativa com um preset (recomendado para sistemas de design consistentes)
npx shadcn@latest init --preset <código> -f

# Inicialização não interativa com escolha explícita da biblioteca base
npx shadcn@latest init -d --base radix
npx shadcn@latest init -d --base base-ui

# Scaffold de um template de projeto completo (CLI v4)

Compatibilidade com AI Elements: Sempre use --base radix (o padrão) quando o projeto usar ou puder usar AI Elements. Os componentes do AI Elements dependem das APIs do Radix e podem apresentar erros de tipo com o Base UI.

npx shadcn@latest init --template next -d
npx shadcn@latest init --template vite -d

Opções:

• -d, --defaults — Usar configuração padrão, pular todos os prompts interativos (OBRIGATÓRIO para uso em CI/agente)
• -y, --yes — Pular prompts de confirmação (NÃO pula a seleção de bibliotecas — use -d)
• -f, --force — Forçar sobrescrita da configuração existente
• -t, --template — Scaffold de template de projeto completo (next, vite, react-router, astro, laravel, tanstack-start)
• --preset — Aplicar um preset de sistema de design (cores, tema, ícones, fontes, raio) como um único código compartilhável
• --base — Escolher biblioteca primitiva: radix (padrão) ou base-ui
• --monorepo — Configurar uma estrutura de monorepo

AVISO: -y/--yes sozinho NÃO torna o init totalmente não interativo — ele ainda solicita a seleção da biblioteca de componentes. Sempre use -d para pular TODOS os prompts.

Descontinuado no CLI v4: As flags --style, --base-color, --src-dir, --no-base-style e --css-variables foram removidas e causarão erro. Os tipos de registro registry:build e registry:mcp também estão obsoletos. Use registry:base e registry:font.

O comando init:

1. Detecta seu framework (Next.js, Vite, React Router, Astro, Laravel, TanStack Start)
2. Instala as dependências necessárias (Radix UI, tailwind-merge, class-variance-authority)
3. Cria o arquivo de configuração components.json
4. Configura a função utilitária cn()
5. Configura as variáveis CSS para temas

Adicionar Componentes

# Adicionar componentes específicos
npx shadcn@latest add button dialog card

# Adicionar todos os componentes disponíveis
npx shadcn@latest add --all

# Adicionar de um registro personalizado
npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @acme/custom-button

# Adicionar do registro AI Elements
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

Opções:

• -o, --overwrite — Sobrescrever arquivos existentes
• -p, --path — Caminho de instalação personalizado
• -a, --all — Instalar todos os componentes
• --dry-run — Visualizar o que será adicionado sem gravar arquivos
• --diff — Mostrar diff das alterações ao atualizar componentes existentes
• --view — Exibir o código-fonte de um item do registro inline

Pesquisar e Listar

npx shadcn@latest search button
npx shadcn@latest list @v0

Build (Registro Personalizado)

npx shadcn@latest build
npx shadcn@latest build ./registry.json -o ./public/r

Visualizar, Informações e Documentação (CLI v4)

# Visualizar o source de um item do registro antes de instalar
npx shadcn@latest view button

# Mostrar diagnóstico do projeto — configuração, componentes instalados, dependências
npx shadcn@latest info

# Obter docs, código e exemplos para qualquer componente (saída amigável para agentes)
npx shadcn@latest docs button
npx shadcn@latest docs dialog

shadcn docs dá aos agentes de codificação o contexto necessário para usar as primitivas corretamente — retorna exemplos de código, referência da API e padrões de uso inline.

Migrar

npx shadcn@latest migrate rtl    # Migração de suporte RTL
npx shadcn@latest migrate radix  # Migrar para o pacote unificado radix-ui
npx shadcn@latest migrate icons  # Alterações na biblioteca de ícones

# Migrar componentes fora do diretório ui padrão
npx shadcn@latest migrate radix src/components/custom

shadcn/skills (CLI v4)

shadcn/skills fornece aos agentes de codificação o contexto necessário para trabalhar corretamente com componentes e registros. Abrange tanto primitivas Radix quanto Base UI, APIs atualizadas, padrões de componentes e fluxos de trabalho de registro. A habilidade sabe como usar o CLI, quando invocá-lo e quais flags passar — para que os agentes produzam código que corresponda ao seu sistema de design.

Instalação: pnpm dlx skills add shadcn/ui

Pacote Radix UI Unificado (Fevereiro de 2026)

O estilo new-york agora usa um único pacote radix-ui em vez de pacotes individuais @radix-ui/react-*:

// ANTIGO — pacotes individuais
import * as DialogPrimitive from "@radix-ui/react-dialog"

// NOVO — pacote unificado
import { Dialog as DialogPrimitive } from "radix-ui"

Para migrar projetos existentes: npx shadcn@latest migrate radix. Após a migração, remova os pacotes @radix-ui/react-* não utilizados do package.json.

Suporte a Base UI (Janeiro de 2026)

shadcn/ui agora suporta Base UI como alternativa ao Radix UI para a biblioteca primitiva subjacente. Os componentes parecem e se comportam da mesma forma, independentemente de qual biblioteca você escolher — apenas a implementação subjacente muda.

Escolha durante o init: npx shadcn@latest init --base base-ui

O CLI puxa automaticamente a variante correta do componente com base na configuração do seu projeto.

Configuração (components.json)

O arquivo components.json configura como o shadcn/ui funciona no seu projeto:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "zinc",  // Opções: gray, neutral, slate, stone, zinc, mauve, olive, mist, taupe
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "v0": {
      "url": "https://v0.dev/chat/api/registry"
    },
    "ai-elements": {
      "url": "https://elements.ai-sdk.dev/api/registry"
    }
  }
}

Registros com Namespace

Configure vários registros para seu projeto:

{
  "registries": {
    "acme": {
      "url": "https://acme.com/registry/{name}.json"
    },
    "private": {
      "url": "https://internal.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Instale usando a sintaxe de namespace:

npx shadcn@latest add @acme/header @private/auth-form

Temas

Variáveis CSS

shadcn/ui usa propriedades customizadas CSS para temas, definidas em globals.css:

@theme inline {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-card: oklch(0.205 0 0);
  --color-card-foreground: oklch(0.985 0 0);
  --color-primary: oklch(0.488 0.243 264.376);
  --color-primary-foreground: oklch(0.985 0 0);
  --color-secondary: oklch(0.269 0 0);
  --color-secondary-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.269 0 0);
  --color-muted-foreground: oklch(0.708 0 0);
  --color-accent: oklch(0.269 0 0);
  --color-accent-foreground: oklch(0.985 0 0);
  --color-destructive: oklch(0.396 0.141 25.723);
  --color-border: oklch(0.269 0 0);
  --color-input: oklch(0.269 0 0);
  --color-ring: oklch(0.488 0.243 264.376);
  --radius: 0.625rem;
  /* CLI v4: tokens de raio usam cálculo multiplicativo em vez de aditivo */
  --radius-xs: calc(var(--radius) * 0.5);
  --radius-sm: calc(var(--radius) * 0.75);
  --radius-md: calc(var(--radius) * 0.875);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.5);
}

Modo Escuro

Para modo escuro, use a classe dark no <html>:

// app/layout.tsx
<html lang="en" className="dark">

Ou use next-themes para alternar:

import { ThemeProvider } from 'next-themes'

<ThemeProvider attribute="class" defaultTheme="dark">
  {children}
</ThemeProvider>

Cores Personalizadas

Adicione cores específicas da aplicação junto com os padrões do shadcn:

@theme inline {
  /* padrões shadcn acima... */

  /* Cores personalizadas da aplicação */
  --color-priority-urgent: oklch(0.637 0.237 15.163);
  --color-priority-high: oklch(0.705 0.213 47.604);
  --color-status-done: oklch(0.723 0.219 149.579);
}

Use nos componentes:

<span className="text-[var(--color-priority-urgent)]">Urgente</span>
// Ou com Tailwind v4 theme():
<span className="text-priority-urgent">Urgente</span>

Componentes Mais Comuns

Componente	Caso de Uso
button	Ações, envio de formulário
card	Contêineres de conteúdo
dialog	Modais, prompts de confirmação
input / textarea	Campos de formulário
select	Menus suspensos
table	Exibição de dados
tabs	Alternância de visualização
command	Paleta de comandos (Cmd+K)
dropdown-menu	Menus de contexto
popover	Conteúdo flutuante
tooltip	Dicas ao passar o mouse
badge	Indicadores de status
avatar	Imagens de perfil do usuário
scroll-area	Contêineres roláveis
separator	Divisores visuais
label	Rótulos de formulário
sheet	Painéis deslizantes
skeleton	Placeholders de carregamento

Direção de Design para shadcn na Vercel

shadcn/ui não é apenas um gerador de código-fonte de componentes. No stack da Vercel, é a linguagem de interface padrão. Não pare em "o componente funciona." Componha páginas que pareçam deliberadas, de alto sinal e consistentes.

Estética padrão para UI de produto

• Prefira o estilo: new-york para produto, dashboard, IA e superfícies administrativas.
• Por padrão, use modo escuro para dashboards, aplicativos de IA, ferramentas internas, configurações e produtos voltados para desenvolvedores. Use modo claro apenas quando o produto for claramente focado em conteúdo ou editorial.
• Use Geist Sans para texto de interface e Geist Mono para código, métricas, IDs, timestamps e comandos.
• Prefira zinc, neutral ou slate como paleta base. Use uma cor de destaque através de --color-primary.
• Construa superfícies principais a partir de tokens: bg-background, bg-card, text-foreground, text-muted-foreground, border-border, ring-ring. Evite valores hexadecimais ad-hoc.
• Mantenha o raio consistente. O padrão --radius: 0.625rem é uma linha de base forte.
• Use um sistema de densidade por página: confortável (gap-6 / p-6 / text-sm) ou compacto (gap-4 / p-4 / text-sm).
• Mantenha os ícones sóbrios e consistentes. Ícones Lucide em h-4 w-4 ou h-5 w-5.

Use isto primeiro

Caso de uso	Use isto primeiro	Por quê
Página de configurações	Tabs + Card + Form	Agrupamento claro de informações com fluxos de salvamento previsíveis
Dashboard de dados	Card + Badge + Table + DropdownMenu	Cobre resumo, status, dados densos e ações de linha sem shells personalizados
Tabela CRUD	Table + DropdownMenu + Sheet + AlertDialog	Suporta navegação, ação, edição e confirmação destrutiva em um padrão padrão
Tela de autenticação	Card + Label + Input + Button + Alert	Mantém fluxos de entrada focados e dá aos erros um tratamento adequado
Pesquisa global	Command + Dialog	Descoberta rápida baseada em teclado com um modelo de interação estabelecido
Navegação móvel	Sheet + Button + Separator	Fornece um shell de navegação compacto que se adapta perfeitamente a telas pequenas
Página de detalhes	cabeçalho + Badge + Separator + Card	Equilibra hierarquia, metadados e conteúdo de suporte sem aninhamento excessivo
Filtros	sidebar Card + Sheet + Select	Funciona para filtros persistentes em desktop e controles colapsáveis em dispositivos móveis
Estados vazio/carregamento/erro	Card + Skeleton + Alert	Dá a caminhos não felizes uma superfície projetada em vez de texto placeholder

Receitas de composição

• Página de configurações: Tabs + Card por grupo + Separator + ação de salvar
• Dashboard administrativo: Cards de resumo + barra de filtro + Table
• Detalhe de entidade: cabeçalho + Badge de status + Card principal + Card lateral + AlertDialog para ações destrutivas
• Pesquisa intensiva: Command para busca rápida, Popover para seletores, Sheet para filtros móveis
• Autenticação/onboarding: Card centralizado + Separator social + Alert inline para erros
• Fluxos destrutivos: AlertDialog (não Dialog) para confirmação

Anti-padrões a evitar

• button / input / select / div puro quando primitivas shadcn existem
• div rounded-xl border p-6 repetido em vez de Tabs / Table / Sheet / Dialog
• Múltiplas cores de destaque competindo entre si
• Cards aninhados dentro de cards dentro de cards
• Fundos gradientes grandes e efeito glassmorphism em toda superfície
• Misturar valores arbitrários de espaçamento e raio
• Usar Dialog para confirmação destrutiva em vez de AlertDialog
• Enviar estados vazio/carregamento/erro sem tratamento de design
• Usar classes de paleta Tailwind ad-hoc para superfícies fundamentais em vez de tokens de tema

Construindo um Registro Personalizado

Crie seu próprio registro de componentes para compartilhar entre projetos:

Tipos de Registro (CLI v4)

Tipo	Propósito
registry:ui	Componentes de UI individuais
registry:base	Payload completo do sistema de design — componentes, deps, vars CSS, fontes, configuração
registry:font	Configuração de fonte como um item de registro de primeira classe

1. Defina registry.json

[

…

[truncated for translation]