Hex para OKLCH: Migração de Design Tokens para Tailwind CSS v4

Guia passo a passo para migrar temas Hex/HSL do Tailwind v3 para @theme oklch() do Tailwind v4 com brilho uniforme e Display P3.

6 min de leitura · Atualizado 2026-11-22

Resumo

CritérioHex / HSL legado (Tailwind v3)OKLCH @theme (Tailwind v4)
SintaxeStrings Hex em tailwind.config.jsCSS @theme --color-* : oklch(...)
Uniformidade perceptualNão — amarelo brilha bem mais que azulSim — eixo L acompanha brilho percebido
Gama Display P3Preso ao sRGB de 8 bitsPronto para Display P3 e Rec.2020
Variações dinâmicasExige matemática de pré-processadorCSS nativo oklch(from var(--c) ...)

Por que o Tailwind v4 migrou sua paleta padrão de Hex para OKLCH

Strings Hex sRGB escondem a luminância visual real. Dois degraus 500 em azul e amarelo oferecem contrastes completamente distintos sem auditoria manual.

O OKLCH coloca a Luminosidade perceptual (L) no primeiro eixo, Croma (C) no segundo e Matiz (H) no terceiro, mantendo peso visual estável.

  • Degraus 50–950 coerentes: texto escuro passa com folga sobre 50–400 e texto branco sobre 600–950.
  • Cores relativas nativas em CSS sem plugins Sass ou PostCSS.

Converter tema Tailwind v3 para v4 OKLCH

Mapeando theme.extend.colors de tailwind.config.js para @theme

Cole seu bloco Hex ou variáveis :root no conversor do Colr para transformar cada ponto via sRGB linear D65 em declarações oklch() precisas.

Substitua paletas estáticas em Hex do tailwind.

Mapeando theme.extend.colors de tailwind.config.js para @theme
CSS
@import "tailwindcss";

@theme {
  --color-brand-50: oklch(97.2% 0.014 261.2);
  --color-brand-500: oklch(54.6% 0.215 262.9);
  --color-brand-700: oklch(42.4% 0.178 263.5);
  --color-brand-950: oklch(23.1% 0.086 264.1);
}

Verificando contraste WCAG 2.2 e APCA após migrar

Sempre audite a escala 50–950 antes de ir para produção,

especialmente botões 500–600 com texto branco.

  • Cheque degraus 500 e 600 para razão mínima 4.5:1.
  • Inspecione fallbacks sRGB de acentos wide-gamut.

Criar escala OKLCH 50–950 acessível

Ferramentas citadas neste guia

Formatos relacionados

Perguntas frequentes

Cores oklch() quebram em navegadores antigos?

Chrome, Safari, Firefox e Edge desde 2023 suportam oklch() nativamente; variáveis Hex opcionais garantem compatibilidade legada.

Hex e OKLCH parecem iguais em monitores sRGB comuns?

Sim — até você elevar intencionalmente o Croma rumo ao Display P3, o valor convertido reproduz o mesmo sRGB.

Mais guias de cor