Ein Designsystem existiert erst, wenn es aufgeschrieben ist. Davor ist es eine Sammlung von Dateien in Figma und lose Absprachen im Code. Teams wechseln, Projekte wachsen, Erinnerungen verblassen. Die Dokumentation haelt fest, was gilt.

Gute Dokumentation spart Gespraeche ueber Details, die laengst entschieden sind. Sie gibt Entwicklern Sicherheit bei der Implementierung. Sie gibt Designern einen Rahmen fuer neue Entwuerfe. Dieser Text beschreibt, wie Teams ihre Komponenten, Tokens und Entscheidungen nuetzlich festhalten.

Zielgruppen einer Designdokumentation

Eine Dokumentation scheitert oft daran, dass sie nur fuer eine Disziplin geschrieben ist. Designer brauchen andere Angaben als Entwickler. Produktmanager suchen nach Logik, waehrend Barrierefreiheits-Beauftragte nach semantischen Rollen suchen. Jedes Teammitglied betrachtet dieselbe Komponente aus einem anderen Blickwinkel.

Entwickler benoetigen exakte Parameternamen, zulaessige Typen und Importpfade. Sie muessen wissen, wie die Komponente auf Tastatureingaben reagiert. Visuelle Designer achten auf Abstaende, Farbwerte und Typografiehierarchien. Schreibende suchen nach Laengenbeschraenkungen fuer Texte und Richtlinien fuer die Tonalitaet.

Trennen Sie die Bereiche klar voneinander ab. Mischen Sie nicht den CSS-Quellcode mit Hinweisen zur Grammatik. Gliedern Sie jede Komponentenseite in feste Reiter oder Abschnitte. So findet jede Person ihre Antwort in wenigen Sekunden.

Aufbau von Komponentenbeschreibungen

Jede Komponente folgt demselben Schema. Diese Gleichfoermigkeit reduziert die kognitive Last beim Lesen. Das Team weiss sofort, an welcher Stelle die gesuchte Information steht. Die Beschreibung beginnt immer mit dem Namen und einer Definition in einem einzigen Satz.

Uebersicht und Einsatzzweck

Beschreiben Sie die Primaerfunktion der Komponente. Erwaehnen Sie kurz, welches Problem dieses Element loest. Nennen Sie auch Alternativen, falls die Komponente fuer einen bestimmten Fall ungeeignet ist. Ein Satz reicht: Nutzen Sie die Primaerschaltflaeche fuer die wichtigste Aktion auf der Seite.

Visuelle und funktionale Zustaende

Dokumentieren Sie jeden Zustand einzeln und vollstaendig. Eine Schaltflaeche besitzt nicht nur einen Standardzustand. Zeigen Sie konkrete Werte fuer Hintergrundfarbe, Rahmen und Textfarbe.

• Default: Der unberuehrte Zustand bei geladener Seite.
• Hover: Der Mauszeiger liegt ueber dem Element, Farbton dunkelt um 8 Prozent ab.
• Active oder Pressed: Das Element wird geklickt oder beruehrt.
• Focus-Visible: Die Tastaturbedienung erreicht das Element, ein Rahmen von 2 Pixeln mit 2 Pixeln Versatz erscheint.
• Disabled: Keine Interaktion moeglich, Kontrastwert sinkt, ARIA-Attribut aria-disabled ist gesetzt.
• Loading: Ein Ladeindikator ersetzt das Label, Klicks loesen keine Aktionen aus.

Eigenschaften und Schnittstellen

Listen Sie alle Props oder Parameter in einer uebersichtlichen Tabelle auf. Definieren Sie den Datentyp, den Standardwert und ob die Eigenschaft verpflichtend ist. Ergaenzen Sie kurze Saetze zur Wirkung des Parameters im Code.

Barrierefreiheit und Tastatursteuerung

Dokumentieren Sie die exakten Tasten fuer jede Interaktion. Notieren Sie die semantische HTML-Basis. Verwenden Sie ein echtes button-Element anstelle eines div-Elements mit Klick-Handler. Halten Sie fest, welche Screenreader-Ausgabe bei Zustandsaenderungen erwartet wird.

Negativbeispiele zur Verhuetung typischer Fehler

Regeln bleiben oft abstrakt, wenn der falsche Weg nicht sichtbar ist. Gute Dokumentationen nutzen Bildpaare aus korrekten und fehlerhaften Varianten. Wir nennen diese Gegenueberstellung Do and Don't. Diese Beispiele verhindern Missverstaendnisse schneller als lange Erklaerungen.

Zeigen Sie reale Situationen aus der taeglichen Praxis. Verzichten Sie auf uebertriebene Kunstfehler, die niemand begehen wuerde. Zeigen Sie die Nuancen, an denen Entwickler und Designer tatsaechlich scheitern.

Beispiele fuer Schaltflaechen

Richtig: Pro Ansicht existiert nur eine Primaerschaltflaeche. Alle weiteren Aktionen nutzen die Sekundaervariante. Der Primaer-Button nutzt eine Hoehe von 40 Pixeln und ein klares Verb als Text.

Falsch: Drei Primaerschaltflaechen stehen nebeneinander in einer Maske. Der Nutzer erkennt die wichtigste Aktion nicht mehr. Das Auge springt unruhig zwischen gleichwertigen farbigen Bloecken hin und her.

Beispiele fuer Formularfelder

Richtig: Das Label steht dauerhaft sichtbar ueber dem Eingabefeld. Der Abstand zwischen Label und Feld betraegt 8 Pixel. Ein Hilfetext darunter nennt das genaue Eingabeformat.

Falsch: Der Text liegt ausschliesslich als Platzhalter im Feld. Sobald der Nutzer tippt, verschwindet der Hinweis. Der Nutzer vergisst, welche Information in das Feld gehoert.

Beispiele fuer Benachrichtigungen

Richtig: Eine Warnmeldung bleibt sichtbar, bis der Nutzer sie schliesst oder den Fehler behebt. Der Text beschreibt die Ursache und nennt den naechsten Korrekturschritt.

Falsch: Eine Fehlermeldung blendet sich nach 4 Sekunden automatisch aus. Nutzer mit geringerer Lesegeschwindigkeit verpassen die Information. Eine Behebung des Fehlers wird dadurch unmoeglich.

Einbindung in den taeglichen Entwicklungsprozess

Eine Dokumentation in einem isolierten Wiki veraltet innerhalb weniger Monate. Dokumentation muss dort liegen, wo die Arbeit stattfindet. Sie gehoert in dieselbe Versionsverwaltung wie der Produktionscode. Erst die technische Naehe fuehrt zu regelmaessigen Aktualisierungen.

Nutzen Sie Werkzeuge wie Storybook, Docusaurus oder Astro. Legen Sie Komponentenbeschreibungen als MDX-Dateien direkt neben der Komponentendatei ab. Aendert ein Entwickler das Verhalten der Komponente, aendert er im selben Commit die Dokumentation. Pull-Requests ohne Dokumentationsanpassung erhalten keine Freigabe.

Integrieren Sie Pruefungen in die Continuous-Integration-Pipeline:

1. Das System baut bei jedem Git-Push eine Vorschau der Dokumentation auf einem temporaeren Server.
2. Ein automatisierter Test prueft alle Code-Beispiele in der Dokumentation auf Syntaxfehler.
3. Ein Barrierefreiheits-Linter scannt die gerenderten Komponentenbeispiele nach WCAG-Kriterien.
4. Design-Tokens werden als JSON gespeichert und automatisch in SCSS, JavaScript und Figma exportiert.

Koppeln Sie Figma und Code ueber Tokens. Wenn das Design-Team den Token color-neutral-800 von einem Hex-Wert zu einem anderen aendert, laeuft diese Aenderung ueber eine Schnittstelle in das Repository. Der Dokumentationsserver rendert am selben Tag die aktualisierte Farbpalette.

Routinen fuer die kontinuierliche Pflege

Dokumentation schreibt sich nicht von selbst fertig. Sie ist ein fortlaufender Prozess. Teams benoetigen feste Arbeitsablaeufe, um Altlasten zu entfernen und neue Komponenten einzupflegen. Ohne explizite Zustaendigkeiten verwaist die Dokumentationsplattform.

Benennen Sie feste Systemverantwortliche im Wechsel. Ein Designer und ein Entwickler bilden fuer vier Wochen das Pflegetandem. Sie beantworten Fragen in internen Kanaelen, fuehren Komponenten-Reviews durch und pruefen die Aktualitaet der Markdown-Seiten. Nach diesem Zyklus wechseln die Personen.

Fuehren Sie ein zweiwoechentliches Design-System-Review von 45 Minuten Laenge ein. In diesem Treffen bespricht das Team ausschliesslich Aenderungsantraege:

• Wurde eine Komponente in einem Projekt abgewandelt und rechtfertigt dies eine neue Prop?
• Gibt es Rueckmeldungen ueber unklare Texte in den Richtlinien?
• Welche veralteten Varianten erhalten eine Deprecation-Warnung?

Markieren Sie Komponenten klar, wenn diese ausgemustert werden. Verwenden Sie den Hinweis "Deprecated" im Titel der Seite. Nennen Sie den Nachfolger und das genaue Datum, an dem die alte Komponente aus der Codebasis entfernt wird. Das gibt Produktteams 12 bis 16 Wochen Zeit fuer die Umstellung.

Typische Fehler bei der Dokumentation

Viele Teams wiederholen dieselben Versaeumnisse. Das Erkennen dieser Muster spart Monate an vergeblicher Arbeit.

Der haeufigste Fehler ist der Vollstaendigkeitswahn. Teams versuchen, jede moegliche Variante vorab zu planen und zu dokumentieren. Schreiben Sie Dokumentation erst dann, wenn eine Komponente in mindestens zwei realen Ansichten im Einsatz ist. Dokumentieren Sie nur, was tatsaechlich gebaut und getestet wurde.

Ein weiterer Fehler sind statische Screenshots anstelle interaktiver Sandboxen. Ein Screenshot zeigt nicht, wie sich Text bei 200 Prozent Zoom verhaelt. Ein Screenshot zeigt keinen Screenreader-Fokus. Nutzen Sie interaktive Vorschauen, in denen Leser die Texte live editieren und die Fenstergroesse veraendern koennen.

Drittens fehlen oft Versionsangaben. Wenn ein Teammitglied Dokumentation liest, muss ersichtlich sein, fuer welche Paketversion der Text gilt. Eine Komponente in Version 3.2.0 unterscheidet sich womoeglich von der Version 4.0.0. Ohne sichtbare Versionsnummer entstehen schwer auffindbare Fehler in der Anwendung.

Schliesslich vernachlaessigen viele Teams die Suchfunktion. Wenn Nutzer fuenf Klicks durch eine verschachtelte Navigation brauchen, geben sie auf. Eine schnelle, fehlertolerante Volltextsuche ist die wichtigste Funktion der gesamten Plattform.

Naechste Schritte fuer die Umsetzung

Beginnen Sie nicht mit dem gesamten System. Waehlen Sie eine einzige, hochfrequentierte Komponente als Pilotprojekt. Meistens eignet sich die Schaltflaeche oder das Text-Eingabefeld dafuer am besten.

Gehen Sie die Implementierung in klaren Schritten an:

1. Definieren Sie eine einheitliche Dateistruktur fuer MDX-Seiten direkt im Komponenten-Ordner Ihres Projekts.
2. Erstellen Sie die vier festen Abschnitte: Uebersicht, Zustaende, Schnittstellen und Barrierefreiheit fuer die Pilotkomponente.
3. Fuegen Sie jeweils ein konkretes Do- und ein Don't-Beispiel mit Code-Snippet hinzu.
4. Legen Sie eine Checkliste fuer Pull-Requests an, die das Aktualisieren der Dokumentation verpflichtend macht.
5. Veroeffentlichen Sie den Link zur Dokumentation im primaeren Kommunikationskanal Ihres Entwicklungsteams.

Lassen Sie zwei Personen, die nicht an der Erstellung beteiligt waren, eine Testseite mit dieser Pilotkomponente bauen. Beobachten Sie, an welchen Stellen Fragen auftauchen. Ergaenzen Sie die fehlenden Antworten sofort im Text. Wiederholen Sie dieses Verfahren fuer jede weitere Komponente.