CSS contrast-color(): automatisch schwarzer oder weißer Text, und die eine echte Grenze

contrast-color() ist eine CSS-Funktion, die eine Farbe entgegennimmt und die Textfarbe zurückgibt, die sich darauf am besten liest. Sie ist in allen vier großen Engines angekommen und wurde im April 2026 Baseline Newly available. Sie loest ein kleines, lästiges Problem, auf das themenfaehige Oberflaechen ständig stossen, und sie hat eine Grenze, die man leicht übersieht.

Was sie wirklich zurückgibt

Nur zwei Werte: white oder black. Sonst nichts. Die Funktion vergleicht den Kontrast beider zur übergebenen Farbe und gibt den hoeheren zurück. Sind beide exakt gleich, gibt sie white zurück.

Diese Enge ist der Punkt. Es ist keine allgemeine Funktion zur Farbableitung: Sie erzeugt weder ein getoentes Grau noch einen markennahen Ton. Sie beantwortet genau eine Frage: Liest sich auf diesem Hintergrund dunkler oder heller Text besser?

Die Syntax

Du übergibst einen beliebigen gültigen <color>-Wert, auch eine Custom Property:

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

Diese eine Zeile ist der Fall, für den sie gebaut wurde. Eine themenfaehige Komponente bekommt ihren Hintergrund aus einer Variablen, und die Textfarbe folgt automatisch: keine zweite Variable, die synchron gehalten werden muss, kein JavaScript, das den berechneten Stil ausliest.

Wo sie sich lohnt

Hell- und Dunkelmodus ist der klarste Fall. Den Hintergrund einmal je Schema definieren und den Text folgen lassen:

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

Dasselbe Muster gilt für eine vom Nutzer gewählte Akzentfarbe, nach Kategorie eingefaerbte Chips und jede Komponentenbibliothek, in der jemand einen Hintergrund uebergibt, den du nicht vorhersehen kannst. Vor dieser Funktion war die uebliche Antwort eine handgepflegte Zuordnung von Hintergrund zu Text oder eine Berechnung zur Build-Zeit.

Die Grenze, die man kennen sollte

MDN veroeffentlicht dazu eine ausdrueckliche Warnung, und sie gehoert wiederholt: WCAG-AA-Kontrast (4,5:1) ist nicht auf jedem Hintergrund erreichbar. Mitteltöne scheitern in der Regel sowohl gegen Schwarz als auch gegen Weiß. Das dokumentierte Beispiel ist ein Königsblau, #2277d3: contrast-color() gibt Schwarz zurück, und dieses Schwarz auf diesem Blau ist in kleinen Textgrößen nicht lesbar.

Die Funktion sagt dir also, welche der zwei Optionen die bessere ist, nicht dass das Ergebnis gut genug ist. Auf einem Mittelton ist keine der beiden gut genug. Die praktische Regel ist die von MDN: mit klar hellen oder klar dunklen Farben verwenden und für alles dazwischen eine echte Kontrastprüfung im Prozess behalten.

Wenn du unsicher bist, ob ein Hintergrund in diese Mittelton-Falle fällt, schick ihn vor dem Ausliefern durch unseren WCAG-Kontrastprüfer.

Browserunterstützung

Baseline Newly available seit April 2026, also verfuegbar in den aktuellen stabilen Versionen von Chrome, Edge, Firefox und Safari, auf Desktop und Mobil. Der Unterschied zwischen „Newly" und „Widely" zählt: alte Geraete und nicht aktualisierte Browser haben sie nicht. Da die Deklaration dort, wo sie nicht unterstuetzt wird, schlicht nicht geparst wird, wirkt eine zuvor in derselben Regel notierte color-Deklaration als natürlicher Fallback.

Kurzreferenz

Frage	Antwort
Mögliche Rückgabewerte	nur white oder black
Gleichstand	gibt white zurück
Nimmt eine Custom Property	ja: contrast-color(var(--c))
Garantiert WCAG AA	nein: Mitteltöne scheitern beidseitig
Baseline-Status	Newly available, April 2026
Fallback	color davor in derselben Regel deklarieren

Setze sie dort ein, wo der Hintergrund wirklich unvorhersehbar und klar hell oder dunkel ist. Mach sie nicht zum Ersatz dafür, von vornherein lesbare Farben zu waehlen: Sie trifft die bessere von zwei Entscheidungen, was nicht dasselbe ist wie eine gute.