Custom Properties als API Vertrag für Komponenten

1. Warum Custom Properties eine API sind, keine Implementierung

Custom Properties werden in den meisten Projekten wie ein reines Implementierungsdetail behandelt: eine Farbe wird als Variable ausgelagert, weil es bequemer ist, nicht weil bewusst eine Schnittstelle für Konsumenten entworfen wurde. Das Problem zeigt sich erst später, wenn ein anderes Team, ein anderes Projekt oder ein Theming-System versucht, eine Komponente von außen anzupassen, indem es genau diese Custom Property überschreibt, und dabei feststellt, dass sich der interne Name jederzeit ändern kann, weil er nie als stabile Schnittstelle gedacht war.

Der entscheidende gedankliche Sprung: Sobald eine Custom Property von außerhalb der eigenen Komponente gesetzt oder gelesen wird, egal ob von einem Theming-Layer, einem Konsumenten-Team oder einer anderen Komponente, ist sie de facto Teil der öffentlichen API dieser Komponente. Genau wie eine PHP-Methode mit public-Sichtbarkeit nicht ohne Ankündigung umbenannt werden sollte, sollte eine öffentlich genutzte Custom Property denselben Stabilitätsanspruch erfüllen wie jede andere öffentliche Schnittstelle im Software-Design.

Dieser Artikel behandelt Custom Properties konsequent als API-Vertrag: mit Namensraum-Konventionen, die private von öffentlichen Werten trennen, mit dokumentierten Fallback-Werten, mit einer Strategie für Breaking Changes und mit Testmethoden, die eine versehentliche Vertragsverletzung frühzeitig erkennen. Das Ziel ist ein Design System, in dem Konsumenten einer Komponente sich auf ihre Custom Properties genauso verlassen können wie auf eine dokumentierte Funktionssignatur.

2. Namensraum: private und öffentliche Custom Properties trennen

Der erste Schritt zu einem belastbaren API-Vertrag ist eine konsequente Namenskonvention, die öffentliche von privaten Custom Properties unterscheidet. Ein bewährtes Muster: Öffentliche Properties folgen dem Schema --komponente-eigenschaft, etwa --button-bg, während private, ausschließlich intern berechnete Werte ein zusätzliches Präfix wie --_button-bg-computed tragen. Diese Konvention macht am Namen selbst erkennbar, ob ein Konsument eine Property sicher überschreiben darf oder nicht, ohne dass eine separate Dokumentation konsultiert werden muss.

Underscore-Präfixe sind in CSS nicht technisch erzwingbar wie ein private-Keyword in einer Programmiersprache, sie sind reine Konvention. Genau deshalb muss diese Konvention im Team dokumentiert und über Code-Reviews durchgesetzt werden. Ein Linter-Regelwerk, das prüft, ob Properties mit Unterstrich-Präfix jemals außerhalb der definierenden Datei referenziert werden, deckt Verstöße gegen diesen Vertrag frühzeitig auf, bevor sie sich zu impliziten Abhängigkeiten verfestigen.

/* Public API: stable, documented, safe for consumers to override */
.c-button {
  --button-bg: var(--color-brand-500);
  --button-fg: white;
  --button-radius: 0.5rem;

  /* Private, computed internally, name signals "do not touch" */
  --_button-bg-hover: color-mix(in oklch, var(--button-bg) 85%, black);

  background: var(--button-bg);
  color: var(--button-fg);
  border-radius: var(--button-radius);
}

.c-button:hover {
  background: var(--_button-bg-hover);
}

/* Consumer safely overrides the public contract, never the private detail */
.c-button--danger {
  --button-bg: var(--color-danger-500);
}

3. Fallbacks als Vertragsbestandteil

Ein oft übersehener Teil des API-Vertrags ist der Fallback-Wert innerhalb von var(). Die Syntax var(--button-radius, 0.5rem) definiert nicht nur einen Notausgang für den Fall, dass die Property nicht gesetzt ist, sie dokumentiert gleichzeitig den Standardwert der Komponente direkt im Code, lesbar für jeden, der die Regel öffnet, ohne eine externe Settings-Datei durchsuchen zu müssen. Diese Custom Properties mit explizitem Fallback funktionieren wie ein Funktionsparameter mit Standardwert in einer typisierten Programmiersprache.

Ein API-Vertrag mit Fallback-Werten ist widerstandsfähiger gegen fehlerhafte Integration. Vergisst ein Konsument, die zentrale Settings-Datei einzubinden, in der --button-radius global definiert wird, greift die Komponente auf den lokalen Fallback zurück und bleibt visuell funktionsfähig, statt mit border-radius: ; stillschweigend ins Leere zu laufen. Dieses Verhalten sollte bewusster Teil des Vertrags sein, nicht ein Zufallsprodukt der jeweiligen Browser-Implementierung.

/* Fallback values document the contract's default behavior in place */
.c-card {
  background: var(--card-bg, #ffffff);
  padding: var(--card-padding, 1.5rem);
  border-radius: var(--card-radius, 0.75rem);
  box-shadow: var(--card-shadow, 0 4px 12px rgb(0 0 0 / 8%));
}

/* Consumer overrides only what differs from the documented default */
.c-card--compact {
  --card-padding: 0.75rem;
}

4. Stabilität und Versionierung ohne Build-Tooling

Anders als bei einer JavaScript-Bibliothek gibt es für Custom Properties kein natives Semver-Konzept, keinen Package Manager, der eine Breaking-Change-Warnung ausgibt. Stabilität muss deshalb durch Konvention und Disziplin erzeugt werden. Ein pragmatischer Ansatz: ein Kommentarblock über jeder Komponentendatei, der die öffentlichen Custom Properties explizit auflistet, ähnlich einem Interface in einer typisierten Sprache, ergänzt um ein Änderungsdatum und eine kurze Beschreibung jeder Property.

Für Design Systeme mit vielen Konsumenten empfiehlt sich zusätzlich ein Deprecation-Zeitraum: Eine alte Property bleibt funktional erhalten und wird intern auf die neue Property umgeleitet, während eine Konsolen-Warnung, etwa via einem begleitenden Lint-Skript, auf die Umbenennung hinweist. Dieser Übergangszeitraum gibt Konsumenten Zeit, ihren Code anzupassen, bevor die alte Custom Property endgültig entfernt wird, statt einen sofortigen Bruch ohne Vorwarnung zu erzeugen.

/**
 * Public API contract for .c-badge (component version 2.1)
 * --badge-bg        background color, default: brand-500
 * --badge-fg        text color, default: white
 * --badge-size      inline padding scale, default: 0.5rem
 *
 * Deprecated (removed in 3.0): --badge-color, use --badge-bg instead
 */
.c-badge {
  --badge-bg: var(--badge-color, var(--color-brand-500));
  background: var(--badge-bg);
  color: var(--badge-fg, white);
  padding-inline: var(--badge-size, 0.5rem);
}

5. Dokumentation direkt im Stylesheet

Die effektivste Dokumentation eines Custom Properties-Vertrags lebt direkt neben dem Code, nicht in einem separaten Wiki, das schnell veraltet. Ein strukturierter Kommentarblock, wie im vorherigen Abschnitt gezeigt, ist für die meisten Teams ausreichend und hat den Vorteil, dass er bei jeder Code-Review automatisch mitgelesen wird. Größere Design Systeme ergänzen das durch generierte Dokumentation, etwa mit Tools wie Storybook, das Custom Properties einer Komponente automatisch aus Kommentaren extrahiert und in einer durchsuchbaren Oberfläche darstellt.

Wichtig ist, dass die Dokumentation den Unterschied zwischen "diese Property existiert" und "diese Property ist Teil des stabilen Vertrags" klar macht. Eine Property, die nur zufällig funktioniert, weil sie irgendwo im internen CSS verwendet wird, aber nie als öffentliche Schnittstelle gedacht war, sollte explizit als intern markiert werden, damit kein Konsument sich versehentlich auf ein Implementierungsdetail verlässt, das beim nächsten Refactoring ohne Vorwarnung verschwindet.

6. Typisierung mit @property als Vertragsverstärkung

Die native @property-Regel erlaubt es, einer Custom Property einen expliziten Syntaxtyp, einen Vererbungsmodus und einen initialen Wert zuzuweisen. Für den API-Vertrag bedeutet das eine zusätzliche, browserseitig durchgesetzte Garantie: Ein Konsument, der versucht, --badge-size mit einem ungültigen Wert zu überschreiben, etwa einem String statt einer Länge, sieht den initialen Wert statt eines stillschweigend falsch interpretierten Werts. Das macht den Vertrag robuster, weil Fehlerfälle sichtbar statt lautlos falsch werden.

Diese Typisierung ist besonders wertvoll bei Properties, die animiert werden sollen, weil @property dem Browser mitteilt, wie zwischen zwei Werten interpoliert werden soll, etwa als Zahl statt als reiner String. Ohne diese Deklaration überspringt eine CSS-Transition auf eine benutzerdefinierte Property den Zwischenzustand komplett, was für Konsumenten des API-Vertrags ein überraschendes, schwer zu debuggendes Verhalten erzeugt.

/* @property strengthens the contract with a browser-enforced type */
@property --badge-size {
  syntax: "<length>";
  inherits: false;
  initial-value: 0.5rem;
}

.c-badge {
  padding-inline: var(--badge-size);
  transition: padding-inline 200ms ease;
}

/* Invalid consumer override falls back to the initial value, not silent breakage */
.c-badge--broken {
  --badge-size: "not-a-length"; /* browser ignores, uses 0.5rem instead */
}

7. Breaking Changes vermeiden und kommunizieren

Ein Breaking Change bei einer öffentlichen Custom Property entsteht meist durch drei Muster: Umbenennung ohne Übergangszeit, Änderung des erwarteten Werttyps, oder Änderung der Semantik ohne Namensänderung, etwa wenn --card-spacing plötzlich Padding statt Margin steuert. Von diesen drei ist die stille Semantikänderung am gefährlichsten, weil sie weder von einem Linter noch von @property erkannt wird, der Konsument bekommt keinerlei Warnung, nur ein visuell falsches Ergebnis.

Die zuverlässigste Absicherung gegen versehentliche Breaking Changes im API-Vertrag ist ein Visual-Regression-Test, der die Komponente mit typischen Konsumenten-Overrides rendert und Screenshots über Versionen hinweg vergleicht. Ergänzend hilft ein Changelog, das jede Änderung an einer öffentlichen Custom Property explizit auflistet, analog zu einem API-Changelog einer REST-Schnittstelle, inklusive Migrationsanleitung für den Fall einer notwendigen Umbenennung.

8. Die API testen: Contract-Tests für CSS

Contract-Tests für Custom Properties unterscheiden sich von klassischen Unit-Tests, weil CSS keine Assertions im herkömmlichen Sinn kennt. Ein praktikabler Ansatz: ein automatisierter Test, der den berechneten Stil (getComputedStyle) einer Komponente mit und ohne gesetzte öffentliche Custom Property vergleicht und sicherstellt, dass eine Änderung der Property tatsächlich die erwartete visuelle Eigenschaft beeinflusst, nicht mehr und nicht weniger.

Für Design Systeme mit vielen Komponenten lohnt sich ein automatisiertes Snapshot der öffentlichen API selbst: eine Liste aller mit --komponente--Präfix beginnenden Properties je Komponente, versioniert im Repository. Ein CI-Check, der diese Liste bei jedem Pull Request gegen die aktuelle Snapshot-Datei vergleicht, macht jede Änderung am API-Vertrag sichtbar, bevor sie in den Main-Branch gelangt, unabhängig davon, ob die Änderung beabsichtigt war oder ein Versehen ist.

9. Öffentliche API vs. interne Implementierung im Vergleich

Die folgende Tabelle stellt gegenüber, wie sich der Umgang mit Custom Properties unterscheidet, je nachdem ob sie als öffentlicher Vertrag oder als reines internes Detail behandelt werden.

Der Unterschied zwischen beiden Spalten ist meist keine Frage der CSS-Syntax, sondern der organisatorischen Disziplin. Alle Werkzeuge für einen belastbaren API-Vertrag existieren bereits nativ in CSS, sie müssen nur konsequent angewendet werden.

10. Zusammenfassung

Custom Properties sind sobald sie von außerhalb einer Komponente gesetzt oder gelesen werden, keine Implementierungsdetails mehr, sondern Teil einer öffentlichen API, mit denselben Stabilitätsanforderungen wie jede andere Softwareschnittstelle. Ein klarer Namensraum trennt öffentliche von privaten Werten, dokumentierte Fallbacks machen Standardverhalten im Code selbst sichtbar, und @property verstärkt den Vertrag durch browserseitig durchgesetzte Typsicherheit.

Der größte Hebel liegt nicht in neuer CSS-Syntax, sondern in organisatorischer Disziplin: ein dokumentierter Deprecation-Prozess, ein Changelog für jede Änderung an einer öffentlichen Custom Property und automatisierte Contract-Tests, die eine Breaking-Change-Situation erkennen, bevor sie Konsumenten erreicht. Design Systeme, die diese Praxis konsequent anwenden, ermöglichen es Teams, unabhängig voneinander zu arbeiten, ohne dass eine interne Refactoring-Entscheidung fremden Code unbemerkt zerstört.

11. FAQ: Custom Properties als API Vertrag