CSS contrast-color(): texto negro o blanco automático, y su límite real

contrast-color() es una función CSS que toma un color y devuelve el color de texto que mejor se lee sobre él. Llegó a los cuatro motores principales y pasó a ser Baseline Newly available en abril de 2026. Resuelve un problema pequeno y molesto con el que tropiezan constantemente las interfaces tematizables, y tiene un limite fácil de pasar por alto.

Qué devuelve en realidad

Solo dos valores: white o black. Nada más. La función compara el contraste de ambos con el color que le pasas y devuelve el mayor. Si los dos son exactamente iguales, devuelve white.

Esa estrechez es justamente el punto. No es una función general de derivación de color: no producira un gris matizado ni un tono cercano a tu marca. Responde a una sola pregunta: sobre este fondo, ¿se lee mejor el texto oscuro o el claro?

La sintaxis

Le pasas cualquier valor <color> valido, incluida una propiedad personalizada:

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

Esa única línea es el caso para el que se creo. Un componente tematizable recibe su fondo desde una variable y el color del texto lo sigue automáticamente: ni una segúnda variable que mantener sincronizada, ni JavaScript leyendo el estilo calculado.

Donde se gana su sitio

El modo claro y oscuro es el caso más claro. Define el fondo una vez por esquema y deja que el texto siga:

: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));
}

El mismo patrón sirve para un color de acento elegido por el usuario, etiquetas coloreadas por categoría y cualquier librería de componentes donde quien la consume pasa un fondo que no puedes prever. Antes de esta función, la respuesta habitual era un mapa fondo-texto mantenido a mano o un calculo en tiempo de build.

El limite que conviene conocer

MDN publica una advertencia explicita sobre esto y merece repetirse: el contraste WCAG AA (4,5:1) no es alcanzable en todos los fondos. Los tonos medios suelen fallar tanto contra el negro como contra el blanco. El ejemplo documentado es un azul rey, #2277d3: contrast-color() devuelve negro, y ese negro sobre ese azul no es legible en tamaños de texto pequeños.

La función te dice, pues, cual de las dos opciones es mejor, no que el resultado sea suficiente. Sobre un fondo de tono medio ninguna lo es. La regla practica es la que da MDN: úsala con colores claramente claros o claramente oscuros, y mantén una comprobación real de contraste en tu proceso para todo lo que quede en medio.

Si dudas de si un fondo cae en esa trampa de los tonos medios, pásalo por nuestro verificador de contraste WCAG antes de publicar.

Soporte de navegadores

Baseline Newly available desde abril de 2026, es decir, funcióna en las versiónes estables actuales de Chrome, Edge, Firefox y Safari, en escritorio y móvil. La diferencia entre «Newly» y «Widely» importa: los dispositivos antiguos y los navegadores sin actualizar no la tienen. Como la declaración sencillamente no se analiza donde no hay soporte, una declaración color puesta antes en la misma regla actua de reserva natural.

Referencia rapida

Pregunta	Respuesta
Valores de retorno posibles	solo white o black
Empate entre ambos	devuelve white
Acepta una propiedad personalizada	si: contrast-color(var(--c))
Garantiza WCAG AA	no: los tonos medios fallan por ambos lados
Estado Baseline	Newly available, abril de 2026
Reserva	declarar color antes en la misma regla

Úsala donde el fondo sea de verdad imprevisible y claramente claro u oscuro. No la conviertas en sustituto de elegir colores legibles desde el principio: escoge la mejor de dos opciones, que no es lo mismo que producir una buena.