Guia Pratico

Tailwind CSS + shadcn/ui

Setup, componentes e boas praticas em projetos Next.js / React

Um guia direto ao ponto de como configuro e uso Tailwind CSS com shadcn/ui nos meus projetos. Sem enrolacao -- so o que realmente funciona no dia a dia.

Aviso: Este conteudo reflete como eu uso essas ferramentas no dia a dia e pode estar desatualizado em relacao as versoes mais recentes. Sempre consulte a documentacao oficial para informacoes atualizadas.

Setup Inicial

Como configuro do zero

O passo a passo que sigo pra iniciar qualquer projeto Next.js com Tailwind + shadcn/ui ja configurado e pronto pra produzir.

Criar o projeto com Next.js

Uso o create-next-app com TypeScript, Tailwind e App Router ja habilitados de fabrica.

step-1

npx create-next-app@latest meu-projeto --typescript --tailwind --eslint --app --src-dir

Inicializar o shadcn/ui

O CLI do shadcn configura tudo automaticamente: paths, tokens, CSS variables e a pasta components/ui.

step-2

npx shadcn@latest init

Adicionar componentes conforme a necessidade

Nunca instalo tudo de uma vez. Vou adicionando so o que o projeto precisa.

step-3

npx shadcn@latest add button card input dialog
npx shadcn@latest add table form select textarea

Configurar o tema no globals.css

Customizo as CSS variables do tema (cores, radius, fontes) direto no globals.css. Isso garante consistencia em todo o projeto.

step-4

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 240 10% 3.9%;
    --primary: 240 5.9% 10%;
    --primary-foreground: 0 0% 98%;
    --radius: 0.5rem;
  }
}

Componentes na Pratica

Exemplos reais do dia a dia

Esses sao padroes que uso em praticamente todo projeto. Componentes do shadcn compostos com Tailwind de forma limpa e reutilizavel.

Card com hover e badge

Card reutilizavel com efeito hover sutil, badge de status e layout flexbox. Uso muito em listagens de projetos e dashboards.

Card com hover e badge

<Card className="group border-border bg-card/50 transition-colors hover:border-primary/20">
  <CardHeader className="pb-2">
    <div className="flex items-center justify-between">
      <CardTitle className="text-base">Titulo</CardTitle>
      <Badge variant="secondary">Ativo</Badge>
    </div>
  </CardHeader>
  <CardContent>
    <p className="text-sm text-muted-foreground">Descricao aqui</p>
  </CardContent>
</Card>

Botoes com variantes

O sistema de variantes do shadcn e muito poderoso. Combino com classes utilitarias pra criar botoes consistentes.

Botoes com variantes

<div className="flex gap-3">
  <Button>Primario</Button>
  <Button variant="secondary">Secundario</Button>
  <Button variant="outline" className="gap-1.5">
    <Github className="h-4 w-4" />
    GitHub
  </Button>
  <Button variant="ghost" size="icon">
    <Sun className="h-4 w-4" />
  </Button>
</div>

Form com validacao (React Hook Form + Zod)

Essa e a stack que mais uso pra formularios: shadcn Form + React Hook Form + Zod. Type-safe, validacao automatica e UX consistente.

Form com validacao (React Hook Form + Zod)

const formSchema = z.object({
  email: z.string().email("Email invalido"),
  name: z.string().min(2, "Minimo 2 caracteres"),
})
 
<Form {...form}>
  <FormField name="email" render={({ field }) => (
    <FormItem>
      <FormLabel>Email</FormLabel>
      <FormControl>
        <Input placeholder="seu@email.com" {...field} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )} />
</Form>

Padroes que Sigo

Convencoes que mantem o codigo limpo

Composicao ao inves de props gigantes

Prefiro compor componentes menores do que criar um com 20 props. Mais legivel, testavel e facil de manter.

Composicao ao inves de props gigantes

// Ruim: <Card title="..." subtitle="..." icon="..." badge="..." />
 
// Bom:
<Card>
  <CardHeader>
    <CardTitle>Titulo</CardTitle>
    <CardDescription>Subtitulo</CardDescription>
  </CardHeader>
  <CardContent>...</CardContent>
</Card>

cn() pra classes condicionais

Uso o helper cn() (clsx + twMerge) pra combinar classes de forma segura, sem conflito entre Tailwind classes.

cn() pra classes condicionais

import { cn } from "@/lib/utils"
 
<div className={cn(
  "rounded-lg border p-4 transition-colors",
  isActive && "border-primary bg-primary/5",
  isDisabled && "opacity-50 pointer-events-none"
)} />

Tokens semanticos ao inves de cores hardcoded

Nunca uso bg-white ou text-gray-500 direto. Sempre uso os tokens semanticos (bg-background, text-muted-foreground) pra garantir que dark mode funcione.

Tokens semanticos ao inves de cores hardcoded

// Ruim:
<div className="bg-white text-gray-900 border-gray-200">
 
// Bom:
<div className="bg-background text-foreground border-border">

Responsivo mobile-first

Sempre comeco pelo mobile e vou subindo. O Tailwind facilita muito isso com os prefixos md: e lg:.

Responsivo mobile-first

<div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
  <Card>...</Card>
  <Card>...</Card>
  <Card>...</Card>
</div>

Do vs Don't

Erros comuns que vejo em projetos

Espacamento

p-[16px] mx-[8px] mt-[24px]

p-4 mx-2 mt-6

Use a escala do Tailwind. Valores arbitrarios sujam o codigo e quebram a consistencia do spacing.

Cores

bg-white text-black dark:bg-gray-900

bg-background text-foreground

Tokens semanticos adaptam automaticamente ao tema. Nunca hardcode cores.

Layout

float-left position: absolute (pra layout)

flex items-center justify-between gap-4

Flexbox resolve 90% dos layouts. Reserve absolute/fixed pra overlays e tooltips.

Spacing entre filhos

space-y-4 (pode dar conflito)

flex flex-col gap-4

Gap e mais previsivel e nao conflita com margin de componentes filhos.

Links Uteis

Documentacao oficial e referencias

Tailwind CSS Docs

Documentacao oficial do Tailwind CSS com exemplos, referencias de classes e guias de configuracao.

shadcn/ui

Biblioteca de componentes reutilizaveis construidos com Radix UI e Tailwind CSS. Codigo aberto e customizavel.

Next.js Docs

Documentacao oficial do Next.js com App Router, Server Components e muito mais.

Radix UI

Primitivos de UI acessiveis e sem estilo que formam a base dos componentes do shadcn/ui.

Tailwind CSS IntelliSense

Extensao do VS Code com autocomplete, linting e preview de classes Tailwind.

clsx + tailwind-merge

Combinacao que uso no helper cn() para merge seguro de classes Tailwind sem conflitos.

Curtiu as dicas?

Se quiser trocar uma ideia sobre Tailwind, shadcn/ui ou qualquer coisa de frontend, me chama!

Voltar às Dicas

Conteúdo relacionado

Dicas de IA para DesenvolvedoresGuia prático de ferramentas IA, uso consciente de tokens e modelos: v0, Copilot, prompt engineering, boas práticas e ferramentas para produtividade dev.

React Query Essencial — Cache e MutationsGuia completo de TanStack Query (React Query): cache inteligente, mutations, invalidação, otimistic updates e boas práticas para apps React.

Recursos para Desenvolvedores — Jr, Pleno e SeniorSnippets, comparações before/after, padrões de código e playground interativo filtrado por nível: junior, pleno e senior.

10 min de leitura

<CardTitle className="text-base">Titulo</CardTitle>

<Badge variant="secondary">Ativo</Badge>

</div>

</CardHeader>

<p className="text-sm text-muted-foreground">Descricao aqui</p>

</CardContent>

</Card>

<Button>Primario</Button>

<Button variant="secondary">Secundario</Button>

GitHub

</Button>

</Button>

</div>

const formSchema = z.object({

email: z.string().email("Email invalido"),

name: z.string().min(2, "Minimo 2 caracteres"),

})

<FormField name="email" render={({ field }) => (

<FormLabel>Email</FormLabel>

</FormControl>

</FormItem>

)} />

</Form>

// Ruim: <Card title="..." subtitle="..." icon="..." badge="..." />

// Bom:

<Card>

<CardTitle>Titulo</CardTitle>

<CardDescription>Subtitulo</CardDescription>

</CardHeader>

</Card>