CSS contrast-color(): testo nero o bianco automatico, e il suo limite reale

contrast-color() è una funzione CSS che prende un colore e restituisce il colore di testo che vi si legge meglio. È arrivata su tutti e quattro i motori principali ed è diventata Baseline Newly available ad aprile 2026. Risolve un problema piccolo e fastidioso in cui le interfacce personalizzabili inciampano di continuo, e ha un limite facile da mancare.

Cosa restituisce davvero

Solo due valori: white o black. Nient'altro. La funzione confronta il contrasto di entrambi con il colore passato e restituisce quello più alto. Se i due sono esattamente uguali, restituisce white.

Questa ristrettezza è proprio il punto. Non è una funzione generale di derivazione del colore: non produrra un grigio virato né una tinta vicina al tuo brand. Risponde a una sola domanda: su questo sfondo si legge meglio un testo scuro o uno chiaro?

La sintassi

Le passi qualsiasi valore <color> valido, inclusa una proprietà personalizzata:

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

Quella singola riga è il caso per cui e stata pensata. Un componente personalizzabile riceve lo sfondo da una variabile e il colore del testo segue in automatico: niente seconda variabile da tenere sincronizzata, niente JavaScript che legge lo stile calcolato.

Dove si guadagna il posto

La modalita chiara e scura e il caso più netto. Definisci lo sfondo una volta per schema e lascia che il testo segua:

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

Lo stesso schema vale per un colore d'accento scelto dall'utente, chip colorati per categoria e qualsiasi libreria di componenti in cui chi la usa passa uno sfondo che non puòi prevedere. Prima di questa funzione la risposta abituale era una mappa sfondo-testo mantenuta a mano, o un calcolo in fase di build.

Il limite da conoscere

MDN pubblica un avviso esplicito al riguardo, e vale la pena ripeterlo: il contrasto WCAG AA (4,5:1) non è raggiungibile su ogni sfondo. I toni medi falliscono in genere sia contro il nero sia contro il bianco. L'esempio documentato è un blu reale, #2277d3: contrast-color() restituisce nero, e quel nero su quel blu non è leggibile a corpi piccoli.

La funzione ti dice quindi quale delle due opzioni e migliore, non che il risultato sia sufficiente. Su uno sfondo di tono medio nessuna delle due lo è. La regola pratica è quella data da MDN: usala con colori chiaramente chiari o chiaramente scuri, e tieni una verifica reale del contrasto nel tuo processo per tutto cio che sta in mezzo.

Se hai dubbi che uno sfondo cada in quella trappola dei toni medi, passalo per il nostro verificatore di contrasto WCAG prima di pubblicare.

Supporto dei browser

Baseline Newly available da aprile 2026, cioè funziona nelle versioni stabili attuali di Chrome, Edge, Firefox e Safari, su desktop e mobile. La differenza tra «Newly» e «Widely» conta: i dispositivi vecchi e i browser non aggiornati non ce l'hanno. Poiché dove non è supportata la dichiarazione semplicemente non viene interpretata, una dichiarazione color messa prima nella stessa regola funge da fallback naturale.

Riferimento rapido

Domanda	Risposta
Valori di ritorno possibili	solo white o black
Parita tra i due	restituisce white
Accetta una proprietà personalizzata	si: contrast-color(var(--c))
Garantisce WCAG AA	no: i toni medi falliscono da entrambi i lati
Stato Baseline	Newly available, aprile 2026
Fallback	dichiarare color prima nella stessa regola

Usala dove lo sfondo è davvero imprevedibile e chiaramente chiaro o scuro. Non farne un sostituto della scelta di colori leggibili in partenza: sceglie la migliore fra due opzioni, che non è la stessa cosa che produrne una buona.