Color theory

Escopo: transversal. Aplica-se a qualquer interface, em qualquer linguagem ou stack do projeto.

Cor não é decoração. Cada cor numa interface comunica hierarquia, estado, temperatura emocional e legibilidade. Decisões aleatórias produzem interfaces que cansam o olho, falham em acessibilidade e se descontrolam em escala. Este guia consolida a teoria mínima necessária para decidir cores com intenção: do círculo cromático ao espaço OKLCH (Lightness, Chroma, Hue, espaço de cor perceptualmente uniforme), das harmonias ao WCAG (Web Content Accessibility Guidelines, Diretrizes de Acessibilidade para Conteúdo Web), da hierarquia de superfícies à escala tonal.

Para padrões de espaçamento, tipografia e estados, consulte ui-ux.md. Para densidade visual em código, consulte visual-density.md.

O círculo cromático organiza os matizes em 360°. Cores primárias (vermelho, amarelo, azul) não podem ser obtidas por mistura. Secundárias (laranja, verde, violeta) resultam da mistura de duas primárias. Terciárias combinam uma primária com uma secundária adjacente.

Sistemas de design tradicionalmente usavam RGB (Red, Green, Blue, espaço aditivo de monitor) e HSL (Hue, Saturation, Lightness, projeção cilíndrica de RGB). Ambos sofrem do mesmo problema: a "luminosidade" numérica não corresponde à percepção visual. Um amarelo com hsl(50, 100%, 50%) parece muito mais brilhante que um azul com hsl(240, 100%, 50%), mesmo com o mesmo valor de L.

OKLCH corrige isso. É um espaço perceptualmente uniforme: um passo de +0.10 em L produz a mesma diferença visual independentemente do matiz. Resultado prático: escalas tonais geradas em OKLCH são previsíveis e visualmente balanceadas, qualidade essencial para temas acessíveis.

oklch(L C H)
       │ │ │
       │ │ └─ Hue (matiz)        : 0° a 360°
       │ └─── Chroma (croma)     : 0 a ~0.4 em sRGB
       └───── Lightness (clara)  : 0 a 1

Cores quentes avançam visualmente: parecem mais próximas. Cores frias recuam. Esse efeito é útil para criar separação de planos sem depender só de luminosidade.

Harmonias são relações geométricas no círculo cromático que produzem paletas coesas. Cada harmonia tem uma personalidade distinta e serve a contextos diferentes. As referências abaixo usam H = 250° (azul) como base.

Neutros não são uma harmonia rotacional: são variações de luminosidade da cor base com croma reduzido. Em vez de cinzas puros (oklch(L 0 0)), neutros tonalizados (oklch(L 0.005 250)) integram melhor com o resto da paleta e dão acabamento profissional.

Decisões de cor não param na escolha da paleta. Como as cores são distribuídas na tela define se a interface respira ou sufoca, se a hierarquia é clara ou plana.

Distribua as cores em proporções definidas:

Essa proporção cria equilíbrio visual e direciona a atenção para os elementos certos. Inverter (cor de destaque ocupando 30 ou 60%) gera interfaces agressivas que cansam rapidamente.

Cores com maior contraste atraem o olhar primeiro. Use cores saturadas e de alto contraste em elementos de ação (botões primários, alertas) e cores neutras em elementos de suporte (bordas, fundos de seção, texto secundário). Quando tudo tem o mesmo peso visual, nada parece importante.

São dois eixos independentes que separam planos visuais.

Combinar os dois (texto escuro frio sobre fundo claro quente) produz separação muito mais nítida que cada um isolado.

O espaço negativo (branco no tema claro, neutro escuro no tema escuro) é uma cor ativa na composição. Cria respiro, separa grupos e amplifica a percepção das cores adjacentes. Esse princípio se conecta diretamente à densidade visual em código (ver visual-density.md): em UI (User Interface, interface do usuário) ou em código, agrupamento por respiro é a estrutura que guia a leitura.

Não tente preencher todos os espaços. Interface sem respiro tem o mesmo problema que código sem linhas em branco entre grupos: o olho não sabe onde uma seção termina e outra começa.

WCAG define critérios mensuráveis de acessibilidade em três níveis: A (mínimo), AA (padrão da indústria) e AAA (Triple-A, excelência). A maioria dos produtos digitais busca AA. AAA é exigido em contextos críticos como saúde e serviços governamentais.

A proporção de contraste compara a luminância relativa de duas cores. Branco puro (#fff) tem luminância 1.0; preto puro (#000) tem luminância 0. A proporção máxima possível é 21 : 1 (branco sobre preto). Uma proporção de 4.5 : 1 significa que a cor mais clara é 4.5 vezes mais luminosa que a mais escura.

O cálculo oficial de contraste do WCAG 2.x usa luminância em sRGB (Standard RGB, espaço de cor padrão para web), não OKLCH. Mesmo assim, a uniformidade perceptual do OKLCH torna paletas geradas neste espaço previsíveis: paradas afastadas por 4 ou mais posições na escala tonal tendem a satisfazer AA na maioria dos matizes.

O WCAG 3.0 (em desenvolvimento) deve adotar APCA, que usa luminância perceptual próxima ao OKLCH. Paletas projetadas em OKLCH já estão alinhadas com essa direção.

Interfaces modernas são compostas por camadas empilhadas. Cada camada tem uma função semântica e uma cor associada. Entender essa estrutura é essencial para criar temas consistentes.

foreground  → texto e ícones       (L máximo de contraste)
popover     → modais, dropdowns    (L 1.000 + sombra profunda)
card        → containers           (L 1.000 + sombra suave)
surface     → sidebars, painéis    (L 0.970)
background  → plano base           (L 0.985)

Para que duas superfícies adjacentes sejam percebidas como distintas, a diferença de L em OKLCH deve ser de pelo menos 0.05 a 0.08, equivalente a 1 ou 2 paradas na escala tonal. Diferenças menores criam névoa visual: o usuário não percebe a separação entre camadas.

Interfaces com muitas cores saturadas em proximidade causam fadiga. A solução é reduzir o croma das cores de fundo e reservar croma alto para elementos interativos e de destaque. Em OKLCH, manter croma abaixo de 0.05 em backgrounds garante neutralidade sem perder a tonalidade da paleta.

Sombras pretas puras parecem genéricas e brigam com o tema. Sombras tonalizadas com a cor base da paleta (um azul desaturado para tema frio, um marrom para tema quente) integram melhor e parecem mais naturais. No dark mode, prefira diferença de luminosidade entre superfícies a sombras opacas, que desaparecem em fundo escuro.

Criar um tema escuro de qualidade não é inverter as cores do tema claro. São estratégias distintas que exigem atenção a como o olho humano percebe luz em cada contexto. Para variáveis semânticas e tokens, ver ui-ux.md.

Fundos muito escuros (L abaixo de 0.10 em OKLCH) criam contraste máximo com qualquer conteúdo e cansam os olhos em uso prolongado. Os melhores dark themes usam L entre 0.12 e 0.18 para o background: escuro o suficiente para parecer dark, com ar suficiente para o conteúdo respirar.

Texto branco puro (#fff) sobre fundo escuro cria contraste de 21:1, muito além do necessário. Isso causa halação (glare, brilho ofuscante). Use um off-white com L entre 0.92 e 0.97 para texto primário e L entre 0.60 e 0.75 para texto secundário.

Em fundos escuros, cores de destaque precisam de mais luminosidade e um pouco mais de croma para saltar da superfície. Uma cor de botão primário que funciona com L = 0.55 no light mode pode precisar de L = 0.65 a 0.70 no dark mode para manter o mesmo impacto visual.

Em tema claro, bordas com opacidade de 15-20% funcionam bem. Em dark mode, bordas opacas escuras se fundem com o fundo. Use bordas claras com opacidade de 8-12% (oklch(1 0 0 / 10%)) para separar cards sem criar peso visual excessivo.

Dark themes devem ser testados em tela com brilho reduzido, simulando uso noturno. Light themes devem ser testados sob luz ambiente forte. Um contraste que parece adequado no monitor calibrado do desenvolvedor pode falhar para usuários em condições diferentes.

A escala tonal padrão (50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950) é a principal ferramenta de composição em sistemas de design. Cada parada tem L pré-calculado para produzir contraste previsível.

Em OKLCH, a parada 50 tem L aproximado de 0.97 e a parada 900 tem L aproximado de 0.22. A diferença de 0.75 produz contraste WCAG muito acima de 7:1 (AAA), independentemente do matiz, graças à uniformidade perceptual do espaço.

Para garantir WCAG AA (4.5:1) em qualquer matiz, mantenha diferença mínima de 4 paradas entre fundo e texto (fundo 100 com texto 500, fundo 400 com texto 800). Para AAA, use diferença de 6 ou mais paradas. Diferenças menores podem passar em alguns matizes e falhar em outros.

A parada 500 fica no centro da escala, geralmente com L aproximado de 0.55, ponto onde croma costuma atingir o pico. É a escolha natural para cor de destaque interativo: tem identidade forte e contrasta bem com paradas altas (claras) e baixas (escuras).

Amarelo (H ≈ 95°) e ciano (H ≈ 200°) têm luminância sRGB percebida muito alta mesmo com L moderado em OKLCH. Um amarelo com oklch(0.60 0.20 95) falha o WCAG AA contra branco, enquanto um azul com oklch(0.60 0.18 250) passa confortavelmente, mesmo com a mesma luminosidade OKLCH. Sempre verificar o contraste com ferramenta WCAG ao escolher matizes nessas faixas.

A regra prática: para amarelos e cianos sobre branco, reduzir L para 0.45 ou menos antes de assumir que passa contraste.

Desenvolvido por @thiagocajadev · Fork baseado no repositório pmndrs/docs · Poimandres.