Designsystem-Dokumentation – UI-Regeln, die Teams nutzen

Wenn Buttons mal abgerundet, mal eckig sind und Abstände je nach Seite „gefühlt“ gesetzt werden, liegt das selten an fehlendem Können. Meist fehlt ein Ort, an dem Regeln schnell gefunden, verstanden und angewendet werden können. Genau hier entscheidet die Designsystem-Dokumentation, ob ein System im Alltag funktioniert oder nur als Sammlung hübscher Komponenten existiert.

Eine gute Doku ist kein Roman. Sie ist ein Werkzeug: klar, durchsuchbar, konkret. Und sie beantwortet die Fragen, die im Projekt wirklich auftauchen – nicht die, die theoretisch interessant wären.

Welche Fragen die Dokumentation im Alltag beantworten muss

Die häufigsten „Wo finde ich…?“-Momente im Team

In UI-Projekten wiederholen sich bestimmte Suchanfragen. Eine gute Doku ist so strukturiert, dass diese Fragen in wenigen Sekunden beantwortet sind:

• Welchen Button nutze ich für diese Aktion – und mit welchem Text?
• Wie sehen die Zustände aus (normal, hover, disabled) und wann gelten sie?
• Welche Abstände sind Standard, welche sind Ausnahmen?
• Wie werden Icons, Bilder und Illustrationen eingesetzt, ohne das UI zu überladen?
• Was tun bei Sonderfällen, die nicht in die vorhandenen Komponenten passen?

Wichtig: Die Antworten sollten immer sowohl „was“ als auch „warum“ erklären – kurz und verständlich. „Warum“ verhindert Diskussionen, „was“ beschleunigt die Umsetzung.

Für wen wird dokumentiert? Rollen statt Jobtitel denken

Dokumentation scheitert oft, weil sie nur eine Zielgruppe bedient. Besser ist, nach Rollen zu strukturieren:

• Designer:innen brauchen Regeln, Varianten, Beispiele und Grenzen („Do/Don’t“ in Worten).
• Entwickler:innen brauchen eindeutige Spezifikationen, Benennungen und Hinweise zu States, Responsivität und Zugänglichkeit (Barrierefreiheit).
• PMs/Stakeholder brauchen Entscheidungshilfen („Wann nutzen wir das?“) und nachvollziehbare Prinzipien.

Ein Trick aus der Praxis: Jede zentrale Seite bekommt oben eine Mini-Navigation wie „Für Design“, „Für Dev“, „Für Content“. Das hält die Inhalte schlank, ohne Informationen zu verlieren.

Struktur, die funktioniert: Seiten-Typen statt endloser Wiki-Bäume

Startseite: Prinzipien, Status und „Wie arbeiten wir damit?“

Die Startseite ist kein Schaufenster, sondern ein Einstieg. Sie sollte drei Dinge leisten:

• Grundprinzipien (z. B. „klar, ruhig, robust“) in einfachen Sätzen
• System-Status: stabil / in Arbeit / experimentell (damit Teams Risiken einschätzen)
• Arbeitsweise: Wie wird das System verwendet und wie werden Änderungen vorgeschlagen?

Damit wird sofort klar: Das System ist ein Produkt, kein Ordner.

Komponentenseiten: klare Regeln, Beispiele, Grenzen

Jede Komponente (z. B. Button, Input, Card) braucht eine Seite nach einem einheitlichen Muster. Bewährt hat sich:

• Wofür: Einsatzbereich in 1–2 Sätzen
• Wann nicht: typische Fehlanwendungen („Nicht für Navigation“, „Nicht für destruktive Aktionen“)
• Varianten: welche gibt es wirklich (nicht jede Mini-Abwandlung)
• States (Zustände): z. B. focus/hover/disabled, mit kurzen Hinweisen
• Inhalt: Textlängen, Icon-Nutzung, Beispiele für gute Labels
• Layout: Abstände, Mindestbreiten, Verhalten bei Zeilenumbruch

Besonders wichtig ist der Fokus-State (Tastaturfokus): Wenn er fehlt oder uneinheitlich ist, leidet die Bedienbarkeit. Wer tiefer einsteigen will, kann ergänzend den Artikel zur Barrierefreiheit im Web verlinken und die Doku daran anlehnen.

Pattern-Seiten: wiederkehrende Lösungen über einzelne Komponenten hinaus

Nicht alles ist eine Komponente. Viele UI-Probleme sind Muster (Pattern): Kombinationen aus mehreren Bausteinen. Beispiele:

• Formularabschnitte mit Hilfe-Text und Fehlermeldungen
• Filterleisten mit Chips, Suchfeld und Sortierung
• Dialoge (Modal): Struktur, Titel, Buttons, Schließen-Verhalten

Hier entsteht besonders viel Reibung, weil Teams sonst jedes Mal neu entscheiden. Ein Pattern spart Diskussionen und sorgt für wiederholbare Qualität. Passend dazu hilft eine saubere Grundlage für Abstände, wie im Beitrag zu Designsystem-Abständen und Spacing.

So wird die Doku verständlich: Sprache, Beispiele, „Do/Don’t“ ohne Bilder

Regeln in normaler Sprache statt Tool-Sprech

Dokumentation muss auch ohne Figma-Kenntnis verständlich sein. Tool-Begriffe (z. B. „Variant Property“) helfen selten. Besser sind klare Regeln:

• Schlecht: „Primary/Secondary abhängig vom Kontext.“
• Gut: „Primärbutton nur für die wichtigste Aktion pro Bereich. Sekundärbutton für Alternativen.“

Fachwörter kurz erklären, wenn sie unvermeidbar sind: „State (Zustand)“, „Token (benannter Designwert wie Farbe/Abstand)“.

Beispiele, die direkt kopierbar sind

Teams arbeiten schneller, wenn die Doku Textbeispiele liefert. Zum Beispiel bei Button-Labels:

Wer Microcopy systematisch angehen will, kann ergänzend auf UI-Text und Microcopy verweisen, damit Tonalität und Muster zusammenpassen.

Benennung und Ordnung: damit niemand doppelt baut

Eine Namenslogik, die auch in Stress-Situationen hält

Viele Systeme scheitern an Namen wie „Button2“, „Card final“, „Input_new“. Das wirkt klein, hat aber große Folgen: Teams finden Komponenten nicht, bauen neu, und das System zerfasert.

Eine robuste Logik ist: Komponenten-Benennung nach „Baustein / Variante / Zweck“. Also zum Beispiel „Button / Primary / Destructive“ statt „Danger Button“. Wichtig ist nicht die perfekte Terminologie, sondern Konsistenz.

Suchbarkeit in Figma: Seiten, Sections und Komponenten-Index

Auch wenn die Doku in einem Wiki liegt: Viele suchen zuerst in Figma. Darum braucht es einen Index:

• Eine Übersichtsseite mit allen Komponenten (alphabetisch und nach Bereichen)
• Klare Sections wie „Actions“, „Inputs“, „Navigation“, „Feedback“
• Hinweis, wo „stabil“ liegt und wo „experimentell“ liegt

Zusätzlich hilft ein kurzer Hinweis, wie Auto Layout (automatische Anordnung und flexible Größen) genutzt wird, damit Komponenten sich verlässlich verhalten. Wer dazu eine Basis sucht: Figma Auto Layout meistern.

Ein kurzer Ablauf, der sich bewährt hat

Damit die Dokumentation nicht „später irgendwann“ passiert, hilft ein fester Ablauf, der in Sprints passt. Die folgenden Schritte sind bewusst schlank gehalten und lassen sich auch in kleinen Teams umsetzen.

• Seite anlegen: Komponente oder Pattern bekommt sofort eine Doku-Seite (auch wenn noch nicht alles fertig ist).
• Minimum eintragen: Zweck, wann nicht nutzen, Varianten, States, Beispiele.
• Review einplanen: Kurzprüfung im Design-Review, bevor etwas als „stabil“ markiert wird.
• Änderung dokumentieren: Was hat sich geändert, ab wann gilt es, was ist betroffen?
• Altlasten markieren: Veraltete Teile nicht löschen, sondern als „deprecated (wird ersetzt)“ kennzeichnen.

Pflege und Verantwortung: Governance ohne Bürokratie

Wer entscheidet was? Kleine Rollen, große Wirkung

Governance heißt: Änderungen laufen kontrolliert, damit das System nicht auseinanderläuft. Dafür reichen oft drei einfache Rollen:

• Owner: priorisiert und entscheidet bei Konflikten
• Maintainer: pflegt Library/Doku und achtet auf Konsistenz
• Contributors: melden Bedarf, liefern Beispiele, setzen um

Entscheidend ist ein leichtes Verfahren für Vorschläge: „Problem → Vorschlag → Auswirkungen → Entscheidung“. Damit werden Änderungen nachvollziehbar, ohne Meetings zu stapeln.

Wie mit Sonderfällen umgehen, ohne das System zu verwässern

Sonderfälle sind normal. Die Doku sollte erklären, wie damit umzugehen ist, damit aus jedem Sonderfall keine neue Variante entsteht. Eine einfache Entscheidungshilfe kann so aussehen:

• Passt der Fall in eine bestehende Komponente?
  • Ja: Komponente nutzen, nur Inhalt/Layout anpassen.
  • Nein: weiter prüfen.
• Ist es ein wiederkehrendes Muster?
  • Ja: neues Pattern definieren, mit klaren Regeln.
  • Nein: einmalige Lösung, aber dokumentieren, warum sie einmalig bleibt.
• Hat es Auswirkungen auf Barrierefreiheit, Text oder Technik?
  • Ja: früh mit Dev/Content abstimmen, bevor Varianten entstehen.

Typische Stolpersteine – und wie sie vermieden werden

Zu viele Regeln, zu wenig Orientierung

Wenn alles dokumentiert wird, finden Teams nichts. Besser ist: Regeln nur dort, wo Entscheidungen sonst wiederholt werden. Detailwissen kann in Unterpunkte, aber die Hauptaussage muss sofort sichtbar sein.

Komponenten ohne Kontext: „Was“ ohne „Wann“

Ein System wird nicht durch Varianten vollständig, sondern durch gute Grenzen. Darum braucht jede Seite mindestens einen Abschnitt „wann nicht“. Das verhindert, dass die gleiche Komponente für komplett unterschiedliche Zwecke missbraucht wird.

Kein Abgleich mit Entwicklung: Doku und Realität driften auseinander

Wenn Code und Doku unterschiedliche Wahrheiten erzählen, verliert die Doku schnell Vertrauen. Ein einfacher Fix: Bei jeder Änderung an zentralen Komponenten wird die Doku im gleichen Arbeitspaket aktualisiert. Außerdem helfen klare Übergaben: Design-Handoff für Entwickler ergänzt die Dokumentation um den Prozess.

Was in eine starke Dokumentation unbedingt hinein gehört

Zum Schluss eine kompakte Übersicht, die als Inhaltsskelett dienen kann. Damit ist schnell erkennbar, ob eine Seite „fertig genug“ ist, um genutzt zu werden.

Mit dieser Struktur lässt sich eine Dokumentation Stück für Stück erweitern, ohne jemals „fertig“ sein zu müssen. Entscheidend ist, dass die Inhalte auffindbar, eindeutig und im Teamalltag anschlussfähig sind – dann wird die Doku genutzt und das System bleibt stabil.