CSS-Variablen ist eine geläufige Alternativbezeichnung für CSS custom properties, Einheiten, die in einem CSS-Stylesheet definiert und anschließend innerhalb des selben oder eines anderen Stylesheets wiederverwendet werden können. Sie dienen damit der Redundanzvermeidung nach dem DRY-Prinzip.

CSS-Variablen sind durch zwei führende Kurzstriche -- gekennzeichnet, auf die der Name der Variable folgt. Sie werden, wie Attributzuweisungen in CSS, innerhalb eines auf einen Selektor bezogenen Regelblocks definiert:

:root {
  --color-white: #ffffff;
}

Die CSS-Variable --color-white bekommt den hexadezimalen Farbcode für die Farbe Weiß zugewiesen. Dies erfolgt innerhalb des :root-Selektors, der die globale CSS-Umgebung des Dokuments repräsentiert.

Der gewählte Selektor beeinflusst die Gültigkeit der CSS-Variable. CSS-Variablen erhalten ihren Wert nur innerhalb des selektierten Elements sowie dessen Unterelementen in der Baumstruktur des Dokuments. Das hat zur Folge, dass eine CSS-Variable innerhalb des selben Dokuments mehrere Werte repräsentieren oder definiert oder nicht definiert sein kann. Sie verhält sich somit nicht wie eine klassische Variable.

Auf den Wert der CSS-Variable kann mithilfe der Funktion var() zugegriffen werden:

.weisser-hintergrund {
  background-color: var(--color-white);
}
.weisser-text {
  color: var(--color-white);
}

Der in --color-white definierte Farbwert (in diesem Fall gemäß obigem Beispiel #ffffff) wird dann background-color bzw. color zugewiesen.

Für den Fall, dass eine CSS-Variable innerhalb des aufrufenden Selektors nicht definiert ist, kann var() ein optionaler Rückfallwert mit Komma getrennt hinter dem Variablennamen übergeben werden:

.weisser-hintergrund {
  background-color: var(--color-white, #ffffff);
}

Wenn die CSS-Variable --color-white nicht gefunden wird, erhält das mit der Klasse weisser-hintergrund ausgezeichnete Element dennoch eine Hintergrundfarbe, nämlich das explizit angegebene #ffffff aus dem Rückfallwert. Ansonsten hat immer der Wert aus der Variable Vorrang und der Rückfallwert wird ignoriert.

Verschachteln von CSS-Variablen sowie Aufrufen von var() ist möglich:

:root {
  --color-white: #ffffff;
  --color-gray: #dddddd;
  --background-primary: var(--color-white, var(--color-gray, #ffffff));
}

In diesem Fall ist der Wert von --background-primary gleich dem von --color-white. Existiert --color-white nicht, erhält --background-primary den Wert von --color-gray (Rückfallwert von --color-white). Existiert auch --color-gray nicht, wird #ffffff zugewiesen (weiterer Rückfallwert).

Über das Wikimedia-Designsystem Codex können die dort definierten Design-Tokens (etwa Farbwerte oder Zeilen- und Texthöhen) über CSS-Variablen in MediaWiki zugänglich gemacht und genutzt werden.

Ob die von Codex definierten CSS-Variablen zur Verfügung stehen, hängt vom jeweiligen Skin ab. Gegenwärtig sind sie nur im Minerva-Skin und im Skin Vector-2022 verfügbar. Ob zu einem späteren Zeitpunkt ältere Skins auf die Nutzung von Codex umgestellt und die CSS-Variablen dadurch auch in diesen verfügbar werden, ist unbekannt. Theoretisch ist es möglich, dass in Skins auch unabhängig von Codex weitere CSS-Variablen eingeführt werden.

Die von MediaWiki definierten CSS-Variablen sind in der globalen CSS-Umgebung des Dokuments (mit :root) definiert und stehen direkt nach dem Seitenaufbau zur Verfügung. Eine Liste der von Codex definierten CSS-Variablen ist in Gitiles verfügbar.

Auch in den lokalen CSS-Ressourcen der deutschsprachigen Wikipedia ist die Definition und Nutzung von CSS-Variablen in Attributzuweisungen möglich. Hierbei bestehen jedoch Unterschiede zwischen den projektweiten CSS-Ressourcen (Gadgets, Common.css, Benutzerskripte), TemplateStyles sowie der Verwendung direkt im Seitenquelltext (style-Attribut):

• in projektweiten CSS-Ressourcen:
  • ist die Definition sowie die Nutzung von lokalen und in MediaWiki definierten CSS-Variablen uneingeschränkt möglich
• in TemplateStyles-Seiten:
  • ist die Definition von CSS-Variablen unzulässig
  • können bestehende lokale und in MediaWiki definierte CSS-Variablen im Kontext von Farbattributzuweisungen verwendet werden
  • ist die Nutzung von CSS-Variablen in Attributen, die eine Verknüpfung mehrerer Ausdrücke ermöglichen (etwa border, background) unzulässig
• im Seitenquelltext:
  • ist die Nutzung von lokalen und in MediaWiki definierten CSS-Variablen uneingeschränkt möglich
  • ist die Definition von CSS-Variablen derzeit noch möglich. Es ist jedoch geplant, dies alsbald zu verhindern.

Die Nutzung von CSS-Variablen in Bereichen, die nicht allein der Bearbeitung durch Benutzeroberflächenadministratoren unterliegen (also TemplateStyles und Seitenquelltext) ist aus Sicherheitsgründen eingeschränkt. Durch geschickte Manipulation von CSS-Variablen könnte es einem Angreifer ansonsten gelingen, die Seitendarstellung zu ändern oder Benutzerdaten abzugreifen.

In der deutschsprachigen Wikipedia werden projektweit verfügbare CSS-Variablen genutzt, um wiederkehrende Hintergrund- und Rahmenfarben zentral zu definieren und dann in Gadgets und TemplateStyles wiederverwenden zu können. Werden diese in einem reinen CSS-Gadget geladen, stehen sie sofort mit dem Seitenaufbau zur Verfügung. Mit JavaScript nachgeladene CSS-Ressourcen werden erst später verfügbar, deshalb kann es in diesen Fällen zu einem Flash of Unstyled Content kommen.

Folgende Gadgets definieren eigene CSS-Variablen für die projektweite Nutzung:

• dewikiCommonStyle (MediaWiki:Gadget-dewikiCommonStyle.css):
  • Farben für die Klassen hintergrundfarbe1 bis hintergrundfarbe9 sowie rahmenfarbe1 bis rahmenfarbe5 (siehe Hilfe:Farben)

Zur Unterscheidung von in MediaWiki definierten sowie nur für die Nutzung innerhalb eines Gadgets vorgesehenen CSS-Variablen sollen für die deutschsprachige Wikipedia spezifische projektweit verfügbare CSS-Variablen das Präfix --dewiki- erhalten.

Prinzipiell möglich, aber derzeit nicht angewendet, ist die Definition von CSS-Variablen innerhalb eines begrenzten Anwendungsfalls (etwa eines Gadgets), um das zugehörige CSS-Stylesheet zu vereinfachen. Diese Variablen dürfen dann nicht in der :root-Umgebung des Dokuments definiert werden, sondern sollen über einen gadgetspezifischen Selektor auf das jeweilige Gadget beschränkt sein.

Der Name der CSS-Variable soll in diesem Fall auf das definierende Gadget Bezug nehmen.

Die Nutzung von in MediaWiki (etwa über Codex) definierten CSS-Variablen in lokalen Ressourcenseiten sowie im Seitenquelltext ist grundsätzlich möglich. Dabei ist zu beachten:

• ihr Wert kann sich je nach Seite, Anzeigemodus (Hell-/Dunkelmodus) oder Skin unterscheiden
• sie können in einigen Skins nicht definiert sein
• ihr Name kann sich ändern

Aus diesem Grund ist es unbedingt ratsam, bei Bezugnahme auf in MediaWiki definierte CSS-Variablen über var() einen Rückfallwert anzugeben, der genutzt wird, wenn diese nicht definiert ist. Zudem sollten die Werte in den gängigen Skins und Anzeigemodi geprüft werden, um unerwünschte Effekte zu vermeiden.

• englischsprachige Dokumentation zu CSS custom properties