Skill de Tailwind v4 + shadcn/ui - Uma receita de skill para Claude Code para dominar a arquitetura de componentes e estilização do Tailwind CSS v4 e shadcn/ui

Q: Qual é a maior mudança de configuração do Tailwind v3 para o v4?

Tailwind v4 usa um modelo de configuração CSS-first via @theme no seu arquivo CSS tailwind.config.js é opcional e não é mais o padrão Valores de tema personalizados (cores, fontes, raios, breakpoints) são definidos diretamente no CSS

Q: Como definir valores de tema personalizados no Tailwind v4?

Use a diretiva @theme dentro do seu arquivo CSS Propriedades CSS personalizadas seguem o padrão --nome-categoria: valor

Q: Quais recursos foram removidos ou alterados no Tailwind v4?

@apply é desencorajado (use extração de componentes em vez disso) Função theme() substituída por variáveis CSS bg-opacity-* substituído por sintaxe de barra como bg-black/50 Largura do anel padrão alterada (ring-3 em vez de ring)

Q: O que é a utilidade cn() e por que ela é importante para shadcn/ui?

Combina clsx (classes condicionais) com twMerge (resolve conflitos do Tailwind) Sem twMerge, classes conflitantes como p-4 e p-6 seriam aplicadas ambas

Q: Como você deve personalizar componentes shadcn/ui?

Edite os arquivos de origem diretamente em components/ui/ - eles vivem na sua base de código Estenda adicionando variantes ao arquivo do componente, não crie componentes de wrapper Use variáveis CSS para temas e cn() para classes condicionais

Q: Como funciona o modo escuro com shadcn/ui e Tailwind v4?

shadcn usa a estratégia class (classe .dark no elemento html), não media (prefers-color-scheme) Defina variáveis claras em :root e substituições escuras em .dark Use next-themes para o toggle, configurado para corresponder à estratégia class

Q: Armadilha: Por que as container queries podem não funcionar com os prefixos @sm: e @lg:?

Container queries exigem @container no elemento pai Sem a classe @container no pai, @sm:, @md:, @lg: não responderão Esta é uma falha comum ao adotar container queries do Tailwind v4

Q: Quais novos recursos CSS estão integrados ao Tailwind v4?

Container queries: @container, @sm, @md, @lg Transformações 3D: rotate-x-, rotate-y-, perspective-* text-wrap-balance, text-wrap-pretty field-sizing-content para textareas de auto-dimensionamento Suporte nativo a aninhamento CSS

Q: Armadilha: O que acontece se você adicionar classes Tailwind personalizadas, mas não configurar o tailwind-merge?

twMerge não reconhecerá suas classes personalizadas Classes personalizadas conflitantes podem não ser resolvidas corretamente Você precisa configurar tailwind-merge para reconhecer quaisquer classes utilitárias personalizadas que você definir

Q: Como tipar a prop className para um componente estilo shadcn em TypeScript?

Estenda React.HTMLAttributes para herdar className e todas as props nativas de div

Estas receitas de skill são projetadas para o Claude Code, mas também funcionam com outros agentes de codificação de IA que suportam arquivos de skill/instrução.

Receita

O conteúdo completo do SKILL.md que você pode copiar para .claude/skills/tailwind-v4-shadcn/SKILL.md:

---
name: tailwind-v4-shadcn
description: "Domine a arquitetura e estilização de componentes do Tailwind CSS v4 + shadcn/ui. Use quando solicitado: ajuda com tailwind, componente shadcn, estilização, temas, modo escuro, variáveis CSS, design responsivo, animação, configuração do Tailwind v4."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Bash(pnpm:*), Agent"
---
 
# Tailwind v4 + shadcn/ui
 
Você é um especialista em Tailwind CSS v4 e shadcn/ui. Forneça orientação autoritativa sobre estilização, temas e arquitetura de componentes.
 
## Principais Mudanças do Tailwind v4 em relação ao v3
 
O Tailwind v4 usa um modelo de configuração CSS-first. Não há mais `tailwind.config.js` por padrão.
 
### Configuração CSS-First
```css
/* app/globals.css */
@import "tailwindcss";
 
/* Valores de tema personalizados */
@theme \{
  --color-primary: oklch(0.7 0.15 240);
  --color-primary-foreground: oklch(0.98 0.01 240);
  --color-secondary: oklch(0.6 0.1 280);
  --color-secondary-foreground: oklch(0.98 0.01 280);
  --color-accent: oklch(0.8 0.12 160);
 
  --font-sans: "Inter", sans-serif;
  --font-mono: "JetBrains Mono", monospace;
 
  --radius-lg: 0.75rem;
  --radius-md: 0.5rem;
  --radius-sm: 0.25rem;
 
  --breakpoint-xs: 30rem;
 
  --animate-slide-in: slide-in 0.3s ease-out;
\}
 
@keyframes slide-in \{
  from \{ transform: translateY(10px); opacity: 0; \}
  to \{ transform: translateY(0); opacity: 1; \}
\}

Recursos Removidos no v4

tailwind.config.js é opcional (CSS-first via @theme)
@apply é desencorajado (use extração de componentes em vez disso)
Função theme() substituída por variáveis CSS
Padrão de largura de anel alterado (ring-3 em vez de ring)
bg-opacity-* substituído pela sintaxe bg-black/50

Novo no v4

Container queries integradas: @container, @sm, @md, @lg
Transformações 3D: rotate-x-*, rotate-y-*, perspective-*
text-wrap-balance, text-wrap-pretty
field-sizing-content para textareas de auto-dimensionamento
color-scheme-* para esquemas de cores do sistema
Modo escuro automático via @media (prefers-color-scheme: dark)
Suporte nativo a aninhamento CSS

Arquitetura shadcn/ui

Padrão de Instalação

npx shadcn@latest init
npx shadcn@latest add button card dialog form input

Regras de Customização de Componentes

Edite a origem - Componentes shadcn vivem na sua base de código em components/ui/. Modifique-os diretamente.
Estenda, não envolva - Adicione variantes ao arquivo do componente, não crie componentes de wrapper.
Use variáveis CSS para temas - Todas as cores devem referenciar variáveis CSS para suporte ao modo escuro.
Componha com cn() - Use a utilidade cn() (clsx + twMerge) para classes condicionais.

Utilitário cn()

import \{ clsx, type ClassValue \} from "clsx";
import \{ twMerge \} from "tailwind-merge";
 
export function cn(...inputs: ClassValue[]) \{
  return twMerge(clsx(inputs));
\}
 
// Uso
<div className=\{cn(
  "rounded-lg border p-4",
  isActive && "border-primary bg-primary/10",
  className // permite sobrescrita pelo pai
)\} />

Padrão de Composição de Componentes

// components/ui/card.tsx - base do shadcn
const Card = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
  (\{ className, ...props \}, ref) => (
    <div
      ref=\{ref\}
      className=\{cn(
        "rounded-lg border bg-card text-card-foreground shadow-sm",
        className
      )\}
      \{...props\}
    />
  )
);
 
// Seu componente composto
function ProductCard(\{ product \}: \{ product: Product \}) \{
  return (
    <Card className="hover:shadow-md transition-shadow">
      <CardHeader>
        <CardTitle>\{product.name\}</CardTitle>
        <CardDescription>\{product.category\}</CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-2xl font-bold">$\{product.price\}</p>
      </CardContent>
      <CardFooter>
        <Button className="w-full">Add to Cart</Button>
      </CardFooter>
    </Card>
  );
\}

Tematização com Variáveis CSS

Configuração de Tema shadcn

/* app/globals.css */
@import "tailwindcss";
 
@theme inline \{
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
\}
 
:root \{
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --radius: 0.625rem;
\}
 
.dark \{
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.145 0 0);
  --card-foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.269 0 0);
  --input: oklch(0.269 0 0);
  --ring: oklch(0.439 0 0);
\}

Toggle de Modo Escuro

"use client";
 
import \{ useTheme \} from "next-themes";
import \{ Button \} from "@/components/ui/button";
import \{ Moon, Sun \} from "lucide-react";
 
export function ThemeToggle() \{
  const \{ theme, setTheme \} = useTheme();
 
  return (
    <Button
      variant="ghost"
      size="icon"
      onClick=\{() => setTheme(theme === "dark" ? "light" : "dark")\}
    >
      <Sun className="h-5 w-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
      <Moon className="absolute h-5 w-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
      <span className="sr-only">Alternar tema</span>
    </Button>
  );
\}

Padrões Responsivos

// Design responsivo mobile-first
<div className="
  grid
  grid-cols-1        // mobile: coluna única
  sm:grid-cols-2     // 640px+: 2 colunas
  lg:grid-cols-3     // 1024px+: 3 colunas
  xl:grid-cols-4     // 1280px+: 4 colunas
  gap-4
  p-4 sm:p-6 lg:p-8
">
 
// Container queries (novo no v4)
<div className="@container">
  <div className="@sm:flex @sm:gap-4 @lg:grid @lg:grid-cols-3">
    \{/* Responde à largura do container, não ao viewport */\}
  </div>
</div>

Padrões de Animação

// Animações integradas do Tailwind
<div className="animate-spin" />     // spinner
<div className="animate-pulse" />    // carregamento de esqueleto
<div className="animate-bounce" />   // atenção
 
// Animações personalizadas com @theme
// Em globals.css:
// @theme \{ --animate-fade-in: fade-in 0.5s ease-out; \}
// @keyframes fade-in \{ from \{ opacity: 0; \} to \{ opacity: 1; \} \}
<div className="animate-fade-in" />
 
// Padrões de transição
<button className="
  transition-colors duration-200
  bg-primary hover:bg-primary/90
  active:scale-95 transition-transform
" />
 
// Para animações complexas, use Framer Motion com Tailwind
import \{ motion \} from "framer-motion";
 
<motion.div
  initial=\{\{ opacity: 0, y: 20 \}\}
  animate=\{\{ opacity: 1, y: 0 \}\}
  className="rounded-lg border bg-card p-6"
/>

Padrões Anti-Estilização Comuns

Usar @apply extensivamente - Extraia componentes em vez de @apply
Cores codificadas - Sempre use variáveis CSS ou tokens de tema
Não usar cn() - Conflitos de classe sem twMerge causam estilos inesperados
Envolver componentes shadcn - Modifique o arquivo de origem ou use a prop className
Ignorar o modo escuro - Sempre teste com ambos os temas; use nomes de cores semânticos
Usar valores arbitrários com muita frequência - w-[347px] é um sinal de alerta; use a escala de design
Estilos inline ao lado do Tailwind - Escolha um sistema; misturar causa sobrecarga de manutenção


## Exemplo de Trabalho

### Exemplo 1: Usuário pergunta "Ajude-me a configurar temas para meu aplicativo"

**Prompt do usuário:** "Quero um aplicativo com tema azul e suporte a modo escuro usando shadcn/ui."

**Resposta guiada pela skill produziria:**
- Variáveis CSS para uma paleta de cores azul em oklch
- Definições de tema claro e escuro
- Configuração do provedor `next-themes`
- Componente de alternância de tema
- Componentes de exemplo usando os tokens de tema

### Exemplo 2: Usuário pergunta "Como personalizo um Button do shadcn?"

**Prompt do usuário:** "Quero adicionar uma variante 'gradient' ao Button do shadcn."

**Resposta guiada pela skill produziria:**

```tsx
// components/ui/button.tsx - Adicionar às variantes existentes
const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
        // NOVO: variante gradient
        gradient: "bg-gradient-to-r from-primary to-accent text-primary-foreground hover:opacity-90",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
);

Mergulho Profundo

Como a Skill Funciona

Esta skill fornece:

Conhecimento de migração do Tailwind v4 - Todas as mudanças do v3 para o v4 e como configurar
Arquitetura shadcn/ui - Customização de componentes, composição e padrões de tematização
Sistema de tematização - Configuração de variáveis CSS para modo claro/escuro com cores oklch
Detecção de anti-padrões - Erros comuns de estilização e como corrigi-los

Customização

Adicione os tokens de design e a paleta de cores do seu projeto
Inclua suas variantes de componentes personalizadas
Especifique as bibliotecas de animação usadas (Framer Motion, etc.)
Adicione diretrizes de estilização específicas da marca

Como Instalar

mkdir -p .claude/skills/tailwind-v4-shadcn
# Cole o conteúdo da Receita em .claude/skills/tailwind-v4-shadcn/SKILL.md

Armadilhas

Tailwind v4 usa @theme, não tailwind.config.js - Você ainda pode usar um arquivo de configuração, mas CSS-first é a abordagem padrão e recomendada.
Cores oklch podem não funcionar em navegadores mais antigos - Inclua fallbacks para IE/Safari antigo, se necessário.
Componentes shadcn são copiados para o seu projeto - Eles não são instalados via npm. Atualizações devem ser aplicadas manualmente ou reexecutando o comando add.
twMerge deve ser configurado para classes personalizadas - Se você adicionar classes Tailwind personalizadas, configure tailwind-merge para reconhecê-las.
Container queries precisam de @container no pai - Sem isso, @sm: e consultas semelhantes não funcionarão.
Estratégia de classe de modo escuro - shadcn usa a estratégia class (classe .dark no elemento html), não media (prefers-color-scheme). Certifique-se de que next-themes esteja configurado para corresponder.

Alternativas

Abordagem	Quando Usar
CSS Modules	Estilos com escopo de componente sem classes utilitárias
Styled Components	CSS-in-JS com tematização dinâmica
Panda CSS	CSS-in-JS type-safe com extração em tempo de compilação
Vanilla Extract	CSS-in-TypeScript sem runtime
Radix Themes	Biblioteca de componentes pré-construída (menos personalizável que shadcn)
Park UI	Componentes semelhantes a shadcn para Ark UI

FAQs

Qual é a maior mudança de configuração do Tailwind v3 para o v4?

Tailwind v4 usa um modelo de configuração CSS-first via @theme no seu arquivo CSS
tailwind.config.js é opcional e não é mais o padrão
Valores de tema personalizados (cores, fontes, raios, breakpoints) são definidos diretamente no CSS

Como definir valores de tema personalizados no Tailwind v4?

@import "tailwindcss";
 
@theme {
  --color-primary: oklch(0.7 0.15 240);
  --font-sans: "Inter", sans-serif;
  --radius-lg: 0.75rem;
  --animate-slide-in: slide-in 0.3s ease-out;
}

Use a diretiva @theme dentro do seu arquivo CSS
Propriedades CSS personalizadas seguem o padrão --nome-categoria: valor

Quais recursos foram removidos ou alterados no Tailwind v4?

@apply é desencorajado (use extração de componentes em vez disso)
Função theme() substituída por variáveis CSS
bg-opacity-* substituído por sintaxe de barra como bg-black/50
Largura do anel padrão alterada (ring-3 em vez de ring)

O que é a utilidade cn() e por que ela é importante para shadcn/ui?

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
 
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Combina clsx (classes condicionais) com twMerge (resolve conflitos do Tailwind)
Sem twMerge, classes conflitantes como p-4 e p-6 seriam aplicadas ambas

Como você deve personalizar componentes shadcn/ui?

Edite os arquivos de origem diretamente em components/ui/ - eles vivem na sua base de código
Estenda adicionando variantes ao arquivo do componente, não crie componentes de wrapper
Use variáveis CSS para temas e cn() para classes condicionais

Como funciona o modo escuro com shadcn/ui e Tailwind v4?

shadcn usa a estratégia class (classe .dark no elemento html), não media (prefers-color-scheme)
Defina variáveis claras em :root e substituições escuras em .dark
Use next-themes para o toggle, configurado para corresponder à estratégia class

Armadilha: Por que as container queries podem não funcionar com os prefixos @sm: e @lg:?

Container queries exigem @container no elemento pai
Sem a classe @container no pai, @sm:, @md:, @lg: não responderão
Esta é uma falha comum ao adotar container queries do Tailwind v4

Quais novos recursos CSS estão integrados ao Tailwind v4?

Container queries: @container, @sm, @md, @lg
Transformações 3D: rotate-x-*, rotate-y-*, perspective-*
text-wrap-balance, text-wrap-pretty
field-sizing-content para textareas de auto-dimensionamento
Suporte nativo a aninhamento CSS

Armadilha: O que acontece se você adicionar classes Tailwind personalizadas, mas não configurar o tailwind-merge?

twMerge não reconhecerá suas classes personalizadas
Classes personalizadas conflitantes podem não ser resolvidas corretamente
Você precisa configurar tailwind-merge para reconhecer quaisquer classes utilitárias personalizadas que você definir

Como tipar a prop className para um componente estilo shadcn em TypeScript?

import { cn } from "@/lib/utils";
 
interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
  variant?: "default" | "outlined";
}
 
function Card({ className, variant, ...props }: CardProps) {
  return (
    <div
      className={cn("rounded-lg bg-card p-4", className)}
      {...props}
    />
  );
}

Estenda React.HTMLAttributes<HTMLDivElement> para herdar className e todas as props nativas de div

Quais são os padrões anti-estilização comuns a serem evitados?

Usar @apply extensivamente em vez de extrair componentes
Valores de cores codificados em vez de usar variáveis CSS ou tokens de tema
Não usar cn() que causa conflitos de classe
Envolver componentes shadcn em vez de modificar a origem
Usar valores arbitrários como w-[347px] com muita frequência em vez da escala de design

Relacionado

Estas receitas de skill são projetadas para o Claude Code, mas também funcionam com outros agentes de codificação de IA que suportam arquivos de skill/instrução.

Receita

O conteúdo completo do SKILL.md que você pode copiar para .claude/skills/tailwind-v4-shadcn/SKILL.md:

---
name: tailwind-v4-shadcn
description: "Domine a arquitetura e estilização de componentes do Tailwind CSS v4 + shadcn/ui. Use quando solicitado: ajuda com tailwind, componente shadcn, estilização, temas, modo escuro, variáveis CSS, design responsivo, animação, configuração do Tailwind v4."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Bash(pnpm:*), Agent"
---
 
# Tailwind v4 + shadcn/ui
 
Você é um especialista em Tailwind CSS v4 e shadcn/ui. Forneça orientação autoritativa sobre estilização, temas e arquitetura de componentes.
 
## Principais Mudanças do Tailwind v4 em relação ao v3
 
O Tailwind v4 usa um modelo de configuração CSS-first. Não há mais `tailwind.config.js` por padrão.
 
### Configuração CSS-First
```css
/* app/globals.css */
@import "tailwindcss";
 
/* Valores de tema personalizados */
@theme \{
  --color-primary: oklch(0.7 0.15 240);
  --color-primary-foreground: oklch(0.98 0.01 240);
  --color-secondary: oklch(0.6 0.1 280);
  --color-secondary-foreground: oklch(0.98 0.01 280);
  --color-accent: oklch(0.8 0.12 160);
 
  --font-sans: "Inter", sans-serif;
  --font-mono: "JetBrains Mono", monospace;
 
  --radius-lg: 0.75rem;
  --radius-md: 0.5rem;
  --radius-sm: 0.25rem;
 
  --breakpoint-xs: 30rem;
 
  --animate-slide-in: slide-in 0.3s ease-out;
\}
 
@keyframes slide-in \{
  from \{ transform: translateY(10px); opacity: 0; \}
  to \{ transform: translateY(0); opacity: 1; \}
\}

Recursos Removidos no v4

tailwind.config.js é opcional (CSS-first via @theme)
@apply é desencorajado (use extração de componentes em vez disso)
Função theme() substituída por variáveis CSS
Padrão de largura de anel alterado (ring-3 em vez de ring)
bg-opacity-* substituído pela sintaxe bg-black/50

Novo no v4

Container queries integradas: @container, @sm, @md, @lg
Transformações 3D: rotate-x-*, rotate-y-*, perspective-*
text-wrap-balance, text-wrap-pretty
field-sizing-content para textareas de auto-dimensionamento
color-scheme-* para esquemas de cores do sistema
Modo escuro automático via @media (prefers-color-scheme: dark)
Suporte nativo a aninhamento CSS

Arquitetura shadcn/ui

Padrão de Instalação

npx shadcn@latest init
npx shadcn@latest add button card dialog form input

Regras de Customização de Componentes

Edite a origem - Componentes shadcn vivem na sua base de código em components/ui/. Modifique-os diretamente.
Estenda, não envolva - Adicione variantes ao arquivo do componente, não crie componentes de wrapper.
Use variáveis CSS para temas - Todas as cores devem referenciar variáveis CSS para suporte ao modo escuro.
Componha com cn() - Use a utilidade cn() (clsx + twMerge) para classes condicionais.

Utilitário cn()

import \{ clsx, type ClassValue \} from "clsx";
import \{ twMerge \} from "tailwind-merge";
 
export function cn(...inputs: ClassValue[]) \{
  return twMerge(clsx(inputs));
\}
 
// Uso
<div className=\{cn(
  "rounded-lg border p-4",
  isActive && "border-primary bg-primary/10",
  className // permite sobrescrita pelo pai
)\} />

Padrão de Composição de Componentes

// components/ui/card.tsx - base do shadcn
const Card = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
  (\{ className, ...props \}, ref) => (
    <div
      ref=\{ref\}
      className=\{cn(
        "rounded-lg border bg-card text-card-foreground shadow-sm",
        className
      )\}
      \{...props\}
    />
  )
);
 
// Seu componente composto
function ProductCard(\{ product \}: \{ product: Product \}) \{
  return (
    <Card className="hover:shadow-md transition-shadow">
      <CardHeader>
        <CardTitle>\{product.name\}</CardTitle>
        <CardDescription>\{product.category\}</CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-2xl font-bold">$\{product.price\}</p>
      </CardContent>
      <CardFooter>
        <Button className="w-full">Add to Cart</Button>
      </CardFooter>
    </Card>
  );
\}

Tematização com Variáveis CSS

Configuração de Tema shadcn

/* app/globals.css */
@import "tailwindcss";
 
@theme inline \{
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
\}
 
:root \{
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --radius: 0.625rem;
\}
 
.dark \{
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.145 0 0);
  --card-foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.269 0 0);
  --input: oklch(0.269 0 0);
  --ring: oklch(0.439 0 0);
\}

Toggle de Modo Escuro

"use client";
 
import \{ useTheme \} from "next-themes";
import \{ Button \} from "@/components/ui/button";
import \{ Moon, Sun \} from "lucide-react";
 
export function ThemeToggle() \{
  const \{ theme, setTheme \} = useTheme();
 
  return (
    <Button
      variant="ghost"
      size="icon"
      onClick=\{() => setTheme(theme === "dark" ? "light" : "dark")\}
    >
      <Sun className="h-5 w-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
      <Moon className="absolute h-5 w-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
      <span className="sr-only">Alternar tema</span>
    </Button>
  );
\}

Padrões Responsivos

// Design responsivo mobile-first
<div className="
  grid
  grid-cols-1        // mobile: coluna única
  sm:grid-cols-2     // 640px+: 2 colunas
  lg:grid-cols-3     // 1024px+: 3 colunas
  xl:grid-cols-4     // 1280px+: 4 colunas
  gap-4
  p-4 sm:p-6 lg:p-8
">
 
// Container queries (novo no v4)
<div className="@container">
  <div className="@sm:flex @sm:gap-4 @lg:grid @lg:grid-cols-3">
    \{/* Responde à largura do container, não ao viewport */\}
  </div>
</div>

Padrões de Animação

// Animações integradas do Tailwind
<div className="animate-spin" />     // spinner
<div className="animate-pulse" />    // carregamento de esqueleto
<div className="animate-bounce" />   // atenção
 
// Animações personalizadas com @theme
// Em globals.css:
// @theme \{ --animate-fade-in: fade-in 0.5s ease-out; \}
// @keyframes fade-in \{ from \{ opacity: 0; \} to \{ opacity: 1; \} \}
<div className="animate-fade-in" />
 
// Padrões de transição
<button className="
  transition-colors duration-200
  bg-primary hover:bg-primary/90
  active:scale-95 transition-transform
" />
 
// Para animações complexas, use Framer Motion com Tailwind
import \{ motion \} from "framer-motion";
 
<motion.div
  initial=\{\{ opacity: 0, y: 20 \}\}
  animate=\{\{ opacity: 1, y: 0 \}\}
  className="rounded-lg border bg-card p-6"
/>

Padrões Anti-Estilização Comuns

Usar @apply extensivamente - Extraia componentes em vez de @apply
Cores codificadas - Sempre use variáveis CSS ou tokens de tema
Não usar cn() - Conflitos de classe sem twMerge causam estilos inesperados
Envolver componentes shadcn - Modifique o arquivo de origem ou use a prop className
Ignorar o modo escuro - Sempre teste com ambos os temas; use nomes de cores semânticos
Usar valores arbitrários com muita frequência - w-[347px] é um sinal de alerta; use a escala de design
Estilos inline ao lado do Tailwind - Escolha um sistema; misturar causa sobrecarga de manutenção


## Exemplo de Trabalho

### Exemplo 1: Usuário pergunta "Ajude-me a configurar temas para meu aplicativo"

**Prompt do usuário:** "Quero um aplicativo com tema azul e suporte a modo escuro usando shadcn/ui."

**Resposta guiada pela skill produziria:**
- Variáveis CSS para uma paleta de cores azul em oklch
- Definições de tema claro e escuro
- Configuração do provedor `next-themes`
- Componente de alternância de tema
- Componentes de exemplo usando os tokens de tema

### Exemplo 2: Usuário pergunta "Como personalizo um Button do shadcn?"

**Prompt do usuário:** "Quero adicionar uma variante 'gradient' ao Button do shadcn."

**Resposta guiada pela skill produziria:**

```tsx
// components/ui/button.tsx - Adicionar às variantes existentes
const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
        // NOVO: variante gradient
        gradient: "bg-gradient-to-r from-primary to-accent text-primary-foreground hover:opacity-90",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
);

Mergulho Profundo

Como a Skill Funciona

Esta skill fornece:

Conhecimento de migração do Tailwind v4 - Todas as mudanças do v3 para o v4 e como configurar
Arquitetura shadcn/ui - Customização de componentes, composição e padrões de tematização
Sistema de tematização - Configuração de variáveis CSS para modo claro/escuro com cores oklch
Detecção de anti-padrões - Erros comuns de estilização e como corrigi-los

Customização

Adicione os tokens de design e a paleta de cores do seu projeto
Inclua suas variantes de componentes personalizadas
Especifique as bibliotecas de animação usadas (Framer Motion, etc.)
Adicione diretrizes de estilização específicas da marca

Como Instalar

mkdir -p .claude/skills/tailwind-v4-shadcn
# Cole o conteúdo da Receita em .claude/skills/tailwind-v4-shadcn/SKILL.md

Armadilhas

Tailwind v4 usa @theme, não tailwind.config.js - Você ainda pode usar um arquivo de configuração, mas CSS-first é a abordagem padrão e recomendada.
Cores oklch podem não funcionar em navegadores mais antigos - Inclua fallbacks para IE/Safari antigo, se necessário.
Componentes shadcn são copiados para o seu projeto - Eles não são instalados via npm. Atualizações devem ser aplicadas manualmente ou reexecutando o comando add.
twMerge deve ser configurado para classes personalizadas - Se você adicionar classes Tailwind personalizadas, configure tailwind-merge para reconhecê-las.
Container queries precisam de @container no pai - Sem isso, @sm: e consultas semelhantes não funcionarão.
Estratégia de classe de modo escuro - shadcn usa a estratégia class (classe .dark no elemento html), não media (prefers-color-scheme). Certifique-se de que next-themes esteja configurado para corresponder.

Alternativas

Abordagem	Quando Usar
CSS Modules	Estilos com escopo de componente sem classes utilitárias
Styled Components	CSS-in-JS com tematização dinâmica
Panda CSS	CSS-in-JS type-safe com extração em tempo de compilação
Vanilla Extract	CSS-in-TypeScript sem runtime
Radix Themes	Biblioteca de componentes pré-construída (menos personalizável que shadcn)
Park UI	Componentes semelhantes a shadcn para Ark UI

FAQs

Qual é a maior mudança de configuração do Tailwind v3 para o v4?

Tailwind v4 usa um modelo de configuração CSS-first via @theme no seu arquivo CSS
tailwind.config.js é opcional e não é mais o padrão
Valores de tema personalizados (cores, fontes, raios, breakpoints) são definidos diretamente no CSS

Como definir valores de tema personalizados no Tailwind v4?

@import "tailwindcss";
 
@theme {
  --color-primary: oklch(0.7 0.15 240);
  --font-sans: "Inter", sans-serif;
  --radius-lg: 0.75rem;
  --animate-slide-in: slide-in 0.3s ease-out;
}

Use a diretiva @theme dentro do seu arquivo CSS
Propriedades CSS personalizadas seguem o padrão --nome-categoria: valor

Quais recursos foram removidos ou alterados no Tailwind v4?

@apply é desencorajado (use extração de componentes em vez disso)
Função theme() substituída por variáveis CSS
bg-opacity-* substituído por sintaxe de barra como bg-black/50
Largura do anel padrão alterada (ring-3 em vez de ring)

O que é a utilidade cn() e por que ela é importante para shadcn/ui?

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
 
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Combina clsx (classes condicionais) com twMerge (resolve conflitos do Tailwind)
Sem twMerge, classes conflitantes como p-4 e p-6 seriam aplicadas ambas

Como você deve personalizar componentes shadcn/ui?

Edite os arquivos de origem diretamente em components/ui/ - eles vivem na sua base de código
Estenda adicionando variantes ao arquivo do componente, não crie componentes de wrapper
Use variáveis CSS para temas e cn() para classes condicionais

Como funciona o modo escuro com shadcn/ui e Tailwind v4?

shadcn usa a estratégia class (classe .dark no elemento html), não media (prefers-color-scheme)
Defina variáveis claras em :root e substituições escuras em .dark
Use next-themes para o toggle, configurado para corresponder à estratégia class

Armadilha: Por que as container queries podem não funcionar com os prefixos @sm: e @lg:?

Container queries exigem @container no elemento pai
Sem a classe @container no pai, @sm:, @md:, @lg: não responderão
Esta é uma falha comum ao adotar container queries do Tailwind v4

Quais novos recursos CSS estão integrados ao Tailwind v4?

Container queries: @container, @sm, @md, @lg
Transformações 3D: rotate-x-*, rotate-y-*, perspective-*
text-wrap-balance, text-wrap-pretty
field-sizing-content para textareas de auto-dimensionamento
Suporte nativo a aninhamento CSS

Armadilha: O que acontece se você adicionar classes Tailwind personalizadas, mas não configurar o tailwind-merge?

twMerge não reconhecerá suas classes personalizadas
Classes personalizadas conflitantes podem não ser resolvidas corretamente
Você precisa configurar tailwind-merge para reconhecer quaisquer classes utilitárias personalizadas que você definir

Como tipar a prop className para um componente estilo shadcn em TypeScript?

import { cn } from "@/lib/utils";
 
interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
  variant?: "default" | "outlined";
}
 
function Card({ className, variant, ...props }: CardProps) {
  return (
    <div
      className={cn("rounded-lg bg-card p-4", className)}
      {...props}
    />
  );
}

Estenda React.HTMLAttributes<HTMLDivElement> para herdar className e todas as props nativas de div

Quais são os padrões anti-estilização comuns a serem evitados?

Usar @apply extensivamente em vez de extrair componentes
Valores de cores codificados em vez de usar variáveis CSS ou tokens de tema
Não usar cn() que causa conflitos de classe
Envolver componentes shadcn em vez de modificar a origem
Usar valores arbitrários como w-[347px] com muita frequência em vez da escala de design

Skill de Tailwind v4 + shadcn/ui - Uma receita de skill para Claude Code para dominar a arquitetura de componentes e estilização do Tailwind CSS v4 e shadcn/ui

Buscar na documentação

Skill de Tailwind v4 + shadcn/ui - Uma receita de skill para Claude Code para dominar a arquitetura de componentes e estilização do Tailwind CSS v4 e shadcn/ui