Padrões ShadCN UI – Novembro de 2025
Quando Usar
- Criar novos componentes de interface
- Refatorar componentes existentes para usar ShadCN
- Implementar formulários com validação
- Criar modais, diálogos e sobreposições
- Garantir conformidade com acessibilidade
Por que ShadCN UI?
- Copie e cole, não npm - Propriedade total do código do componente
- Primitivos Radix UI - Acessibilidade nativa (conformidade WCAG 2.1 AA)
- Primeiro TailwindCSS - Personalização completa, sem CSS-in-JS
- Nativo TypeScript - Props e variantes type-safe
- Compatível com Server Components - Funciona com Next.js 15 App Router
Princípios Fundamentais
1. Padrão de Instalação de Componentes
# Instale componentes individuais conforme necessário
npx shadcn@latest add button
npx shadcn@latest add dialog
npx shadcn@latest add form
npx shadcn@latest add input
npx shadcn@latest add label
Os componentes são copiados para src/components/ui/ – você é dono do código.
2. Padrões de Uso de Componentes
Componente Button
import { Button } from "@/components/ui/button"
// ✅ FAÇA: Use variantes semânticas
<Button variant="default">Salvar</Button>
<Button variant="destructive">Excluir</Button>
<Button variant="outline">Cancelar</Button>
<Button variant="ghost">Pular</Button>
<Button variant="link">Saiba Mais</Button>
// ✅ FAÇA: Use variantes de tamanho
<Button size="default">Médio</Button>
<Button size="sm">Pequeno</Button>
<Button size="lg">Grande</Button>
<Button size="icon"><Icon /></Button>
// ❌ NÃO FAÇA: Criar botões personalizados sem usar o componente Button
<button className="px-4 py-2 bg-blue-500">Ruim</button>
Componente Dialog/Modal
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog"
// ✅ FAÇA: Use a estrutura adequada do diálogo (acessibilidade)
<Dialog>
<DialogTrigger asChild>
<Button>Abrir Configurações</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Configurações</DialogTitle>
<DialogDescription>
Configure as configurações da sua aplicação aqui.
</DialogDescription>
</DialogHeader>
{/* Conteúdo do diálogo */}
</DialogContent>
</Dialog>
// ❌ NÃO FAÇA: Pular DialogHeader ou DialogTitle (quebra leitores de tela)
<DialogContent>
<h2>Configurações</h2> {/* Errado - use DialogTitle */}
</DialogContent>
Componente Form (com React Hook Form + Zod)
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import {
Form,
FormControl,
FormDescription,
FormField,
FormItem,
FormLabel,
FormMessage,
} from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"
// ✅ FAÇA: Defina o schema Zod primeiro (validação)
const formSchema = z.object({
email: z.string().email("Endereço de e-mail inválido"),
password: z.string().min(8, "A senha deve ter pelo menos 8 caracteres"),
})
function LoginForm() {
const form = useForm<z.infer<typeof formSchema>>({
resolver: zodResolver(formSchema),
defaultValues: {
email: "",
password: "",
},
})
async function onSubmit(values: z.infer<typeof formSchema>) {
// Dados validados type-safe
console.log(values)
}
return (
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
<FormField
control={form.control}
name="email"
render={({ field }) => (
<FormItem>
<FormLabel>E-mail</FormLabel>
<FormControl>
<Input placeholder="[email protected]" {...field} />
</FormControl>
<FormDescription>
Nunca compartilharemos seu e-mail.
</FormDescription>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name="password"
render={({ field }) => (
<FormItem>
<FormLabel>Senha</FormLabel>
<FormControl>
<Input type="password" {...field} />
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<Button type="submit">Entrar</Button>
</form>
</Form>
)
}
// ❌ NÃO FAÇA: Usar formulários não controlados sem validação
<form>
<input name="email" /> {/* Sem validação */}
</form>
3. Componentes Server vs Client
// ✅ FAÇA: Use Server Component para diálogos estáticos
import { Dialog, DialogContent } from "@/components/ui/dialog"
export default function ServerDialog() {
// Não precisa de 'use client'
return <Dialog>...</Dialog>
}
// ✅ FAÇA: Use Client Component quando estado for necessário
'use client'
import { useState } from 'react'
import { Dialog, DialogContent } from "@/components/ui/dialog"
export function ClientDialog() {
const [open, setOpen] = useState(false)
return (
<Dialog open={open} onOpenChange={setOpen}>
<DialogContent>...</DialogContent>
</Dialog>
)
}
4. Requisitos de Acessibilidade
Gerenciamento de Foco
// ✅ FAÇA: Use DialogTrigger com asChild para foco adequado
<DialogTrigger asChild>
<Button>Abrir</Button>
</DialogTrigger>
// ❌ NÃO FAÇA: Acionar manualmente sem tratamento adequado de foco
<Button onClick={() => setOpen(true)}>Abrir</Button>
Navegação por Teclado
// ✅ ShadCN lida com isso automaticamente:
// - ESC fecha diálogos
// - Tab navega pelos elementos focalizáveis
// - Enter/Space ativa botões
// - Setas navegam em menus
// ❌ NÃO FAÇA: Sobrescrever o comportamento padrão do teclado sem boa razão
Suporte a Leitores de Tela
// ✅ FAÇA: Sempre inclua DialogTitle (necessário para ARIA)
<DialogHeader>
<DialogTitle>Excluir Projeto</DialogTitle>
<DialogDescription>
Esta ação não pode ser desfeita.
</DialogDescription>
</DialogHeader>
// ❌ NÃO FAÇA: Usar títulos ocultos visualmente de forma incorreta
<DialogTitle className="sr-only">Excluir</DialogTitle>
// Só oculte se houver uma alternativa visual clara
5. Componentes Comuns para Usar
| Componente | Caso de Uso | Props Principais |
|---|---|---|
Button | Todas as ações clicáveis | variant, size, asChild |
Dialog | Modais, confirmações | open, onOpenChange |
Sheet | Painéis laterais, gavetas | side, open, onOpenChange |
Popover | Dicas, menus | open, onOpenChange |
Form | Todos os formulários | form (do useForm) |
Input | Entrada de texto | type, placeholder |
Select | Menus suspensos | value, onValueChange |
Checkbox | Entrada booleana | checked, onCheckedChange |
RadioGroup | Escolha única | value, onValueChange |
Table | Tabelas de dados | table (do TanStack Table) |
Card | Contêineres de conteúdo | CardHeader, CardContent, CardFooter |
Toast | Notificações | title, description, variant |
Command | Paleta de comandos | onSelect |
Tabs | Navegação por abas | value, onValueChange |
6. Boas Práticas TailwindCSS
// ✅ FAÇA: Use classes utilitárias Tailwind
<Button className="w-full mt-4">Enviar</Button>
// ✅ FAÇA: Use o helper cn() para classes condicionais
import { cn } from "@/lib/utils"
<Button className={cn(
"w-full",
isLoading && "opacity-50 cursor-not-allowed"
)}>
Enviar
</Button>
// ❌ NÃO FAÇA: Usar estilos inline
<Button style={{ width: '100%', marginTop: '16px' }}>Enviar</Button>
// ❌ NÃO FAÇA: Criar arquivos CSS personalizados para componentes
// styles.css
.my-button { width: 100%; }
7. Suporte a Modo Escuro
// ✅ FAÇA: Use classes de modo escuro do Tailwind
<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
Conteúdo
</div>
// ✅ Os componentes ShadCN têm modo escuro nativo
<Button variant="default">
{/* Estilizado automaticamente para modo escuro */}
</Button>
Erros Comuns a Evitar
❌ DialogTitle Ausente (Violação de Acessibilidade)
// RUIM
<DialogContent>
<h2>Configurações</h2>
<p>Conteúdo</p>
</DialogContent>
// BOM
<DialogContent>
<DialogHeader>
<DialogTitle>Configurações</DialogTitle>
</DialogHeader>
<p>Conteúdo</p>
</DialogContent>
❌ Não Usar o Componente Form para Formulários
// RUIM - Sem validação, UX pobre
<form>
<input name="email" />
<button type="submit">Enviar</button>
</form>
// BOM - Validação, mensagens de erro, acessibilidade
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)}>
<FormField name="email" ... />
</form>
</Form>
❌ Codificar Cores em Vez de Usar Variantes
// RUIM
<Button className="bg-red-500 hover:bg-red-600">Excluir</Button>
// BOM
<Button variant="destructive">Excluir</Button>
❌ Não Usar asChild para Gatilhos
// RUIM - Cria botões aninhados desnecessários
<DialogTrigger>
<Button>Abrir</Button>
</DialogTrigger>
// Renderiza: <button><button>Abrir</button></button> (HTML inválido)
// BOM - Mescla props em um único botão
<DialogTrigger asChild>
<Button>Abrir</Button>
</DialogTrigger>
// Renderiza: <button>Abrir</button>
Testando Componentes ShadCN
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { Dialog, DialogTrigger, DialogContent } from '@/components/ui/dialog'
describe('Dialog', () => {
it('deve abrir quando o gatilho for clicado', async () => {
const user = userEvent.setup()
render(
<Dialog>
<DialogTrigger asChild>
<button>Abrir</button>
</DialogTrigger>
<DialogContent>
<div>Conteúdo do diálogo</div>
</DialogContent>
</Dialog>
)
// Conteúdo do diálogo não deve estar visível inicialmente
expect(screen.queryByText('Conteúdo do diálogo')).not.toBeInTheDocument()
// Clique no gatilho
await user.click(screen.getByText('Abrir'))
// Conteúdo do diálogo agora deve estar visível
expect(screen.getByText('Conteúdo do diálogo')).toBeInTheDocument()
})
it('deve fechar com a tecla ESC', async () => {
const user = userEvent.setup()
render(
<Dialog defaultOpen>
<DialogContent>Conteúdo do diálogo</DialogContent>
</Dialog>
)
expect(screen.getByText('Conteúdo do diálogo')).toBeInTheDocument()
await user.keyboard('{Escape}')
expect(screen.queryByText('Conteúdo do diálogo')).not.toBeInTheDocument()
})
})
Recursos
- Documentação Oficial: https://ui.shadcn.com
- Radix UI: https://www.radix-ui.com
- Exemplos: https://ui.shadcn.com/examples
- Temas: https://ui.shadcn.com/themes
Nota de Novembro de 2025
O ShadCN UI é o padrão da indústria para bibliotecas de componentes React em Novembro de 2025. Todas as novas aplicações Quetrex devem usar ShadCN UI para consistência, acessibilidade e manutenibilidade.