Tailwind CSS v4: Customização de Cores com Variáveis CSS

A customização de cores também passou por uma grande evolução no Tailwind CSS v4. O modelo baseado em propriedades de um objeto JavaScript no tailwind.config.js foi substituído pelo uso de variáveis CSS nativas dentro da diretiva @theme no seu arquivo CSS principal.

Abaixo está o artigo totalmente atualizado para o padrão da v4, mantendo a estrutura Markdown e sem ícones.

Embora a paleta padrão do Tailwind CSS seja extensa, muitas vezes é necessário aplicar as cores da identidade visual da sua marca ou de um projeto específico. Para isso, o Tailwind v4 permite personalizar, estender ou substituir as cores padrão diretamente no seu arquivo CSS principal utilizando a diretiva @theme.

Estendendo a paleta padrão

Você pode adicionar novas cores personalizadas mantendo todas as cores padrão do Tailwind intactas. Para fazer isso, basta declarar as novas variáveis de cor dentro da diretiva @theme:

CSS

@import "tailwindcss";

@theme {
  --color-primary: #1e3a8a;
  --color-secondary: #64748b;
  
  --color-destaque-light: #fde68a;
  --color-destaque: #facc15;
  --color-destaque-dark: #ca8a04;
}

O Tailwind v4 detecta o prefixo --color-* e gera automaticamente todas as classes utilitárias correspondentes (como bg-primary, text-destaque-dark, border-secondary, etc.).

Exemplo de uso no HTML:

HTML

<button class="bg-primary text-white px-4 py-2 rounded">
  Botão com cor personalizada
</button>

<p class="text-destaque-dark">Texto com variação de cor customizada</p>

Substituindo completamente a paleta

Se desejar remover toda a paleta de cores padrão do Tailwind e disponibilizar apenas as suas próprias cores no projeto, utilize a palavra-chave default logo após a diretiva @theme:

CSS

@import "tailwindcss";

@theme default {
  --color-primary: #0d9488;
  --color-white: #ffffff;
  --color-black: #000000;
}

Neste caso, as cores originais do Tailwind (como blue, gray, red, etc.) deixam de estar disponíveis, e o autocomplete do seu editor exibirá apenas os seus tokens customizados.

Cores com estados (hover, focus)

Assim como nas versões anteriores, as cores personalizadas mapeadas pelas variáveis CSS funcionam normalmente com os modificadores de estado nativos do framework:

HTML

<a href="#" class="text-primary hover:text-destaque-dark">
  Link com efeito hover
</a>

Cores no modo escuro (dark mode)

No Tailwind v4, a abordagem para o modo escuro aproveita ainda mais os recursos do CSS moderno. Você pode redefinir o valor das suas variáveis de cor dentro do escopo de mídia de preferência de cor ou através de uma classe controladora:

CSS

@import "tailwindcss";

@theme {
  --color-custom-text: #1f2937;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-custom-text: #f3f4f6;
  }
}

No HTML, o uso das classes utilitárias continua limpo e integrado:

HTML

<p class="text-custom-text">
  Este texto adapta sua cor automaticamente no modo escuro baseado no sistema
</p>

Se o seu projeto utiliza uma classe para alternar o tema (ex: <html class="dark">), basta aplicar a variação correspondente:

HTML

<p class="text-gray-800 dark:text-gray-200">
  Este texto muda de cor usando o modificador clássico dark:
</p>

Organização recomendada

É uma boa prática adotar nomes semânticos para os tokens de design (como primary, secondary, surface, error, success) em vez de nomes baseados na cor exata (como dark-blue). Isso facilita a manutenção e permite que a paleta inteira mude no futuro sem a necessidade de alterar centenas de arquivos HTML.

Ferramentas externas

Para gerar paletas harmônicas ou inspiradas em marcas que exportam facilmente para formatos compatíveis com variáveis CSS ou configurações de design, você pode usar:

Customizar as cores no Tailwind CSS através de variáveis CSS nativas é uma forma poderosa de alinhar sua interface à identidade da marca, tornando o framework ainda mais integrado aos padrões da web, rápido na compilação e simples de estender.