Construindo uma paleta de cores OKLCH que o Tailwind v4 realmente quer significa duas mudanças em relação ao método antigo: seus tons vivem no espaço de cores OKLCH (não hex), e suas cores de marca são definidas em CSS dentro de um bloco @theme em vez de uma configuração JavaScript. Faça ambos e você obtém uma escala de 50 a 900 onde cada etapa parece uniformemente espaçada, seus escuros permanecem ricos em vez de turvos, e seus tons mais claros não se transformam em néon desbotado. Este guia percorre todo o pipeline, desde a escolha de um matiz de marca até colar variáveis em @theme.
A maioria dos geradores de paleta ainda entrega códigos hex e para por aí. Isso funcionava para o Tailwind v3. No v4, o sistema de cores padrão foi reconstruído em OKLCH, então colar hex de volta joga fora exatamente o que torna a nova paleta equilibrada. Abaixo você verá por que o OKLCH evita o clássico problema "700 turvo, 100 néon", como leveza, croma e matiz se mapeiam em uma escala, e a sintaxe exata de @theme para publicá-la.
Por que o Tailwind v4 migrou para OKLCH#
O Tailwind v4 fornece toda sua paleta padrão em OKLCH e espera que suas cores personalizadas sigam o mesmo. OKLCH significa Luminosidade, Croma, Matiz, com um alfa opcional. É um espaço de cor perceptualmente uniforme, ou seja, uma alteração no número de luminosidade parece a mesma quantidade de mudança visual aos seus olhos, independentemente do matiz em que você está.
Isso parece acadêmico até você comparar com os espaços que usávamos antes. Hex e HSL não são perceptualmente uniformes. Em HSL, "50% de luminosidade" no amarelo parece muito mais brilhante do que "50% de luminosidade" no azul, então uma paleta construída com etapas uniformes de luminosidade HSL fica desequilibrada. Alguns tons parecem muito escuros, outros muito claros, e nada se alinha entre as cores.
Ideia-chave: OKLCH desacopla o quão brilhante uma cor parece de seu matiz. Aumente a luminosidade uniformemente e os tons parecem igualmente espaçados, seja a cor limão ou marinho.
O que o OKLCH corrige na prática#
Dois modos de falha desaparecem quando você cria cores em OKLCH:
- Escuros turvos: Em HSL, escurecer uma cor saturada frequentemente a arrasta para o cinza ou marrom. OKLCH permite reduzir a luminosidade mantendo o croma, então um tom 700 ou 800 permanece uma versão rica e reconhecível da cor da marca, em vez de lama.
- Luzes de neon: Em HSL, tons próximos ao branco podem disparar em saturação aparente e parecer radioativos. Os tons em OKLCH permanecem suaves e controlados porque o croma é gerenciado independentemente da luminosidade.
O bônus da gama mais ampla#
OKLCH também pode descrever cores fora do antigo intervalo sRGB. Em monitores modernos que suportam a gama P3 (a maioria dos celulares e laptops recentes), as cores do Tailwind v4 são renderizadas mais vívidas do que os equivalentes sRGB, e depois fazem fallback graciosamente em telas antigas. Você obtém cores mais ricas gratuitamente em hardware capaz, sem quebrar nada no restante. É por isso que as cores da gama P3 são importantes para trabalhos de marca em 2026: o mesmo CSS parece mais vibrante onde pode e seguro em todos os outros lugares.
Como Luminosidade, Croma e Matiz se Mapeiam em uma Escala de 50 a 950#
Uma escala de cores Tailwind vai de 50 (tom mais claro) a 950 (tom mais escuro), com a cor da marca geralmente no 500. O segredo para uma escala OKLCH limpa é entender qual dos três canais você mexe em cada etapa e qual você deixa praticamente intacto.
Aqui está o modelo mental:
| Canal | O que controla | Como se move de 50 a 950 |
|---|---|---|
| Luminosidade (L) | O quão brilhante a cor parece, de 0 a 1 | Mais alta em 50 (cerca de 0,97), mais baixa em 950 (cerca de 0,25). Isso faz a maior parte do trabalho. |
| Croma (C) | Intensidade / saturação da cor | Mais baixa nos extremos (tons claros e escuros), atinge o pico no meio (400-600). |
| Matiz (H) | O ângulo real da cor, de 0 a 360 | Permanece quase constante. Pequenos deslocamentos adicionam realismo, mas são opcionais. |
A regra mais importante: a luminosidade deve aumentar em incrementos aproximadamente iguais. Se o seu 500 estiver perto de L 0,65, sua escala pode ser algo como 0,97, 0,94, 0,89, 0,82, 0,74, 0,65, 0,55, 0,45, 0,37, 0,30 de 50 a 900. Espaçamento uniforme em L é o que faz as amostras parecerem um gradiente verdadeiro, e não amostras aleatórias.
Croma é uma curva, não uma linha#
O erro que as pessoas cometem é manter o croma constante em toda a escala. Isso produz tons claros desbotados e tons escuros supersaturados. Paletas reais e agradáveis usam um arco de croma:
- Tons claros (50-200): croma baixo. Um tom quase branco com croma alto parece artificial, então reduza-o.
- Núcleo (400-600): pico de croma. É aqui que a cor da marca é mais vívida.
- Tons escuros (700-950): o croma diminui novamente, em parte porque cores escuras não conseguem manter croma alto sem sair do gamute.
Imagine o croma subindo do tom mais claro até um pico por volta de 400-500, depois diminuindo de volta em direção ao tom mais escuro. Esse arco é a diferença entre uma escala que parece projetada e uma que parece gerada.
Matiz: deixe-o em paz, na maioria das vezes#
Para uma escala limpa e moderna, mantenha o matiz constante em todas as onze etapas. Se quiser um acabamento extra, você pode ajustar o matiz em alguns graus, uma técnica chamada deslocamento de matiz, para imitar como os pigmentos reais se comportam (sombras tendem ao frio, realces ao quente). É opcional e fácil de exagerar, então comece com um matiz constante e adicione deslocamentos sutis apenas se a versão plana parecer sem vida.
Como Criar uma Paleta OKLCH para Tailwind v4#
Você pode calcular manualmente, mas é complicado e fácil errar a curva de croma. O caminho mais rápido e confiável é gerar a escala a partir de uma única cor de marca e colar os valores OKLCH na sua folha de estilo. Aqui está o procedimento completo.
Passo 1: Escolha sua cor de marca como o ponto 500#
Comece com uma cor, aquela que representa sua marca, e trate-a como o passo 500. Não comece pela extremidade mais clara ou mais escura; o tom médio é a âncora da qual tudo deriva. Se você só tem um código hex de um logotipo, tudo bem, você o converterá. Abra o gerador de paleta de cores gratuito, insira seu hex de marca ou escolha um matiz e deixe-o se tornar seu 500.
Passo 2: Gere a escala completa de 50 a 900 em OKLCH#
A partir da âncora 500, gere os passos ao redor. Um bom gerador faz a progressão de luminosidade e o arco de croma para você, resultando em matizes suaves e sombras ricas. Confirme que a saída está em OKLCH, não em hex. Você quer valores como oklch(0.65 0.18 250), três números para luminosidade, croma e matiz. Se uma ferramenta só fornecer hex, ela está gerando saída do Tailwind v3 e você perderá o benefício.
Passo 3: Verifique a escala visualmente#
Olhe as amostras em ordem. Dois testes rápidos:
- Os passos parecem uniformemente espaçados, sem um salto repentino onde um tom parece muito mais próximo do vizinho do que os outros?
- Os escuros ainda são claramente sua cor de marca, e os claros são suaves em vez de neon?
Se um passo parecer estranho, geralmente é um problema de espaçamento de luminosidade ou um valor de croma que não afinou. Ajuste esse passo em vez de reconstruir toda a escala.
Passo 4: Converta cada passo em uma variável CSS#
O Tailwind v4 lê cores de propriedades personalizadas CSS. Nomeie-as com a convenção --color-brand-50 até --color-brand-950. O prefixo --color- é o que informa ao Tailwind para gerar utilitários correspondentes. Cada variável contém um valor OKLCH:
:root {
--color-brand-50: oklch(0.97 0.02 250);
--color-brand-100: oklch(0.94 0.04 250);
--color-brand-200: oklch(0.89 0.07 250);
--color-brand-300: oklch(0.82 0.11 250);
--color-brand-400: oklch(0.74 0.15 250);
--color-brand-500: oklch(0.65 0.18 250);
--color-brand-600: oklch(0.55 0.17 250);
--color-brand-700: oklch(0.45 0.14 250);
--color-brand-800: oklch(0.37 0.10 250);
--color-brand-900: oklch(0.30 0.07 250);
--color-brand-950: oklch(0.22 0.04 250);
}
Observe a coluna de croma: ela sobe para 0.18 em 500 e depois afina em ambas as direções. Esse é o arco em ação.
Passo 5: Conecte a escala ao bloco @theme#
Esta é a parte que é realmente nova no v4. Em vez de editar tailwind.config.js, você declara as cores do tema em CSS dentro de um bloco @theme, diretamente na sua folha de estilo principal:
@import "tailwindcss";
@theme {
--color-brand-50: oklch(0.97 0.02 250);
--color-brand-100: oklch(0.94 0.04 250);
--color-brand-200: oklch(0.89 0.07 250);
--color-brand-300: oklch(0.82 0.11 250);
--color-brand-400: oklch(0.74 0.15 250);
--color-brand-500: oklch(0.65 0.18 250);
--color-brand-600: oklch(0.55 0.17 250);
--color-brand-700: oklch(0.45 0.14 250);
--color-brand-800: oklch(0.37 0.10 250);
--color-brand-900: oklch(0.30 0.07 250);
--color-brand-950: oklch(0.22 0.04 250);
}
Como os nomes começam com --color-, o Tailwind gera automaticamente os utilitários: bg-brand-500, text-brand-700, border-brand-200 e assim por diante, além do valor brand correspondente em sintaxe arbitrária. Sem configuração JS, sem plugin, sem reinicialização necessária além da reconstrução normal do dev.
Aviso: variáveis que definem seus tokens de design devem estar dentro de
@theme, não em um bloco:rootsimples, se você quiser que o Tailwind gere utilitários a partir delas. Uma variável:rooté apenas uma variável CSS comum que o Tailwind ignora. Use@themepara tokens,:rootapenas para valores de tempo de execução únicos.
Passo 6: Use os utilitários e verifique em uma tela real#
Aplique as classes e verifique o resultado em um dispositivo real, idealmente um com tela P3 e outro sem. As cores devem parecer vívidas na tela de ampla gama e corretas (não quebradas) na tela sRGB. Se você suportar modo escuro, pode redefinir as mesmas variáveis dentro de um @theme com escopo no seu seletor escuro, trocando qual extremidade da escala mapeia para suas superfícies.
OKLCH vs Hex: O Que Realmente Muda no Seu Fluxo de Trabalho#
Para desenvolvedores que vêm da v3, a mudança pode parecer burocracia extra. Não é, quando você vê o retorno. Aqui está o antes e depois honesto.
| Aspecto | Tailwind v3 (hex/HSL) | Tailwind v4 (OKLCH) |
|---|---|---|
| Onde as cores vivem | tailwind.config.js (JavaScript) | Bloco @theme no CSS |
| Formato de cor | Hex ou HSL | OKLCH (L, C, H) |
| Uniformidade da escala | Ajuste manual, geralmente irregular | Etapas de luminosidade uniformes parecem equilibradas |
| Tons escuros | Tendem a ficar turvos | Permanecem ricos com baixa luminosidade |
| Gama ampla | Apenas sRGB | Gama P3 em telas compatíveis |
| Editar um tom | Recalcular hex manualmente | Ajustar um número (L, C ou H) |
A vantagem do dia a dia é a última linha. Quer um 600 um pouco mais vibrante? Aumente o croma em 0,02. Quer a escala inteira um pouco mais clara? Adicione 0,02 a cada valor de luminosidade. Como os canais são independentes e perceptuais, pequenas edições numéricas produzem mudanças visuais previsíveis, em vez do chute e verificação que você faz com hex.
Quando você ainda precisa de hex#
Alguns destinos ainda não falam OKLCH: certos clientes de e-mail, ferramentas de design antigas, algumas plataformas nativas. Para esses, exporte um fallback hex junto com seu tema OKLCH. O Tailwind v4 lida com fallback do navegador automaticamente para navegadores modernos, mas se você estiver passando cores para uma superfície não CSS, mantenha uma folha hex convertida. Um bom gerador fornece ambas as representações a partir da mesma cor de origem para que nunca se distanciem.
Integrando com Outros Tokens de Tema#
Uma paleta raramente vem sozinha. Depois que sua escala de marca está em @theme, o mesmo padrão se estende ao restante das variáveis de cor do tema: neutros, cores semânticas (sucesso, aviso, perigo) e superfícies. Construa cada uma como sua própria escala OKLCH com o mesmo ritmo de luminosidade, e todo o seu sistema permanecerá visualmente coerente porque cada cor compartilha o mesmo espaçamento perceptual.
Se o seu design também utiliza gradientes ou efeitos em camadas, defina-os a partir dos mesmos tokens OKLCH para que os pontos finais do gradiente correspondam exatamente à sua paleta. Uma maneira rápida de prototipar paradas de gradiente que se alinham com sua escala de marca é o gerador de gradiente CSS, que permite visualizar combinações antes de confirmá-las em um token. E quando você precisar exportar a marca resultante ou uma folha de amostras como ativo, o conversor de SVG para PNG transforma uma exportação vetorial em um arquivo raster para slides ou redes sociais.
Para o lado conceitual de escolher os matizes base corretos antes mesmo de abrir um gerador, o guia sobre um gerador de paleta de cores para design de marca aborda regras de harmonia e contraste de acessibilidade, que combinam naturalmente com a mecânica OKLCH aqui.
Conclusão#
Uma paleta de cores OKLCH para o Tailwind v4 não é apenas uma mudança de formato; é uma maneira melhor de pensar sobre cores. Ancore-se na cor da sua marca em 500, distribua a luminosidade uniformemente de 50 a 950, aumente o croma até o meio e reduza-o de volta, mantenha o matiz quase constante e, em seguida, declare toda a escala como variáveis --color-brand-* dentro de um bloco @theme. Faça isso e você obterá tons equilibrados, vívidos e sem sujeira, além da riqueza gratuita do P3 em telas modernas. Gere a escala, cole-a em @theme e publique.
Perguntas Frequentes#
O que é OKLCH e por que o Tailwind v4 o utiliza? OKLCH é um espaço de cor perceptual uniforme definido por Luminosidade, Croma e Matiz. O Tailwind v4 o adotou porque incrementar uniformemente a luminosidade produz tons que parecem igualmente espaçados ao olho humano, o que hex e HSL não conseguem fazer. O resultado são escalas balanceadas de 50 a 950 com escuros ricos e tons suaves, em vez de extremos opacos ou neon.
Onde defino cores personalizadas no Tailwind v4?
Dentro de um bloco @theme no seu CSS, não em um arquivo de configuração JavaScript. Declare cada tom como uma propriedade personalizada como --color-brand-500: oklch(0.65 0.18 250);. Como os nomes começam com --color-, o Tailwind gera automaticamente utilitários como bg-brand-500 e text-brand-700. Variáveis :root simples não geram utilitários, então use @theme para tokens de design.
Como luminosidade, croma e matiz se mapeiam para uma escala de 50 a 900? A luminosidade faz a maior parte do trabalho: mais alta em 50, mais baixa em 950, incrementando em etapas uniformes. O croma segue um arco, baixo nos extremos de tom e sombra e atingindo o pico por volta de 400-600 onde a cor é mais vívida. O matiz permanece quase constante em toda a escala, com apenas pequenos deslocamentos opcionais para realismo adicional.
Por que meus tons escuros baseados em hex parecem opacos, mas os OKLCH não? Em fluxos de trabalho HSL e hex, escurecer uma cor saturada frequentemente a arrasta para cinza ou marrom porque luminosidade e saturação estão entrelaçadas. OKLCH as separa, então você pode diminuir a luminosidade para um tom 700 ou 800 enquanto mantém o croma, mantendo a cor uma versão rica e reconhecível da sua marca, em vez de lama.
Ainda preciso de valores de cor hex com Tailwind v4? Para a web, não: navegadores modernos leem OKLCH e o Tailwind lida com fallbacks. Você ainda pode querer hex para destinos que não suportam OKLCH, como alguns clientes de e-mail, ferramentas de design antigas ou plataformas nativas. Gere ambos a partir da mesma cor de origem para que as representações nunca se distanciem.
Posso gerar uma escala Tailwind OKLCH automaticamente?
Sim. Um gerador de paleta que produz OKLCH cuidará do incremento uniforme de luminosidade e do arco de croma para você a partir de uma única cor de marca, e então fornecerá as linhas --color-brand-* para colar em @theme. Isso é mais rápido e confiável do que calcular manualmente cada etapa, o que é fácil de errar na curva de croma.
