Vier Töne desselben Blaus, drei verschiedene Button-Höhen, ein Datumswähler, der in jedem Projekt neu geschrieben wird. So sieht die Oberfläche aus, wenn in einem Unternehmen mehrere Webanwendungen, Kundenportale und die Unternehmenswebsite von getrennten Teams entwickelt werden. Ein Designsystem stoppt diese Zersplitterung, indem es Designentscheidungen und Komponenten in ein versioniertes, dokumentiertes und gemeinsam genutztes Produkt überführt. Im Folgenden beschreiben wir den Aufbau eines codebasierten Systems vom Token bis zur Komponentenbibliothek, von der Versionierung bis zum Beitragsprozess, und in welchen Fällen man es nicht aufbauen sollte.
Umfang des Designsystems
„Designsystem“ bedeutet in jedem Team etwas anderes. Die Designerin denkt an die Figma-Bibliothek, der Frontend-Entwickler an das npm-Paket, die Produktmanagerin an den Styleguide. Wird der Umfang nicht von Anfang an schriftlich definiert, sind unterschiedliche Erwartungen und halbfertige Arbeit unvermeidlich. Typische Schichten:
| Ebene | Inhalt | Verantwortlich |
|---|---|---|
| Grundlagen | Tokens für Farbe, Typografie, Abstände, Eckenradius, Schatten, Bewegung | Design + Frontend |
| Komponenten | Button, Formularfeld, Modal, Tabelle, Benachrichtigung; Zustände und Varianten | Frontend-Team |
| Muster | Formularlayout, Liste-Detail-Bildschirm, leerer Zustand, Fehlerseite | Design + Produkt |
| Inhaltsregeln | Sprache von Fehlermeldungen, Button-Texte, Datums-/Währungsformat | Inhalt / Produkt |
| Governance | Versionierung, Beitragsprozess, Entscheidungsprotokolle, Supportkanal | Systemteam |
Beginnen Sie klein: Die erste Version mit den Grundlagen und den 8–10 meistgenutzten Komponenten herauszubringen, ist gesünder, als alle Schichten gleichzeitig fertigstellen zu wollen. Um die vorrangigen Komponenten zu finden, genügt ein Screenshot-Inventar der bestehenden Anwendungen, in dem wiederkehrende Elemente gruppiert werden. Das Inventar beendet die Diskussion.
Design Tokens und CSS-Variablen
Ein Token ist die plattformunabhängige, benannte Form einer Designentscheidung. Eine gesunde Struktur hat zwei Schichten: Basis-Tokens (Primitive) halten den Rohwert (color.blue.600), semantische Tokens (Semantic) drücken den Verwendungszweck aus und verweisen auf ein Basis-Token (color.action.primary). Komponenten verwenden nur semantische Tokens; ändert sich die Markenfarbe oder kommt ein dunkles Theme hinzu, wird der Komponentencode nicht angefasst. Der Fehler, den wir in der Praxis am häufigsten sehen, ist die direkte Bindung von Komponenten an Basis-Tokens wie blue-600. Am Tag, an dem das Theme kommt, ändern sich Hunderte Dateien.
{
"color": {
"blue": { "600": { "$type": "color", "$value": "#1d4ed8" } },
"gray": { "900": { "$type": "color", "$value": "#111827" } },
"action": {
"primary": { "$type": "color", "$value": "{color.blue.600}" }
},
"text": {
"default": { "$type": "color", "$value": "{color.gray.900}" }
}
},
"space": {
"2": { "$type": "dimension", "$value": "8px" },
"4": { "$type": "dimension", "$value": "16px" }
}
}
Dieses Format folgt der von der W3C Design Tokens Community Group vorgeschlagenen Struktur $type/$value. Token-Quelldateien liegen in Git und werden mit einem Build-Werkzeug für die Zielplattformen umgewandelt. Style Dictionary ist dafür ein verbreitetes Open-Source-Werkzeug; die Unterstützung für das direkte Lesen des Formats $type/$value kam mit der Hauptversion 4, ältere Versionen erwarten den Schlüssel value. Die folgende Konfiguration erzeugt in beiden Versionen die grundlegende CSS-Ausgabe:
// style-dictionary-Konfiguration (config.json)
{
"source": ["tokens/**/*.json"],
"platforms": {
"css": {
"transformGroup": "css",
"buildPath": "dist/css/",
"files": [{ "destination": "tokens.css", "format": "css/variables" }]
}
}
}
Die Ausgabe ist eine Datei mit CSS Custom Properties wie --color-action-primary unter :root. Für Theme-Unterstützung wird die semantische Schicht mit einem zweiten Wertesatz neu definiert:
:root {
--color-action-primary: #1d4ed8;
--color-text-default: #111827;
--color-surface: #ffffff;
}
[data-theme="dark"] {
--color-action-primary: #60a5fa;
--color-text-default: #f3f4f6;
--color-surface: #0f172a;
}
.btn-primary {
background: var(--color-action-primary);
padding: var(--space-2) var(--space-4);
}
Prüfen Sie den Kontrast auf Token-Ebene: Für jedes semantische Text-/Hintergrundpaar lassen sich die WCAG-Schwellen (bei normalem Text mindestens 4,5:1) beim Build per Skript prüfen. Ein Paar, das die Schwelle nicht erreicht, soll den Build brechen, statt auf dem Bildschirm entdeckt zu werden. Zu weiteren Barrierefreiheitsanforderungen auf Komponentenebene siehe den WCAG-2.2-Leitfaden für Entwickler.
Synchronisation zwischen Figma und Code
Arbeiten Designer in Figma mit Variablen (Variables), entscheiden Sie, wo die einzige Quelle der Wahrheit für Tokens liegt. Es gibt zwei verbreitete Modelle: Tokens liegen in Git und werden nach Figma übertragen, oder sie werden in Figma bearbeitet und kommen über ein Plugin oder die API als Pull Request nach Git. Welches Sie auch wählen, Änderungen müssen ein Code-Review durchlaufen, und niemand darf an zwei Stellen manuell aktualisieren. Sonst driften Designdatei und Live-Oberfläche innerhalb weniger Monate auseinander, und niemand weiß, welche stimmt.
Komponentenbibliothek und Dokumentation
Das Schicksal einer Komponentenbibliothek bestimmt das API-Design. Props sind über Versionen hinweg ein Vertrag; für den Sonderbedarf jedes Teams ein neues Boolean-Prop hinzuzufügen, erzeugt schnell eine unbeherrschbare Oberfläche. Ein Button mit siebzehn Props ist kein Button mehr. Grundsätze, die dieses Risiko senken:
- Definieren Sie Varianten statt mit freiem Text mit begrenzten Union-Typen:
variant: 'primary' | 'secondary' | 'danger'. - Bieten Sie das Überschreiben von Stilen (
style, beliebigeclassName) kontrolliert an; sonst zerfällt die Konsistenz erneut. - Verwenden Sie bei komplexen Komponenten statt einer riesigen Komponente eine zusammengesetzte (Compound-)Struktur:
<Dialog>,<Dialog.Title>,<Dialog.Actions>. - Lösen Sie Barrierefreiheit innerhalb der Komponente: Fokusverwaltung, ARIA-Attribute und Tastaturverhalten dürfen nicht dem nutzenden Team überlassen werden.
- Erwägen Sie, statt von Grund auf zu schreiben, Ihre eigene visuelle Schicht auf eine Bibliothek mit fertigem Verhalten und ohne Stil (Headless) zu setzen; korrektes Tastatur- und ARIA-Verhalten komplexer Komponenten zu schreiben, erfordert erheblichen Aufwand.
Für die Dokumentation ist Storybook die verbreitete Wahl: Varianten jeder Komponente werden als „Story“ geschrieben, die Prop-Tabelle wird automatisch aus TypeScript-Typen erzeugt und ist interaktiv ausprobierbar. Das Barrierefreiheits-Addon (@storybook/addon-a11y) führt in jeder Story einen axe-core-Scan aus. Visuelle Regressionstests (Vergleich von Story-Screenshots) fangen unerwünschte Stiländerungen vor der Veröffentlichung ab; welche Komponenten eine Token-Änderung betrifft, sehen Sie oft hier zuerst.
// Button.stories.tsx (Storybook, CSF 3)
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta: Meta<typeof Button> = {
component: Button,
args: { children: 'Speichern' },
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = { args: { variant: 'primary' } };
export const Danger: Story = { args: { variant: 'danger' } };
export const Disabled: Story = { args: { variant: 'primary', disabled: true } };
Für Konfigurations- und Addon-Details ist die offizielle Storybook-Dokumentation maßgeblich; zwischen Versionen können sich Paketnamen und Konfigurationsformat ändern.
Versionierung und Verteilung
Anwendungen, die das Designsystem nutzen, verwenden es als Abhängigkeit. Die Disziplin der semantischen Versionierung (SemVer) ist daher nicht verhandelbar:
| Änderung | Version | Beispiel |
|---|---|---|
| Fehlerkorrektur, visuelle Feinabstimmung | Patch (1.4.2 → 1.4.3) | Korrektur der Fokusring-Stärke |
| Abwärtskompatible neue Funktion | Minor (1.4.3 → 1.5.0) | Neuer size-Wert für den Button |
| Breaking Change | Major (1.5.0 → 2.0.0) | Umbenennung eines Props, Löschen eines Tokens |
Praktiken, die sich in der Praxis bewähren:
- Veröffentlichen Sie Tokens und Komponenten als getrennte Pakete (z. B.
@unternehmen/tokens,@unternehmen/react). React- und Next.js-Anwendungen nutzen das Komponentenpaket, ein Projekt ohne React oder ein WordPress-Theme nur das Token-CSS. - Veröffentlichen Sie Pakete in einer internen npm-Registry (GitHub Packages, GitLab Package Registry, Azure Artifacts oder Verdaccio).
- Erzeugen Sie das Änderungsprotokoll nicht manuell, sondern bei jedem Pull Request mit einem Werkzeug wie Changesets; der Versionstyp wird beim Beitrag festgelegt.
- Halten Sie vor einem Breaking Change die alte API mindestens eine Nebenversion lang mit „deprecated“-Warnung am Leben und stellen Sie wenn möglich ein automatisches Transformationsskript (Codemod) bereit.
- Führen Sie die Release-Pipeline in der CI aus: Ohne bestandene Typprüfung, Unit-Tests, Barrierefreiheitsscan und visuelle Regression wird kein Paket veröffentlicht. Zum Aufbau der Pipeline siehe den Leitfaden CI/CD-Pipeline mit GitHub Actions.
Beitrags- und Entscheidungsprozess
Designsysteme scheitern meist nicht aus technischen, sondern aus organisatorischen Gründen: Ein Team findet die benötigte Komponente nicht im System, der Beitragsprozess dauert Wochen, und jeder schreibt seine eigene Kopie. Nach sechs Monaten existiert das System nur auf dem Papier. Um das zu verhindern, muss der Prozess schriftlich und leichtgewichtig sein:
- Anfrage: Bedarf an einer neuen Komponente oder Variante wird mit einer Vorlage eröffnet: Nutzungsszenario, Screenshot, wie viele Produkte sie brauchen.
- Bewertung: Das Systemteam prüft, ob der Bedarf mit einer vorhandenen Komponente gedeckt werden kann. Ein produktspezifischer Bedarf bleibt im Produkt; wiederholt er sich in zwei oder mehr Produkten, wird er ins System aufgenommen.
- Design- und API-Vorschlag: Bevor Code geschrieben wird, werden Props, Zustände und Barrierefreiheitsverhalten in einem kurzen Dokument festgelegt.
- Umsetzung: Den Beitrag kann auch das anfragende Team leisten; das Systemteam prüft und bestätigt die Konformität mit den Standards.
- Protokoll: Wichtige Entscheidungen (z. B. „warum der Kalender des Datumswählers die Woche am Montag beginnt“) werden als Entscheidungsprotokoll gespeichert; dieselbe Diskussion wird kein zweites Mal eröffnet.
Um die Akzeptanz zu messen, genügt ein einfaches Skript, das in den nutzenden Repositories die Verwendung von Systemkomponenten und lokalen Kopien scannt. Wie sich lokale Kopien mit Modulgrenzen und Lint-Regeln auf Codeebene verhindern lassen, beschreibt der Leitfaden Standards für TypeScript-Codebasen.
Fälle, in denen kein Designsystem nötig ist
Ein Designsystem ist eine dauerhafte Wartungslast: Es verlangt regelmäßig Zeit von mindestens einer Person, aktuelle Dokumentation und laufende Kommunikation mit den nutzenden Teams. In folgenden Fällen genügt statt eines vollständigen Systems ein leichtgewichtiger Ansatz:
- Ein Produkt, ein Team: Gemeinsame Komponenten liegen in einem Ordner innerhalb der Anwendung; separates Paket und Versionierung bringen unnötigen Aufwand.
- Das Produkt nimmt noch Form an: Ändert sich die Oberfläche in jedem Sprint, zementiert frühe Abstraktion falsche APIs.
- Eine fertige Bibliothek deckt den Bedarf: Für viele interne Anwendungen genügt es, auf einer ausgereiften Komponentenbibliothek nur mit Tokens ein Theme zu definieren.
- Keine Verantwortung: Ist nicht klar, wer die Wartung übernimmt, veraltet das System innerhalb weniger Monate, und Teams beginnen, es zu meiden. Ein System ohne Eigentümer verrottet.
Selbst in diesen Fällen ist der Aufbau der Token-Schicht ein kostengünstiger erster Schritt mit hohem Nutzen: Farb- und Typografieentscheidungen in einer Datei zu bündeln, erleichtert später den Übergang zu einem vollständigen System. Auf WordPress-basierten Websites wird ähnliche Konsistenz mit den globalen Stilen von Elementor erreicht; dieser Ansatz wird im Leitfaden Skalierbare Websitestruktur mit Elementor beschrieben, und das Token-CSS kann der gemeinsame Nenner zwischen beiden Umgebungen sein.
Planen Sie eine gemeinsame Oberflächensprache für mehrere Anwendungen und Websites, behandeln wir die Arbeit UI/UX und Unternehmens-Designsystem zusammen mit Umfang und Verantwortungsmodell.
Häufig gestellte Fragen
Sind Designsystem und Komponentenbibliothek dasselbe?
Nein. Die Komponentenbibliothek ist ein Teil des Designsystems. Das Designsystem umfasst zusätzlich Tokens, Nutzungsmuster, Inhaltsregeln, Dokumentation sowie die Governance mit Versionierung und Beitragsprozess.
Warum werden Tokens in Basis- und semantische Tokens unterteilt?
Basis-Tokens halten den Rohwert, semantische Tokens den Verwendungszweck. Nutzen Komponenten nur semantische Tokens, lassen sich eine Änderung der Markenfarbe oder ein dunkles Theme umsetzen, ohne den Komponentencode anzufassen, indem nur die semantische Schicht neu zugeordnet wird.
In welcher Phase sollte ein Designsystem aufgebaut werden?
Sinnvoll ist der Aufbau, sobald sichtbar wird, dass dieselben Oberflächenelemente von zwei oder mehr Produkten oder Teams neu geschrieben werden. In Projekten mit einem Produkt und einer sich noch schnell ändernden Oberfläche genügt es, mit der Token-Schicht zu beginnen.
Wie werden Breaking Changes im Designsystem verwaltet?
Es wird semantische Versionierung verwendet; ein Breaking Change erhöht die Hauptversionsnummer. Die alte API bleibt mindestens eine Nebenversion lang mit Veraltungswarnung erhalten, im Änderungsprotokoll werden Migrationsschritte beschrieben, und wenn möglich wird ein automatisches Transformationsskript bereitgestellt.