Configuração do Tailwind CSS v4

Q: Qual import único substitui as três diretivas @tailwind da v3?

@import "tailwindcss" substitui @tailwind base, @tailwind components e @tailwind utilities.

Q: Onde toda a configuração reside no Tailwind CSS v4?

No seu arquivo CSS dentro de blocos @theme { }. Não há tailwind.config.js por padrão.

Q: Como a convenção de nomenclatura do @theme mapeia para classes utilitárias?

--color-brand se torna text-brand, bg-brand, border-brand --spacing-18 se torna p-18, m-18, gap-18 --font-family-sans se torna font-sans

Q: Como migrar um projeto v3 existente para v4?

Execute npx @tailwindcss/upgrade. Ele converte os valores do seu tailwind.config.js em blocos CSS @theme.

Q: Qual é o nome correto do plugin PostCSS para v4?

@tailwindcss/postcss, não tailwindcss. Usar o nome antigo falhará silenciosamente.

Q: Armadilha: Por que --brand-color não gera nenhuma classe utilitária?

Os valores de tema devem seguir o padrão --categoria-nome. --color-brand funciona, mas --brand-color não corresponde a nenhuma categoria utilitária.

Q: Armadilha: Você adicionou valores @theme, mas ainda vê um tailwind.config.js - eles entrarão em conflito?

Eles podem. Use @config "./tailwind.config.js" no CSS apenas quando precisar de plugins baseados em JS. Mova todos os valores de tema para @theme para evitar conflitos.

Q: É possível dividir @theme entre vários arquivos CSS?

Sim. Importe um arquivo de tema separado após @import "tailwindcss":

Instale o Tailwind CSS v4, configure com a abordagem CSS-first, configure o @theme e use @import "tailwindcss".

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Instale o Tailwind CSS v4 com Next.js
npm install tailwindcss @tailwindcss/postcss postcss
 
# Ou com Vite
npm install tailwindcss @tailwindcss/vite

/* app/globals.css - a ÚNICA configuração que você precisa */
@import "tailwindcss";
 
/* Valores de tema personalizados */
@theme {
  --color-brand: #3b82f6;
  --color-brand-dark: #1d4ed8;
  --font-family-heading: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

// postcss.config.mjs (Next.js)
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

// vite.config.ts (Vite)
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
 
export default defineConfig({
  plugins: [tailwindcss()],
});

Quando usar isso: No início de cada novo projeto usando Tailwind CSS v4 - a configuração é mais simples que a v3, sem necessidade de tailwind.config.js.

Exemplo de Trabalho

/* app/globals.css - configuração completa do projeto */
@import "tailwindcss";
 
/* Detecção de origem - diga ao Tailwind onde estão suas classes */
@source "../components/**/*.tsx";
@source "../lib/**/*.ts";
 
/* Tema personalizado */
@theme {
  /* Cores */
  --color-primary: #2563eb;
  --color-primary-foreground: #ffffff;
  --color-secondary: #64748b;
  --color-destructive: #ef4444;
  --color-muted: #f1f5f9;
  --color-border: #e2e8f0;
 
  /* Espaçamento */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
 
  /* Tipografia */
  --font-family-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-family-mono: "JetBrains Mono", ui-monospace, monospace;
 
  /* Raio da borda */
  --radius-DEFAULT: 0.5rem;
  --radius-lg: 0.75rem;
 
  /* Sombras */
  --shadow-soft: 0 2px 8px rgb(0 0 0 / 0.08);
 
  /* Animações */
  --animate-fade-in: fade-in 0.3s ease-out;
}
 
@keyframes fade-in {
  from { opacity: 0; transform: translateY(-4px); }
  to { opacity: 1; transform: translateY(0); }
}
 
/* Utilitários personalizados */
@utility container-narrow {
  max-width: 42rem;
  margin-inline: auto;
  padding-inline: 1rem;
}
 
/* Variante personalizada */
@variant hocus (&:hover, &:focus-visible);
 
/* Substituições de camada */
@layer base {
  html {
    font-family: var(--font-family-sans);
    color: var(--color-foreground, #0f172a);
  }
 
  h1, h2, h3 {
    font-family: var(--font-family-heading, var(--font-family-sans));
  }
}

// Uso em componentes
export function Hero() {
  return (
    <section className="container-narrow animate-fade-in py-18">
      <h1 className="text-4xl font-bold text-primary">Bem-vindo</h1>
      <p className="mt-4 text-secondary">Construa algo grandioso.</p>
      <button className="mt-6 rounded-lg bg-primary px-6 py-3 text-primary-foreground shadow-soft hocus:bg-primary-dark">
        Começar
      </button>
    </section>
  );
}

O que isso demonstra:

@import "tailwindcss" substitui as antigas diretivas @tailwind
Bloco @theme para configuração CSS-first (sem arquivo de configuração JS)
@source para detecção explícita de conteúdo
Utilitários personalizados com @utility
Variantes personalizadas com @variant
Valores de tema usados como classes utilitárias (text-primary, shadow-soft, etc.)

Análise Detalhada

Como Funciona

Tailwind v4 é CSS-first - toda a configuração fica no seu arquivo CSS, não em um config JS
@import "tailwindcss" inclui todas as camadas base, componentes e utilitários do Tailwind
@theme define propriedades personalizadas CSS que o Tailwind converte em classes utilitárias
Convenção de nomenclatura: --color-* se torna text-*, bg-*, border-*; --spacing-* se torna p-*, m-*, gap-*
@source diz ao Tailwind onde escanear por nomes de classe (substitui content na configuração v3)
Tailwind v4 detecta fontes automaticamente na maioria dos frameworks - @source é necessário apenas para caminhos não padrão
O bloco @theme compila para propriedades personalizadas CSS, permitindo temas em tempo de execução

Variações

Migrando da configuração v3:

# Ferramenta de migração automática
npx @tailwindcss/upgrade

/* cores do tailwind.config.js v3 → @theme v4 */
/* Antes (JS): colors: { brand: { 500: '#3b82f6' } } */
/* Depois (CSS): */
@theme {
  --color-brand-500: #3b82f6;
}

Desativando valores de tema padrão:

@theme {
  /* Remove todas as cores padrão */
  --color-*: initial;
 
  /* Defina apenas suas cores */
  --color-primary: #2563eb;
  --color-gray-50: #f9fafb;
  --color-gray-900: #111827;
}

Múltiplos arquivos CSS:

/* styles/theme.css */
@theme {
  --color-brand: #3b82f6;
}
 
/* app/globals.css */
@import "tailwindcss";
@import "./styles/theme.css";

Notas sobre TypeScript

// Sem impacto no TypeScript - Tailwind é apenas CSS
// Mas você pode tipar seus tokens de tema para consistência:
const themeColors = {
  primary: "text-primary",
  secondary: "text-secondary",
  destructive: "text-destructive",
} as const;
 
type ThemeColor = keyof typeof themeColors;

Armadilhas Comuns

Sem tailwind.config.js por padrão - v4 não lê um arquivo de configuração JS. Correção: Toda a configuração vai para o CSS via @theme. Se você precisar usar configuração JS (para plugins), use @config "./tailwind.config.js" no seu CSS.
@tailwind base/components/utilities removido - v4 usa @import "tailwindcss" em vez disso. Correção: Substitua as três diretivas @tailwind por um único @import.
Plugin do PostCSS alterado - O plugin agora é @tailwindcss/postcss, não tailwindcss. Correção: Atualize sua configuração do PostCSS.
Detecção automática de conteúdo - v4 escaneia seu projeto automaticamente. Se as classes não estiverem sendo detectadas, adicione caminhos @source explícitos. Correção: Use @source "../path/**/*.tsx" para locais de arquivo não padrão.
Nomes das propriedades personalizadas CSS - Os valores do @theme devem seguir o padrão --categoria-nome para gerar utilitários corretos. --color-brand se torna text-brand, mas --brand-color não.

Alternativas

Alternativa	Use Quando	Não Use Quando
Tailwind v3	Projeto legado não pronto para migrar	Iniciando um novo projeto (v4 é mais simples)
CSS Modules	Você precisa de CSS com escopo local sem classes utilitárias	Você quer prototipagem rápida com utilitários
Vanilla Extract	Você quer CSS-in-TS type-safe com zero runtime	Você prefere desenvolvimento utility-first
UnoCSS	Você quer um motor utilitário ultra-rápido e configurável	Você quer o ecossistema e a comunidade do Tailwind

Perguntas Frequentes

Qual import único substitui as três diretivas @tailwind da v3?

@import "tailwindcss" substitui @tailwind base, @tailwind components e @tailwind utilities.

Onde toda a configuração reside no Tailwind CSS v4?

No seu arquivo CSS dentro de blocos @theme { }. Não há tailwind.config.js por padrão.

Como a convenção de nomenclatura do @theme mapeia para classes utilitárias?

--color-brand se torna text-brand, bg-brand, border-brand
--spacing-18 se torna p-18, m-18, gap-18
--font-family-sans se torna font-sans

Quando você precisa usar @source na v4?

Apenas quando a detecção automática do Tailwind não encontrar seus arquivos. Adicione @source "../path/**/*.tsx" para locais de arquivo não padrão.

Como migrar um projeto v3 existente para v4?

Execute npx @tailwindcss/upgrade. Ele converte os valores do seu tailwind.config.js em blocos CSS @theme.

Como remover todas as cores padrão e definir apenas as suas?

@theme {
  --color-*: initial;
  --color-primary: #2563eb;
}

Qual é o nome correto do plugin PostCSS para v4?

@tailwindcss/postcss, não tailwindcss. Usar o nome antigo falhará silenciosamente.

Armadilha: Por que --brand-color não gera nenhuma classe utilitária?

Os valores de tema devem seguir o padrão --categoria-nome. --color-brand funciona, mas --brand-color não corresponde a nenhuma categoria utilitária.

Armadilha: Você adicionou valores @theme, mas ainda vê um tailwind.config.js - eles entrarão em conflito?

Eles podem. Use @config "./tailwind.config.js" no CSS apenas quando precisar de plugins baseados em JS. Mova todos os valores de tema para @theme para evitar conflitos.

Como você pode verificar o uso de tokens de tema em TypeScript?

const themeColors = {
  primary: "text-primary",
  secondary: "text-secondary",
} as const;
 
type ThemeColor = keyof typeof themeColors;

O próprio Tailwind é apenas CSS, mas você pode criar um mapa de consulta tipado para consistência.

Como definir um utilitário personalizado e uma variante personalizada na v4?

@utility container-narrow {
  max-width: 42rem;
  margin-inline: auto;
}
 
@variant hocus (&:hover, &:focus-visible);

É possível dividir @theme entre vários arquivos CSS?

Sim. Importe um arquivo de tema separado após @import "tailwindcss":

@import "tailwindcss";
@import "./styles/theme.css";

Relacionado

Exemplos - 30 padrões utilitários comuns do Tailwind
Exemplos de Grid - padrões de layout flexbox e grid
Utilitários - folha de referência das classes utilitárias principais
Modo Escuro - modo escuro e temas
Utilitários Personalizados - @utility, @variant, plugins
Configuração do shadcn - integração shadcn + Tailwind

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Instale o Tailwind CSS v4 com Next.js
npm install tailwindcss @tailwindcss/postcss postcss
 
# Ou com Vite
npm install tailwindcss @tailwindcss/vite

/* app/globals.css - a ÚNICA configuração que você precisa */
@import "tailwindcss";
 
/* Valores de tema personalizados */
@theme {
  --color-brand: #3b82f6;
  --color-brand-dark: #1d4ed8;
  --font-family-heading: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

// postcss.config.mjs (Next.js)
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

// vite.config.ts (Vite)
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
 
export default defineConfig({
  plugins: [tailwindcss()],
});

Quando usar isso: No início de cada novo projeto usando Tailwind CSS v4 - a configuração é mais simples que a v3, sem necessidade de tailwind.config.js.

Exemplo de Trabalho

/* app/globals.css - configuração completa do projeto */
@import "tailwindcss";
 
/* Detecção de origem - diga ao Tailwind onde estão suas classes */
@source "../components/**/*.tsx";
@source "../lib/**/*.ts";
 
/* Tema personalizado */
@theme {
  /* Cores */
  --color-primary: #2563eb;
  --color-primary-foreground: #ffffff;
  --color-secondary: #64748b;
  --color-destructive: #ef4444;
  --color-muted: #f1f5f9;
  --color-border: #e2e8f0;
 
  /* Espaçamento */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
 
  /* Tipografia */
  --font-family-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-family-mono: "JetBrains Mono", ui-monospace, monospace;
 
  /* Raio da borda */
  --radius-DEFAULT: 0.5rem;
  --radius-lg: 0.75rem;
 
  /* Sombras */
  --shadow-soft: 0 2px 8px rgb(0 0 0 / 0.08);
 
  /* Animações */
  --animate-fade-in: fade-in 0.3s ease-out;
}
 
@keyframes fade-in {
  from { opacity: 0; transform: translateY(-4px); }
  to { opacity: 1; transform: translateY(0); }
}
 
/* Utilitários personalizados */
@utility container-narrow {
  max-width: 42rem;
  margin-inline: auto;
  padding-inline: 1rem;
}
 
/* Variante personalizada */
@variant hocus (&:hover, &:focus-visible);
 
/* Substituições de camada */
@layer base {
  html {
    font-family: var(--font-family-sans);
    color: var(--color-foreground, #0f172a);
  }
 
  h1, h2, h3 {
    font-family: var(--font-family-heading, var(--font-family-sans));
  }
}

// Uso em componentes
export function Hero() {
  return (
    <section className="container-narrow animate-fade-in py-18">
      <h1 className="text-4xl font-bold text-primary">Bem-vindo</h1>
      <p className="mt-4 text-secondary">Construa algo grandioso.</p>
      <button className="mt-6 rounded-lg bg-primary px-6 py-3 text-primary-foreground shadow-soft hocus:bg-primary-dark">
        Começar
      </button>
    </section>
  );
}

O que isso demonstra:

@import "tailwindcss" substitui as antigas diretivas @tailwind
Bloco @theme para configuração CSS-first (sem arquivo de configuração JS)
@source para detecção explícita de conteúdo
Utilitários personalizados com @utility
Variantes personalizadas com @variant
Valores de tema usados como classes utilitárias (text-primary, shadow-soft, etc.)

Análise Detalhada

Como Funciona

Tailwind v4 é CSS-first - toda a configuração fica no seu arquivo CSS, não em um config JS
@import "tailwindcss" inclui todas as camadas base, componentes e utilitários do Tailwind
@theme define propriedades personalizadas CSS que o Tailwind converte em classes utilitárias
Convenção de nomenclatura: --color-* se torna text-*, bg-*, border-*; --spacing-* se torna p-*, m-*, gap-*
@source diz ao Tailwind onde escanear por nomes de classe (substitui content na configuração v3)
Tailwind v4 detecta fontes automaticamente na maioria dos frameworks - @source é necessário apenas para caminhos não padrão
O bloco @theme compila para propriedades personalizadas CSS, permitindo temas em tempo de execução

Variações

Migrando da configuração v3:

# Ferramenta de migração automática
npx @tailwindcss/upgrade

/* cores do tailwind.config.js v3 → @theme v4 */
/* Antes (JS): colors: { brand: { 500: '#3b82f6' } } */
/* Depois (CSS): */
@theme {
  --color-brand-500: #3b82f6;
}

Desativando valores de tema padrão:

@theme {
  /* Remove todas as cores padrão */
  --color-*: initial;
 
  /* Defina apenas suas cores */
  --color-primary: #2563eb;
  --color-gray-50: #f9fafb;
  --color-gray-900: #111827;
}

Múltiplos arquivos CSS:

/* styles/theme.css */
@theme {
  --color-brand: #3b82f6;
}
 
/* app/globals.css */
@import "tailwindcss";
@import "./styles/theme.css";

Notas sobre TypeScript

// Sem impacto no TypeScript - Tailwind é apenas CSS
// Mas você pode tipar seus tokens de tema para consistência:
const themeColors = {
  primary: "text-primary",
  secondary: "text-secondary",
  destructive: "text-destructive",
} as const;
 
type ThemeColor = keyof typeof themeColors;

Armadilhas Comuns

Sem tailwind.config.js por padrão - v4 não lê um arquivo de configuração JS. Correção: Toda a configuração vai para o CSS via @theme. Se você precisar usar configuração JS (para plugins), use @config "./tailwind.config.js" no seu CSS.
@tailwind base/components/utilities removido - v4 usa @import "tailwindcss" em vez disso. Correção: Substitua as três diretivas @tailwind por um único @import.
Plugin do PostCSS alterado - O plugin agora é @tailwindcss/postcss, não tailwindcss. Correção: Atualize sua configuração do PostCSS.
Detecção automática de conteúdo - v4 escaneia seu projeto automaticamente. Se as classes não estiverem sendo detectadas, adicione caminhos @source explícitos. Correção: Use @source "../path/**/*.tsx" para locais de arquivo não padrão.
Nomes das propriedades personalizadas CSS - Os valores do @theme devem seguir o padrão --categoria-nome para gerar utilitários corretos. --color-brand se torna text-brand, mas --brand-color não.

Alternativas

Alternativa	Use Quando	Não Use Quando
Tailwind v3	Projeto legado não pronto para migrar	Iniciando um novo projeto (v4 é mais simples)
CSS Modules	Você precisa de CSS com escopo local sem classes utilitárias	Você quer prototipagem rápida com utilitários
Vanilla Extract	Você quer CSS-in-TS type-safe com zero runtime	Você prefere desenvolvimento utility-first
UnoCSS	Você quer um motor utilitário ultra-rápido e configurável	Você quer o ecossistema e a comunidade do Tailwind

Perguntas Frequentes

Qual import único substitui as três diretivas @tailwind da v3?

@import "tailwindcss" substitui @tailwind base, @tailwind components e @tailwind utilities.

Onde toda a configuração reside no Tailwind CSS v4?

No seu arquivo CSS dentro de blocos @theme { }. Não há tailwind.config.js por padrão.

Como a convenção de nomenclatura do @theme mapeia para classes utilitárias?

--color-brand se torna text-brand, bg-brand, border-brand
--spacing-18 se torna p-18, m-18, gap-18
--font-family-sans se torna font-sans

Quando você precisa usar @source na v4?

Apenas quando a detecção automática do Tailwind não encontrar seus arquivos. Adicione @source "../path/**/*.tsx" para locais de arquivo não padrão.

Como migrar um projeto v3 existente para v4?

Execute npx @tailwindcss/upgrade. Ele converte os valores do seu tailwind.config.js em blocos CSS @theme.

Como remover todas as cores padrão e definir apenas as suas?

@theme {
  --color-*: initial;
  --color-primary: #2563eb;
}

Qual é o nome correto do plugin PostCSS para v4?

@tailwindcss/postcss, não tailwindcss. Usar o nome antigo falhará silenciosamente.

Armadilha: Por que --brand-color não gera nenhuma classe utilitária?

Os valores de tema devem seguir o padrão --categoria-nome. --color-brand funciona, mas --brand-color não corresponde a nenhuma categoria utilitária.

Armadilha: Você adicionou valores @theme, mas ainda vê um tailwind.config.js - eles entrarão em conflito?

Eles podem. Use @config "./tailwind.config.js" no CSS apenas quando precisar de plugins baseados em JS. Mova todos os valores de tema para @theme para evitar conflitos.

Como você pode verificar o uso de tokens de tema em TypeScript?

const themeColors = {
  primary: "text-primary",
  secondary: "text-secondary",
} as const;
 
type ThemeColor = keyof typeof themeColors;

O próprio Tailwind é apenas CSS, mas você pode criar um mapa de consulta tipado para consistência.

Como definir um utilitário personalizado e uma variante personalizada na v4?

@utility container-narrow {
  max-width: 42rem;
  margin-inline: auto;
}
 
@variant hocus (&:hover, &:focus-visible);

É possível dividir @theme entre vários arquivos CSS?

Sim. Importe um arquivo de tema separado após @import "tailwindcss":

@import "tailwindcss";
@import "./styles/theme.css";

Relacionado

Exemplos - 30 padrões utilitários comuns do Tailwind
Exemplos de Grid - padrões de layout flexbox e grid
Utilitários - folha de referência das classes utilitárias principais
Modo Escuro - modo escuro e temas
Utilitários Personalizados - @utility, @variant, plugins
Configuração do shadcn - integração shadcn + Tailwind

Configuração do Tailwind CSS v4

Buscar na documentação

Configuração do Tailwind CSS v4