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.
Resumo
| Critério | Hex / HSL legado (Tailwind v3) | OKLCH @theme (Tailwind v4) |
|---|---|---|
| Sintaxe | Strings Hex em tailwind.config.js | CSS @theme --color-* : oklch(...) |
| Uniformidade perceptual | Não — amarelo brilha bem mais que azul | Sim — eixo L acompanha brilho percebido |
| Gama Display P3 | Preso ao sRGB de 8 bits | Pronto para Display P3 e Rec.2020 |
| Variações dinâmicas | Exige matemática de pré-processador | CSS 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.
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.
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.
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.
Especificações e referências oficiais
Mais guias de cor
- OKLCH vs HSL vs sRGB: Entendendo o Wide-Gamut Display P3Compare HSL, Hex sRGB, Display P3 e OKLCH em luminosidade perceptual, gradientes limpos, volume cromático e CSS progressivo.
- W3C Design Tokens (DTCG 2025.10): Variáveis do Figma ao CSSEstruture design tokens abertos com W3C DTCG 2025.10 JSON ($type, $value colorSpace & components), aliases e exportação para CSS e Tailwind v4.
- Contraste WCAG 2.2 vs APCA (Lc): Guia Completo de AcessibilidadeCompare a razão WCAG 2.2 (4.5:1) com o contraste perceptual APCA (Lc 60/75/90), polaridade em modo escuro e simulação CVD.
- Uma cor em RGB, HSL, HSV, HWB e OKLabConfira um seletor, uma declaração CSS ou um shader com #336699. Compare oito notações da mesma amostra e verifique a precisão ao voltar para RGB.