CSS contrast-color(): texto preto ou branco automático, e o seu limite real

contrast-color() é uma função CSS que recebe uma cor e devolve a cor de texto que melhor se lê sobre ela. Chegou aos quatro motores principais e passou a Baseline Newly available em abril de 2026. Resolve um problema pequeno e irritante com que as interfaces tematizáveis tropecam constantemente, e tem um limite fácil de passar ao lado.

O que devolve na realidade

Apenas dois valores: white ou black. Mais nada. A função compara o contraste de ambos com a cor que lhe passas e devolve o maior. Se os dois forem exatamente iguais, devolve white.

Essa estreiteza é precisamente o ponto. Não é uma função geral de derivação de cor: não produzirá um cinzento matizado nem um tom próximo da tua marca. Responde a uma única pergunta: sobre este fundo, lê-se melhor texto escuro ou claro?

A sintaxe

Passas qualquer valor <color> valido, incluindo uma propriedade personalizada:

button {
  background-color: var(--button-color);
  color: contrast-color(var(--button-color));
}

Essa única linha e o caso para que foi feita. Um componente tematizavel recebe o fundo de uma variavel e a cor do texto segue automaticamente: nem uma segunda variavel para manter sincronizada, nem JavaScript a ler o estilo calculado.

Onde vale a pena

O modo claro e escuro é o caso mais nítido. Define o fundo uma vez por esquema e deixa o texto seguir:

:root {
  --background-color: navy;
}

@media (prefers-color-scheme: light) {
  :root {
    --background-color: wheat;
  }
}

body,
a {
  background-color: var(--background-color);
  color: contrast-color(var(--background-color));
}

O mesmo padrão serve para uma cor de destaque escolhida pelo útilizador, etiquetas coloridas por categoria e qualquer biblioteca de componentes em que quem a usa passa um fundo que não consegues prever. Antes desta função, a resposta habitual era um mapa fundo-para-texto mantido a mao, ou um calculo em tempo de build.

O limite que convem conhecer

A MDN publica um aviso explicito sobre isto e vale a pena repeti-lo: o contraste WCAG AA (4,5:1) não é atingível em todos os fundos. Os tons médios costumam falhar tanto contra o preto como contra o branco. O exemplo documentado é um azul-rei, #2277d3: contrast-color() devolve preto, e esse preto sobre esse azul não é legível em corpos pequenos.

A função diz-te, portanto, qual das duas opções é melhor, não que o resultado seja suficiente. Num fundo de tom medio nenhuma o é. A regra prática é a que a MDN dá: usa-a com cores claramente claras ou claramente escuras, e mantém uma verificação real de contraste no teu processo para tudo o que fique pelo meio.

Se tiveres dúvidas de que um fundo caia nessa armadilha dos tons médios, passa-o por o nosso verificador de contraste WCAG antes de publicares.

Suporte dos navegadores

Baseline Newly available desde abril de 2026, ou seja, funciona nas versões estaveis atuais do Chrome, Edge, Firefox e Safari, em computador e telemóvel. A diferenca entre «Newly» e «Widely» conta: os aparelhos antigos e os navegadores desatualizados não a tem. Como a declaração simplesmente não é interpretada onde não há suporte, uma declaração color colocada antes na mesma regra funciona como recurso natural.

Referencia rapida

Pergunta	Resposta
Valores de retorno possiveis	apenas white ou black
Empate entre os dois	devolve white
Aceita uma propriedade personalizada	sim: contrast-color(var(--c))
Garante WCAG AA	não: os tons médios falham dos dois lados
Estado Baseline	Newly available, abril de 2026
Recurso	declarar color antes na mesma regra

Usa-a onde o fundo seja mesmo imprevisível e claramente claro ou escuro. Não faças dela um substituto de escolher cores legíveis à partida: escolhe a melhor de duas opções, o que não é o mesmo que produzir uma boa.