Dokumentation ist das neue Interface — und Design Systems sind das Testfeld

Wesentliche Insights

1 — Design-System-Teams designen jetzt zwei Interfaces gleichzeitig

Figmas neue “Make Kit Guidelines” sind Dokumentation, die nicht für Menschen geschrieben wird, sondern für einen AI-Agenten, der aus Design-Tokens und Komponenten Code generiert. Das klingt nach einer technischen Fußnote — ist aber ein Architekturwechsel. Design-System-Teams, die bisher ein Interface für Entwickler gebaut haben (Storybook, Docs-Sites, Readmes), bauen jetzt ein zweites: eines für Maschinen, die diese Systeme interpretieren und anwenden.

Die Implikation geht über Figma hinaus. Jedes System, das von AI-Agenten konsumiert wird — Codebases, Knowledge Bases, API-Dokumentation — steht vor derselben Frage: Ist unsere Dokumentation ein Nachschlagewerk oder eine Steuerungsschicht? Figma beantwortet die Frage, indem es Guidelines als eigenständige Designdisziplin behandelt, nicht als Anhang.

2 — Granularität schlägt Vollständigkeit

Die zentrale Architekturentscheidung: “Multiple short guidelines files are better than a few large files.” Nicht weil kurze Dateien hübscher sind, sondern weil AI-Agenten mit begrenzten Context Windows arbeiten. Eine monolithische design-system.md mit 2.000 Zeilen zwingt den Agenten, irrelevante Information mitzuschleppen. Zwanzig fokussierte Dateien — button.md, color.md, typography.md — erlauben präzises Retrieval.

Das ist eine Designentscheidung, die nichts mit Inhalt zu tun hat und alles mit Informationsarchitektur. Die Parallele zu Microservices ist nicht zufällig: Dekomposition ermöglicht gezielte Adressierung. Wer sein Design System als Monolith dokumentiert, baut eine Architektur, die AI-Agenten bestraft.

3 — Imperativ statt deskriptiv: Dokumentation als Constraint

Figma empfiehlt, vage Formulierungen durch imperative Anweisungen zu ersetzen. Statt “Use small text sparingly” heißt es “Do not use small text except for captions.” Der Unterschied ist nicht stilistisch, sondern funktional: Ein AI-Agent kann Ambiguität nicht auflösen. “Sparingly” ist für einen Menschen interpretierbar, für einen Agenten ist es Noise.

Die Konsequenz: Gute AI-Dokumentation liest sich wie ein Regelwerk, nicht wie ein Styleguide. Das verändert, wer sie schreibt und wie. Content Designer, die für Lesbarkeit optimieren, müssen jetzt auch für Parsbarkeit optimieren — und die beiden Ziele konkurrieren.

4 — Ordnerstruktur ist Retrieval-Architektur

Die empfohlene Struktur — components/, foundations/, composition/ mit je einer overview.md als Router — ist kein Dateisystem-Ästhetik. Sie ist die Sucharchitektur, über die der AI-Agent navigiert. Eine overview.md im Komponentenordner fungiert als Index, der den Agenten zur richtigen Detaildatei leitet. Ordnerstruktur wird zur API.

Das hat eine unangenehme Konsequenz für bestehende Design Systems: Ihre Dokumentationsstruktur, historisch gewachsen aus Confluence-Seiten und Storybook-Addons, ist keine neutrale Ablage mehr. Sie ist aktiv hinderlich, wenn ein AI-Agent sie traversieren soll. Migration ist kein Doku-Projekt, sondern ein Architektur-Refactoring.

5 — Decision Trees als Steuerungslogik

Statt Prosa-Beschreibungen empfiehlt Figma Entscheidungsbäume: “Welcher Button-Variant? → Primary für Hauptaktionen, Neutral für sekundäre, Subtle für tertiäre.” Das ist weniger ein Dokumentationsstil als Kontrollflusslogik: Der Agent bekommt keinen Text zum Interpretieren, sondern einen Algorithmus zum Ausführen.

Die Parallele zu klassischem Interface Design ist direkt: Ein Entscheidungsbaum in der Dokumentation ist funktional äquivalent zu einer Dropdown-Auswahl im UI — er reduziert den Entscheidungsraum auf valide Optionen. Dokumentation wird zur Interaktion.

6 — Konvergenz: Dieselben Prinzipien entstehen unabhängig in anderen Domänen

Die Figma-Empfehlungen konvergieren mit Patterns, die in ganz anderen Kontexten entstanden sind. Andrej Karpathy beschreibt in seinem Essay zu LLM Knowledge Bases dieselbe Konvergenz: Markdown-basierte Wissenssysteme für AI-Agenten folgen unabhängig voneinander denselben Regeln — atomare Dateien statt Monolithe, Index-Dateien als Router, imperatives Framing, Entscheidungsketten statt Prosa. Die Architekturentscheidungen ähneln sich, obwohl die Domänen verschieden sind.

Das deutet auf ein domänenübergreifendes Pattern hin: Es gibt eine emergente Grammatik für “Dokumentation, die Maschinen steuert.” Sie ist weder toolspezifisch noch domänengebunden. Sie folgt aus den Constraints der Technologie — Context Windows, Retrieval-Mechanismen, Ambiguitäts-Intoleranz — und diese Constraints sind überall dieselben.

Einordnung

Geschrieben von jemandem, der Design Systems operativ aufbaut und pflegt und parallel ein LLM-gestütztes Wissenssystem nach denselben Prinzipien strukturiert — die Konvergenzbeobachtung zwischen beiden Domänen ist keine externe Analyse, sondern gelebte Doppelperspektive. Das macht die Patterns konkret, erzeugt aber einen blinden Fleck für Kontexte, in denen Dokumentation nicht von Designern, sondern von technischen Redakteuren oder Content-Strategen verantwortet wird. Deren Perspektive auf die Spannung zwischen Lesbarkeit und Parsbarkeit sähe vermutlich anders aus.

Kritische Einordnung

Was hält stand

• Die Grundthese ist robust: AI-Agenten konsumieren Dokumentation fundamental anders als Menschen. Das verändert, was “gute Dokumentation” bedeutet — nicht als Ersatz, sondern als Erweiterung.
• Praktische Prinzipien funktionieren: Granularität, Imperativ-Stil und Decision Trees verbessern nachweislich die Qualität von AI-generiertem Output — nicht nur bei Figma Make, sondern bei jeder RAG-Architektur.
• Domänenübergreifende Konvergenz als Evidenz: Wenn unabhängige Systeme (Design Systems, Knowledge Bases, Codebases) zu denselben Mustern konvergieren, ist das ein stärkeres Argument als jede einzelne Empfehlung.
• “Treat AI like a new engineer” ist das richtige mentale Modell — es senkt die Einstiegshürde für Teams, die noch nie über AI-Konsumenten ihrer Doku nachgedacht haben.

Was man einordnen muss

• Vendor-Kontext: Figma verkauft ein Produkt (Make), das genau diese Guidelines braucht. Die Empfehlungen sind sinnvoll, aber nicht neutral — sie optimieren für Figmas Retrieval-Pipeline, nicht für AI-Agenten generell.
• Reifegrad: Das Feld ist 6 Monate alt. Ob sich “AI-kompatible Dokumentation” als eigene Disziplin etabliert oder in gute Dokumentationspraxis aufgeht, ist offen.
• Gegenhypothese: Vielleicht erzwingt AI nicht neue Dokumentation, sondern macht die Mängel der bestehenden sichtbar. Imperativ, granular und strukturiert hätten wir immer schreiben sollen — AI ist nur der Anlass, es endlich zu tun.
• Aufwand: Duale Dokumentation (für Menschen und Maschinen) verdoppelt nicht die Arbeit, aber sie erzeugt Wartungskosten. Wer synchronisiert die Developer-Docs mit den Agent-Guidelines, wenn sich Komponenten ändern?
• Knowledge-Base-Parallelen haben Grenzen: Ein persönliches Wissenssystem für einen einzelnen Agenten und ein Design System für ein Team mit 50 Entwicklern haben unterschiedliche Governance-Anforderungen.

Diskussionsfragen

01 Dual Interface: Wenn Design-System-Teams jetzt für Menschen und Maschinen gleichzeitig dokumentieren — wer im Team ist dafür verantwortlich? Braucht Design Ops eine neue Rolle, oder ist das eine Erweiterung bestehender Documentation-Engineering-Praxis?

02 Dokumentation als Produkt: Ist die Konsequenz, dass Dokumentation selbst zum designten Artefakt wird — mit eigener Informationsarchitektur, eigenem Testing, eigenen Quality Gates? Und wenn ja: Was bedeutet das für Budgets und Priorisierung in Design-System-Teams?

03 Konvergenz-Test: Welche anderen Systeme — Codebases, API-Docs, Onboarding-Materialien — profitieren von denselben Prinzipien (Granularität, Imperativ, Decision Trees)? Gibt es eine universelle Checkliste für “AI-ready Documentation”?

04 Gegenhypothese ernst nehmen: Wenn die “neuen” Regeln eigentlich alte sind (klar, strukturiert, präzise) — ist “AI-kompatible Dokumentation” dann ein eigenständiges Thema oder nur ein Rebranding von Dokumentationsqualität?

05 Build vs. Buy: Lohnt es sich, bestehende Design-System-Dokumentation für AI zu migrieren — oder ist es effizienter, sie parallel aufzubauen und die alte für Menschen beizubehalten?

Quellen

• Figma Developer Documentation: Write Design System Guidelines for Make Kits
• Figma Make: AI-Powered Code Generation

Glossar

Make Kit / Figmas Paketformat für Design Systems, das AI-Code-Generierung ermöglicht. Enthält Komponenten, Tokens und Guidelines als maschinenlesbare Einheit.

Context Window / Die maximale Textmenge, die ein AI-Modell gleichzeitig verarbeiten kann. Begrenzt, wie viel Dokumentation ein Agent “sehen” kann — und macht Granularität zur Architekturentscheidung.

Retrieval / Der Mechanismus, mit dem ein AI-Agent relevante Dokumentation findet und in sein Context Window lädt. Ordnerstruktur, Dateinamen und Index-Dateien sind Retrieval-Infrastruktur.

Decision Tree (Entscheidungsbaum) / Verzweigte Wenn-Dann-Logik, die einen Agenten durch Variantenwahl führt. In Dokumentation: Alternative zu Prosa-Beschreibungen, die Ambiguität eliminiert.

RAG (Retrieval-Augmented Generation) / Architekturmuster, bei dem ein AI-Modell externe Dokumente abruft, bevor es antwortet. Design-System-Guidelines für AI sind funktional RAG-Dokumente.

Dual Interface / Das Muster, zwei Dokumentationsschichten parallel zu pflegen — eine für menschliche Entwickler (lesbar, kontextuell), eine für AI-Agenten (parsbar, imperativ, granular).