Tokens de cor em CSS e Tailwind

· 3 min de leitura

Como nomear e organizar variáveis de cor por função, ligar os modos claro e escuro no CSS e usar os mesmos tokens em um tema do Tailwind v4.

Valores hex espalhados pela folha de estilos são o principal motivo de mudar cores ser tão trabalhoso. Um rebranding, a chegada do modo escuro ou a correção de um problema de contraste vira um buscar e substituir por centenas de linhas. Os tokens de cor — variáveis com nome que descrevem para que uma cor serve — resolvem isso. Este guia mostra como estruturá-los em CSS puro e usar os mesmos tokens no Tailwind.

Duas camadas: primitivos e funções

Uma estrutura sólida separa o que as cores são de como elas são usadas.

Os tokens primitivos são a paleta crua, nomeada por matiz e degrau. Eles nunca aparecem direto nos estilos dos componentes.

:root {
  --blue-100: #E3E8FF;
  --blue-500: #3D5AFE;
  --blue-700: #2638C4;
  --sand-50:  #F7F5F0;
  --ink-900:  #1D2433;
}

Os tokens semânticos (de função) descrevem um trabalho na interface e apontam para um primitivo ou guardam um valor próprio. Os componentes só usam esses.

:root {
  --color-bg:         var(--sand-50);
  --color-surface:    #EFECE4;
  --color-border:     #DAD6CC;
  --color-text:       var(--ink-900);
  --color-muted:      #5C6475;
  --color-primary:    var(--blue-500);
  --color-on-primary: #FFFFFF;
  --color-accent:     #C2410C;
}
.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  color: var(--color-text);
}

Agora o botão não sabe que é azul. Se a marca mudar para verde, você troca uma linha. Se uma verificação de contraste reprovar, você ajusta um token e todos os componentes acompanham.

Nomeie os tokens pela função, não pela aparência

Nomes como --light-gray ou --brand-blue descrevem como uma cor é hoje. Eles ficam errados no momento em que o valor muda — e, no modo escuro, --light-gray guardaria uma cor escura. Nomes de função continuam verdadeiros:

  • --color-bg, --color-surface, --color-border para a estrutura.
  • --color-text e --color-muted para o conteúdo.
  • --color-primary, --color-accent para a ênfase.
  • --color-on-primary, --color-on-accent para o texto sobre cores preenchidas.
  • Funções de status opcionais: --color-success, --color-warning, --color-danger.

Mantenha a lista curta. Uma dúzia de tokens de função atende à maioria dos produtos; criar um token para cada componente traz de volta o problema original.

O modo escuro vira um conjunto de novos valores

Com tokens de função, o modo escuro não é uma segunda folha de estilos. São os mesmos nomes com valores diferentes. O padrão abaixo segue a configuração do sistema e ainda deixa uma chave forçar qualquer um dos temas com o atributo data-theme:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-bg:         #14161F;
    --color-surface:    #1C1F2B;
    --color-border:     #2C3040;
    --color-text:       #E6E8EF;
    --color-muted:      #9AA1B2;
    --color-primary:    #8C9EFF;
    --color-on-primary: #14161F;
    --color-accent:     #FB923C;
  }
}

:root[data-theme="dark"] {
  /* os mesmos valores, para quem escolhe o escuro manualmente */
}

Repare que a primária do escuro é um azul mais claro e o rótulo dela é escuro. Os valores escuros devem ser escolhidos, não calculados por inversão — o guia de modo escuro explica por quê.

Os navegadores modernos também suportam a função light-dark(), que deixa os dois valores na mesma linha. Ela segue a propriedade color-scheme, então precisa dessa declaração para funcionar:

:root {
  color-scheme: light dark;
  --color-bg:   light-dark(#F7F5F0, #14161F);
  --color-text: light-dark(#1D2433, #E6E8EF);
}

Derive as cores discretas

Superfícies e bordas podem ser misturadas a partir do fundo e do texto em vez de escolhidas à mão. O color-mix() faz isso no CSS, e misturar em OKLCH dá degraus uniformes e naturais:

:root {
  --color-surface: color-mix(in oklch, var(--color-bg) 94%, var(--color-text));
  --color-border:  color-mix(in oklch, var(--color-bg) 82%, var(--color-text));
}

Como elas fazem referência a outros tokens, se atualizam sozinhas no modo escuro. Confira se a borda chega a 3:1 quando ela marca um campo ou outro controle.

Usando os tokens no Tailwind CSS v4

O Tailwind v4 é configurado no CSS. Qualquer variável --color-* declarada em @theme vira um conjunto completo de utilitários (bg-*, text-*, border-* e assim por diante). Os utilitários gerados leem a variável em tempo de execução — bg-primary vira background-color: var(--color-primary) —, então basta substituir a variável no modo escuro:

@import "tailwindcss";

/* os valores claros viram utilitários: bg-bg, text-text, bg-primary ... */
@theme {
  --color-bg:         #F7F5F0;
  --color-surface:    #EFECE4;
  --color-text:       #1D2433;
  --color-muted:      #5C6475;
  --color-primary:    #3D5AFE;
  --color-on-primary: #FFFFFF;
  --color-accent:     #C2410C;
}

/* os valores escuros substituem as mesmas variáveis */
@media (prefers-color-scheme: dark) {
  :root {
    --color-bg:         #14161F;
    --color-text:       #E6E8EF;
    --color-primary:    #8C9EFF;
    --color-on-primary: #14161F;
    /* ... */
  }
}
<button class="bg-primary text-on-primary">Save</button>
<p class="text-muted">Last edited 2 hours ago</p>

Não é preciso usar variantes dark: em cada elemento: os tokens já mudam, então bg-primary fica correto nos dois temas.

Tailwind v3

No v3, mapeie as mesmas variáveis no arquivo de configuração:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        bg: 'var(--color-bg)',
        surface: 'var(--color-surface)',
        text: 'var(--color-text)',
        primary: 'var(--color-primary)',
        accent: 'var(--color-accent)',
      },
    },
  },
}

Escrevendo valores em OKLCH

Hex serve bem para guardar cores, mas o OKLCH é mais fácil de entender na hora de editar. Seus três canais são luminosidade, croma (saturação) e matiz, e a luminosidade corresponde de perto ao que o olho vê. Para fazer uma versão mais escura de uma cor de marca para texto, você baixa o L e deixa o resto como está: oklch(55% 0.2 265) vira oklch(42% 0.2 265). Todos os principais navegadores atuais suportam oklch().

Pule a digitação

Toda paleta do Colorset exporta exatamente essa estrutura: tokens de função para os modos claro e escuro como variáveis CSS, um tema do Tailwind v4, uma config do Tailwind v3, SCSS, JSON ou design tokens, em HEX, RGB, HSL ou OKLCH. Escolha um esquema de que goste, abra Exportar e cole. O gerador de tons cria uma escala primitiva de 50 a 950 a partir de qualquer cor, se você quiser montar a camada de primitivos por conta própria.