Designsysteme 103: Akzeptanz fördern durch Dokumentation

Als das Razorpay-Team immer wieder kleine Details übersah, erkannte Head of Design Saurabh Soni schnell: Das war kein Qualitätsproblem – sondern ein Kommunikationsproblem. „Vor der Einführung von Blade [unserem Designsystem] war es für Teams nicht unüblich, Kleinigkeiten wie den Status von Buttons oder den Umgang mit Fehlern in Eingabefeldern zu übersehen“, erklärt er

. „Oft konzentrierten sich die Teams darauf, Daten direkt einzubetten und jeweils individuelle Lösungen zu entwickeln, und dabei konnte es passieren, dass sie aus Versehen etwas ausließen.“

Diese Herausforderung kennen viele Unternehmen. „Designer*innen und Entwickler*innen sprechen eine etwas andere Sprache“, erklärt Lukas Oppermann

, Staff System Designer bei GitHub. Diese Sprachlücke führt zu uneinheitlichen Namenskonventionen, nicht abgestimmten Komponenten und falschen Erwartungen an das Look & Feel eines Produkts. Eine gute Dokumentation schließt diese Lücke und stellt die Verbindung zwischen Absicht und Umsetzung her. Aber sie sollte mehr sein als nur eine Sammlung von Komponenten. Sie muss das Wie und Warum hinter Designentscheidungen erfassen. Ohne diese Guidance verstauben selbst die durchdachtesten Systeme in digitalen Archiven.

Wenn Dokumentation gut gemacht ist, hilft sie Teams dabei:

• Designprinzipien und technische Umsetzung zu verstehen
• Konsistente Entscheidungen über Produkte und Plattformen hinweg zu treffen
• Neue Teammitglieder effizient einzuarbeiten
• Die Kommunikation zwischen Designer*innen und Entwickler*innen zu verbessern

Wie findest du deine „Source of Truth“?

Die erste Frage ist nicht, was du dokumentierst – sondern wo. „Eine der größten Herausforderungen für Konsistenz ist die Frage nach der Informationsquelle“, erklärt Raul Menezes

, Design System and Platform Engineer bei Bumble. Mit wachsenden Teams und reiferen Designsystemen wird das Problem nur größer. Die Zeiten, in denen statische PDFs auf geteilten Laufwerken sofort veraltet waren, sind vorbei. Heute gibt es mehr Möglichkeiten denn je – von dedizierten Doku-Websites bis hin zu kollaborativen Workspaces.

Von Grund auf neu erstellen

Benutzerdefinierte Dokumentationsseiten eignen sich hervorragend für große Unternehmen, deren Designsysteme umfassend in deren Tools und Prozesse integriert werden müssen. Material Design von Google, Carbon von IBM und Evo von eBay setzen auf maßgeschneiderte Dokumentationsseiten für interne und externe Nutzer*innen – mit Zugriffssteuerung und speziellen Workflows für unterschiedliche Teams.

„Jede*r will einfach die bestmögliche Arbeit machen“, betont Ryan Tinsley, Staff Product Designer bei eBay. „Unsere Teams haben ihr Level enorm gesteigert, seit sie sich auf unsere Dokumentation beziehen. Die Office Hours, die wir jetzt haben, sind mit der Zeit vor unserem Playbook nicht zu vergleichen – alle wissen genau, wo sie nachschauen müssen und wie sie die Marke konsistent umsetzen.“

Anstatt separate Ziele für Marken- und Produktdokumentation zu schaffen, hat eBay ein einheitliches Playbook erstellt. „Wir wollten eine zentrale Anlaufstelle schaffen, damit Teams nicht ständig zwischen verschiedenen Plattformen wechseln müssen“, so Ryan Damit das funktioniert, hat das eBay-Team ein eigenes Tool entwickelt, das Änderungen direkt aus Figma ins CMS exportiert. So erhalten Designer*innen und andere Teams immer die aktuellsten Playbook-Updates, sobald sie freigegeben sind.

Nutzung bestehender Plattformen

Nicht jedes Team benötigt dieses Maß an Komplexität. Kleinere Teams beginnen oft mit Kollaborationswerkzeugen wie Notion oder Confluence, wobei sie eine schnelle Einrichtung und einfache Wartung priorisieren. Viele Teams kombinieren Ansätze: technische Spezifikationen in Storybook und Design-Richtlinien in zugänglicheren Formaten, ergänzt durch benutzerdefinierte Plugins. Bei Razorpay stellte das Team fest, dass ihre Dokumentation mehr leisten musste, als nur Bestehendes zu erklären – sie musste die unterschiedlichen Teams dort abholen, wo sie sich befinden. Deshalb haben sie ein eigenes Plugin entwickelt: RazorSharp

, eine Brücke zwischen Design-Dokumentation und Umsetzung Der Schlüssel liegt in der Auswahl von Tools, die deine aktuellen Anforderungen erfüllen und gleichzeitig Raum für Wachstum bieten.

Inhalt der Dokumentation

Abgesehen davon, wo die Dokumentation abgelegt werden sollte, musst du eine weitere wichtige Entscheidung treffen: Was gehört hinein? Hier sind die wichtigsten Elemente:

Designprinzipien

Jedes Designsystem braucht klar definierte Prinzipien – sie geben Orientierung für strategische Entscheidungen ebenso wie für kleinste Design-Details. Wenn du das „Warum“ hinter Entscheidungen dokumentierst, verstehen die Teams die Gründe besser und wissen, wie sie sie konsequent umsetzen können.

Komponentenbibliothek

Für jede Komponente solltest du folgende Inhalte dokumentieren:

• Nutzungsrichtlinien und Best Practices
• Design-Spezifikationen für Anatomie, Abmessungen und Verhalten
• Praxisbeispiele und Anwendungsfälle
• Codeschnipsel und Implementierungsdetails
• Interaktive Prototypen zur Darstellung von Zuständen und Varianten

Visueller Styleguide

Dokumentiere die wichtigsten Designentscheidungen für das visuelle Erscheinungsbild deiner Marke:

• Farbpalette mit Nutzungsrichtlinien
• Typografiesystem mit Festlegung der Hierarchie und Best Practices
• Symbol-Bibliotheken mit Designspezifikationen
• Bild- und Illustrationsstandards, einschließlich Richtlinien zur Barrierefreiheit

Technische Umsetzung

Unterstütze Entwickler*innen bei der Implementierung deines Systems:

• Dokumentation der Komponenten-APIs und -Props
• Anforderungen an die Barrierefreiheit und Testverfahren
• Performance-Überlegungen
• Integrationsleitfäden für unterschiedliche Frameworks
• Konsistente Namenskonventionen und Token-Dokumentation

Richtlinien zur Barrierefreiheit

Formuliere die Anforderungen an die Barrierefreiheit deutlich:

• WCAG-Konformitätsstufen für Komponenten
• Screenreader-Verhalten
• Tastaturnavigation und Interaktionsmuster
• Anforderungen an den Farbkontrast
• Touch-Target-Größen

Bei eBay stellte das Designsystem-Team fest: Je detaillierter die Dokumentation, desto besser. Die Mitarbeitenden verlangen nach Dokumentation“, betont Ryan. „Selbst bei einem so umfassenden System wie unserem hören wir ständig Fragen wie ‚Was ist mit diesem Randfall?‘ oder ‚Wurde die Dokumentation dieses Szenarios berücksichtigt?‘ Mithilfe dieses kontinuierlichen Feedbacks können wir unsere Ressourcen perfektionieren und erweitern – Teams konsumieren die Dokumentation nicht nur passiv, sondern unterstützen uns aktiv bei der Gestaltung.“

Pflege und Weiterentwicklung der Dokumentation

Eine der größten Herausforderungen ist, Dokumentation aktuell zu halten, während dein Team wächst. Veraltete Dokumentation führt zu uneinheitlichen Designs – und das untergräbt die Glaubwürdigkeit deines Designsystems. Die Aktualisierung der Dokumentation ist zwar mühsam, aber der Nutzen ist enorm: schnelleres Onboarding, weniger Abweichungen und eine einheitlichere Erfahrung.

Dokumentation up-to-date halten

„Was man im Design sieht, ist auch im Code enthalten“, betont Kamlesh von Razorpay. Diese Ausrichtung ergibt sich aus der bewussten Entscheidung, wie die Dokumentation strukturiert, gepflegt und weiterentwickelt wird. „Wir haben ca. 70 Designer*innen und 100 Frontend-Entwickler*innen“, sagt Saurabh. „Innerhalb dieser Teams widmen sich drei Designer*innen und fünf Entwickler*innen unserem Designsystem.“ Dieses Kernteam pflegt die Community durch regelmäßige Office Hours, Fokusgruppen und ein Advocacy-Programm, an dem Designer*innen aus verschiedenen Teams beteiligt sind.

Während dein Designsystem wächst, brauchst du klare Prozesse, um Änderungen und Beiträge zu verwalten. Dabei geht es um die richtige Balance zwischen zentraler Steuerung und Community-Input – so bleibt das System flexibel, ohne an Konsistenz zu verlieren. Hier einige bewährte Tools und Methoden:

• Beitragsrichtlinien: Lege fest, wie Teammitglieder Änderungen vorschlagen oder neue Komponenten hinzufügen können – mit Vorlagen, Styleguides und definierten Review-Prozessen.
• Versionskontrolle: Nutze semantische Versionierung, um den Umfang und die Auswirkungen jeder Änderung zu kommunizieren. Auf diese Weise kann dein Team besser verstehen, wie sich die einzelnen Versionen unterscheiden und was bei einer Aktualisierung zu erwarten ist.
• Änderungsprotokolle: Führe eine detaillierte Liste mit allen Änderungen in jeder neuen Version – inklusive neuer Features, Bugfixes und Breaking Changes.
• Qualitätssicherung: Implementiere mehrere Kontrollpunkte zur Überprüfung der Qualität, z. B. regelmäßiges Feedback und Linting-Systeme.

Die Teams für Designsysteme und Designtechnologie von eBay führen eine Tabelle mit dem Status der Komponenten, die den Implementierungsstatus für verschiedene Plattformen anzeigt. Cordelia McGee-Tubb, Staff Design Technologist bei eBay, erklärt: „Viele unserer Entwickler*innen haben diese Komponentenstatus-API verwendet, um herauszufinden: Gibt es die Komponente in dem von mir verwendeten Framework? Ist sie up to date im Vergleich zur Figma-Version? Und stimmt sie mit der Playbook-Dokumentation überein? Das war ein großer Erfolg.“ Außerdem wurde ein benutzerdefinierter Linter zur Validierung der Dokumentation entwickelt, der die Verwendung von Komponenten anhand von Richtlinien prüft, die Barrierefreiheit verifiziert, Alt-Texte von Bildern checkt und Unstimmigkeiten bei der Benennung oder Struktur aufzeigt.

Eine Lösung, die für alle passt

Unterschiedliche Teammitglieder haben unterschiedliche Anforderungen an die Dokumentation – Erfolg bedeutet, diese Bedürfnisse zu verstehen und zu berücksichtigen. Bei Alaska Airlines

hatten die Designer*innen Schwierigkeiten mit der pixelgenauen Umsetzung, während die Entwickler*innen oft nicht übereinstimmende Designs erhielten. Product Designer June Lee konzentrierte sich darauf, zentrale Features ihres Auro-Designsystems in Figma zu dokumentieren. „Mir war besonders wichtig, unser Designteam besser mit Figma vertraut zu machen“, erklärt sie. „Ich konnte beobachten, dass Designer*innen Figma effektiver nutzten – und das bedeutete weniger Konflikte mit Entwickler*innen." Ein Überblick, welche Inhalte für verschiedene Rollen besonders relevant sind:

Für Designer*innen

• Visuelle Beispiele und Nutzungsmuster
• Varianten und Zustände von Komponenten
• Implementierung von Design-Tokens
• Grid-Systeme und Abstände
• Objektbibliotheken und Ressourcen

Für Entwickler*innen

• Technische Spezifikationen
• API-Dokumentation
• Integrations-Guides
• Testanforderungen
• Performance-Überlegungen

Für Produktmanager*innen

• Überblick über das System
• Guidelines zur Komponentenwahl
• Funktions-Roadmap
• Release Notes und Updates

Feedback sammeln und Auswirkungen messen

Bei Razorpay wird der Erfolg nicht allein an der Zahl der Nutzer*innen gemessen, sondern an den spürbaren Auswirkungen auf Workflows und Zusammenarbeit. Das Team setzt konkrete Ziele:: Teams, die neue Funktionen entwickeln, sollten ihr System für 70 % ihrer Designarbeit verwenden, während bei bestehenden Produkten eine Abdeckung von 50 % angestrebt wird. „Bei einer Befragung haben 80 % unserer Designer*innen und Entwickler*innen angegeben, dass sie mit Blade produktiver arbeiten als ohne das Designsystem“, so Saurav Rastogi, Staff Designer.

Wenn du Feedback und Proofpoints (Belege) für dein System sammelst, reicht es nicht aus, nur Seitenaufrufe zu analysieren. Wichtiger ist es zu verstehen, wie die Dokumentation das Verhalten deines Teams beeinflusst. Erwäge Nutzertests und Nutzerinterviews, um umfassendes Feedback zu sammeln. Indem du kontinuierliche Verbesserung und Iteration priorisierst, stellst du sicher, dass dein Designsystem ein wertvolles und effektives Werkzeug bleibt – auch wenn sich deine Produkte und Prozesse weiterentwickeln.

Skalierung von Dokumentation

Die beste Dokumentation beschreibt nicht nur, was existiert, sondern hilft Teams, bessere Erlebnisse zu gestalten. Investitionen in Tools und Prozesse, die Dokumentation aktuell halten, zahlen sich langfristig aus: in höherer Akzeptanz und Konsistenz. Hier ein paar zentrale Überlegungen für den Aufbau und die Weiterentwicklung deines eigenen Systems zur Dokumentation:

• Hol Teams dort ab, wo sie arbeiten, mit integrierten Tools und maßgeschneiderten Lösungen.
• Baue Brücken zwischen den Disziplinen, indem du wie Lukas Oppermann von GitHub eine „dritte Sprache“ etablierst, in der Designer*innen und Entwickler*innen tatsächlich kommunizieren können.
• Ermögliche klare Beteiligungswege durch spezielle Teams und regelmäßige Einbindung der Community.
• Miss die Auswirkungen, indem du verfolgst, wie sich Produktivität und Zusammenarbeit im Team verbessern.

Die Zukunft gehört integrierten Ansätzen, bei denen Dokumentation direkt im Arbeitsprozess lebt. Wenn sich die Dokumentation mit dem System weiterentwickelt, folgt die Nutzung ganz automatisch. Das Ziel ist nicht eine perfekte Dokumentation, sondern eine Dokumentation, durch die Teams ihr Bestes geben können

Was möchtest du noch wissen? Sende uns deine Fragen auf Twitter an @figma. Erfahre mehr darüber, wie Figma Teams mithilfe von Designsystem-Funktionen bei der Verbesserung der Konsistenz, der Skalierung von Designs und der Aufrechterhaltung der Parität bei der Entwicklung unterstützt. Oder fordere eine Demo an.