Warum die Dokumentationsseite nicht funktioniert
Der erste Instinkt ist, den Agenten auf die Designsystem-Seite zu verweisen. Das hilft selten, und zwar aus vier strukturellen Gründen, die nichts mit der Qualität der Seite zu tun haben.
| Dokumentationsseite | Was ein Agent benötigt | |
|---|---|---|
| Zugriffsmuster | Durchsucht. Man navigiert zu der benötigten Seite | Alles Relevante im Kontext, vor der ersten Entscheidung |
| Organisation | Nach Komponenten: Button, Input, Card | Nach Entscheidungen: Farbrollen, Density, Elevation, Verbote |
| Tonalität | Beschreibt die Intention: „Unsere Buttons wirken selbstbewusst und nahbar“ | Definiert Einschränkungen: „font-weight 500, radius 6px, niemals ein Gradient“ |
| Vollständigkeit | Deckt ab, was existiert | Muss auch abdecken, was nicht existieren darf |
Die Zeile zur Organisation ist diejenige, die oft übersehen wird. Eine nach Komponenten organisierte Seite ist perfekt für jemanden, der bereits weiß, dass er einen Button benötigt. Ein Agent, der gerade einen Screen erstellt, hat noch nicht entschieden, welche Komponenten er einsetzt. Seine ersten Entscheidungen betreffen Density, Hierarchie und Layout – und genau das wird auf einer komponentenbasierten Seite nie abgedeckt.
Die Zeile zur Vollständigkeit ist die folgenreichste. Dokumentationen beschreiben, was existiert, da dies ihr Zweck ist. Aber der Unterschied zwischen Ihrer Benutzeroberfläche und einer generischen ist primär eine Menge an Dingen, die Sie niemals tun – und keine Komponenten-Seite wird diese jemals erwähnen.
Was echte Dateien tatsächlich enthalten
Wir haben 299 DESIGN.md-Dateien aus öffentlichen Repositories und Verzeichnissen analysiert – Dateien, die bewusst geschrieben wurden, um KI-Agenten Design-Richtlinien zu geben – und deren Inhalte gemessen. 72 davon waren spezifische Visual-Design-Dateien. Das Muster ist konsistent genug, um als Checkliste für Dinge zu dienen, die man vermeiden sollte.
| Anteil der Dateien | |
|---|---|
| Farben als reine Hex-Werte, ohne semantische Rolle | 86% |
| Keinerlei Verbote | 76% |
| Keine Definition für den Dark Mode | 69% |
| Keine unterscheidbaren Motive | 57% |
| Mindestens ein vages Adjektiv als Richtlinie | 54% |
| Kein einziger konkreter Größenwert | 44% |
| Typografie überhaupt erwähnt | 83% |
Setzen Sie die letzten beiden Zeilen gegenüber. Typografie wird in 83% der Dateien erwähnt, aber 44% enthalten keinerlei konkrete Größenwerte. Diese Lücke ist das gesamte Problem in einer einzigen Statistik: In den Dateien wird über Typografie gesprochen, ohne jemals festzulegen, wie groß die Elemente sein sollen.
Die Zahl der Adjektive ist die andere Hälfte. „Clean“ erscheint in 39% dieser Dateien, „modern“ in 36%. Beides sind Begriffe, die ein Modell erfüllt, indem es den Durchschnitt seiner Trainingsverteilung produziert – genau jenen generischen Look, den die Datei eigentlich verhindern sollte.
Ein Modell, das um „clean und modern“ gebeten wird, produziert den Durchschnitt von allem, was es gesehen hat. Das tut das Modell jedes anderen Nutzers bei derselben Anfrage ebenfalls.
Die sieben Änderungen
Jede dieser Änderungen korrespondiert mit einem oben gemessenen Fehler. Zusammen angewendet, verwandeln sie eine Beschreibung in etwas Ausführbares.
- 1
Jeder Farbe eine Rolle zuweisen, nicht nur einen Wert
#6b7280ist ein Wert, den ein Modell gleichermaßen für Fließtext, Rahmen, Icons, Platzhalter und deaktivierte Zustände verwenden wird.--text-muted, definiert ausschließlich als sekundärer und unterstützender Text, hat genau eine Aufgabe. Fünf Rollen sind besser als ein Hex-Wert, und sie ermöglichen es, Rahmen später zu ändern, ohne die Bildunterschriften zu beeinflussen.--text-muted: #6b7280 /* secondary and supporting text only */ --border-subtle: #e5e7eb /* structural edges, dividers */ --text-disabled: #9ca3af /* disabled controls only */ - 2
Jedes Adjektiv durch eine Zahl oder eine Regel ersetzen
„Großzügige Abstände“ wird zu „Sektionsabstand 64px, Card-Padding 24px“. „Clean Typography“ wird zu einer Skala. Wenn ein Satz nicht gegen einen gerenderten Bildschirm geprüft werden kann, ist er bloße Dekoration.
- 3
Verbote explizit formulieren
Der Bereich mit der größten Wirkung und derjenige, den 76% der Dateien komplett auslassen. Fünf Zeilen genügen für den Anfang.
## Never - No gradients - No drop shadows — elevation is a surface step plus a 1px border - No font-weight above 600 - No colour value outside the token set - No border-radius above 12px - 4
Dark Mode definieren, nicht ableiten lassen
Bleibt dies undefiniert, invertiert ein Modell den Light Mode, und das Ergebnis scheitert vorhersehbar: Schatten wirken nicht mehr, Mittelgrautöne verlieren an beiden Enden den Kontrast und ein gesättigierter Akzent, der auf Weiß selbstbewusst wirkte, blendet auf fast schwarzem Grund. Ein zweiter Token-Satz kostet eine Stunde Zeit und eliminiert eine ganze Kategorie von Nachbesserungen.
- 5
Die Entscheidung zur Informationsdichte explizit angeben
Ob es sich um ein dichtes Tool oder eine luftige Marketing-Oberfläche handelt, beeinflusst jede nachfolgende Entscheidung – und es ist die Entscheidung, die die meisten Dateien niemals treffen. Wenn Ihr Produkt beide Arten von Oberflächen hat, bedeutet das zwei Dateien, nicht eine vage formulierte Datei.
- 6
Mindestens zwei Motive benennen
Die wiederkehrenden spezifischen Details, die das Design einzigartig machen: eine 2px-Akzentlinie links von Sektionsüberschriften, numerische Spalten immer tabellarisch und rechtsbündig, eine bestimmte Art, wie Empty States gezeichnet werden. 57% der Dateien haben keine, weshalb deren Output zwar korrekt, aber charakterlos ist.
- 7
Auf die Token-Datei verweisen; niemals Werte wiederholen
Sobald ein Hex-Wert sowohl in der Design-Datei als auch in der Token-Datei existiert, wird einer aktualisiert und der andere nicht – und das Modell wird selbstbewusst den veralteten Wert verwenden. Referenzieren Sie, kopieren Sie nicht.
Wenn Sie nur eine dieser Änderungen umsetzen, wählen Sie die dritte. Eine Liste von Verboten erfordert fünfzehn Minuten Arbeit und verändert den generierten Output stärker als die anderen sechs zusammen, da sie den enormen Entscheidungsspielraum einschränkt, den Ihre Erlaubnisse offen gelassen haben.
Das Ergebnis dieser sieben Änderungen ist eine Datei, deren Werte ein Agent auflösen kann, ohne etwas erfinden zu müssen. Hier ist dieselbe Information gerendert statt geschrieben – nützlich als Checkliste dafür, was Ihre eigene Datei beantworten können muss:
Token specimen · real values
Sage & Slate Editorial
Live renderSage & Slate Editorial's actual tokens — the same values its exports use.
Wie man ein wirksames Verbot schreibt
Nicht alle Verbote funktionieren gleich gut. Drei Eigenschaften unterscheiden diejenigen, die den Output verändern, von denen, die ignoriert werden.
| Schwach | Stark | Warum | |
|---|---|---|---|
| Spezifität | "Vermeiden Sie übermäßig dekoratives Styling" | "Keine Verläufe, keine Schlagschatten, keine dekorativen Rahmen" | Ein Modell kann "übermäßig" nicht bewerten |
| Prüfbarkeit | "Halten Sie die Typografie zurückhaltend" | "Verwenden Sie niemals ein font-weight über 600" | Das eine lässt sich per Grep finden; das andere nicht |
| Alternative angegeben | "Verwenden Sie kein box-shadow" | "Kein box-shadow: Elevation ist eine Oberflächenstufe plus ein 1px-Rahmen" | Ein Verbot ohne Ersatz führt dazu, dass das Modell einen Ersatz erfindet |
Die dritte Zeile ist diejenige, die übersehen wird. Ein Verbot ohne Alternative schafft eine Lücke, die das Modell füllen muss – und es füllt sie aus derselben Trainingsverteilung, der man eigentlich entkommen wollte. Auf jedes "Niemals X" sollte ein "Stattdessen Y" folgen.
Struktur und Länge
Die Datei muss zusammen mit der eigentlichen Aufgabe in den Kontext passen, was eine reale Obergrenze setzt. Etwa 400 Zeilen sind ein praktikables Ziel; darüber hinaus verlieren einzelne Regeln gegenüber der Aufgabe an Aufmerksamkeit.
Auch die Reihenfolge ist entscheidend. Platzieren Sie die Absicht und die Verbote an den Anfang. Ein Modell, das von oben nach unten liest, stößt auf die allgemeine Regel, bevor es den Sonderfall erreicht. Dies ist dieselbe Reihenfolge, die Stripe in seiner Appearance API verwendet: zuerst das Theme, dann Variablen, dann spezifische Regeln.
# DESIGN.md
## Intent <- who reads this product, and what it is for
## Never <- the prohibitions, early and unmissable
## Colour <- roles for light and dark, referencing tokens
## Type <- scale with real numbers, weight band, tracking
## Spacing & density <- the scale, and which surface uses which step
## Elevation <- the strategy, stated once
## Composition <- how components sit together
## Motifs <- what makes this design specifically oursWenn ein Produkt tatsächlich unterschiedliche Oberflächen hat – etwa eine Marketing-Seite und ein komplexes Dashboard –, schreiben Sie nicht eine einzige Datei mit Einschränkungen. "Großzügige Abstände, wobei Tabellen dichter sein können" sind zwei Regeln, die sich als eine ausgeben, und das Modell muss sich entscheiden. Schreiben Sie eine Root-Datei für alles, was konstant bleibt, und oberflächenspezifische Dateien für die Unterschiede.
Was stattdessen in einen Server gehört
Nicht alles sollte in der Datei stehen; der Versuch, alles unterzubringen, führt dazu, dass sie den Rahmen des Nützlichen sprengt. Die Trennlinie ist, ob der Agent die Information vor einer Entscheidung benötigt oder nur bei Bedarf.
| Wo | Warum | |
|---|---|---|
| Komponenten-APIs, Props, Varianten | Server | Umfangreich, häufige Änderungen, erst benötigt, wenn eine Komponente ausgewählt wurde |
| Icon-Katalog | Server | Hunderte von Namen, einzeln abgefragt |
| Farbrollen, Skalen, Dichte | Datei | Jedes Mal vor der ersten Entscheidung benötigt |
| Verbote | Datei | Ein Agent kommt nie von selbst auf die Idee zu fragen, was verboten ist. Er muss es bereits wissen |
IBM's Carbon MCP server ist ein gutes Modell für die erste Spalte: Er stellt die Dokumentationssuche, Code-Beispiele für Komponenten, Diagramme und experimentelle Komponenten als Tools bereit. Bemerkenswert ist, dass keine davon Verbote sind, da ein Retrieval-Tool nur das ausgibt, wonach der Agent explizit gefragt hat. Mehr zur Aufteilung.
Überprüfung der Funktionsweise
Die Datei zu schreiben und einfach vorauszusetzen, dass es funktioniert, führt dazu, dass Teams das Problem erst drei Wochen später entdecken. Vier Prüfungen, in steigender Reihenfolge des Aufwands.
- 1
Nach literalen Farbwerten suchen (Grep)
Wenn der Agent semantischen Rollen folgt, sollten sich außerhalb der Token-Datei keine Hex-Werte befinden.
grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \ | grep -v 'tokens\|globals.css' - 2
Nach den untersagten Weights suchen (Grep)
Bei den Weights kehrt die Hierarchie oft unbemerkt zum Standard zurück; sie sind das schnellste Signal dafür, dass ein Verbot nicht greift.
grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' src | head -30 - 3
Denselben Screen zweimal in separaten Sessions anfordern
Die Konsistenz über Sessions hinweg ist der eigentliche Test. Wenn zwei Durchläufe bei Spacing, Radius oder Hierarchie signifikant voneinander abweichen, schränkt die Datei das Notwendige nicht ausreichend ein. Der Diff zeigt genau, welcher Abschnitt fehlt.
- 4
Zuerst einen Screen im Dark Mode erstellen
Falls der Dark Mode abgeleitet statt definiert wurde, wird dies hier sichtbar. Es ist wesentlich kostengünstiger, dies beim ersten Screen zu bemerken als beim zwanzigsten.
Die ersten beiden Punkte gehören in die CI. Ein Check, der einen Pull Request aufgrund eines rohen Hex-Werts ablehnt, leistet mehr für die langfristige Konsistenz als jede Dokumentation. Zu diesem Schluss kamen Salesforce mit dem SLDS-Linter und Stripe, indem die Funktion vollständig entfernt wurde.
Identity Forge Design-Kits liefern diese Struktur vorinstalliert: 28 semantische Farenrollen für Light und Dark Mode, Typografie- und Spacing-Skalen, Elevation, Motive sowie explizite Do's und Don'ts, serialisiert in einer DESIGN.md. Kits durchsuchen oder lesen Sie, wie man eine DESIGN.md generiert.
Kann ich meinen AI-Agent einfach auf meine Dokumentationsseite des Designsystems verweisen?
Das funktioniert selten. Eine Website wird seitenweise durchstöbert, ist nach Komponenten organisiert und beschreibt die Intention in Prosa. Ein Agent benötigt die Entscheidungen im Kontext, bevor er eine Komponente auswählt – organisiert nach Entscheidungen statt nach Komponenten, mit Einschränkungen, die als prüfbare Regeln formuliert sind. Eine Datei im Repository erfüllt diesen Zweck; eine Website nicht.
Wie lang sollte eine DESIGN.md sein?
Etwa 400 Zeilen sind eine praktikable Obergrenze. Die Datei muss den Kontext mit der eigentlichen Aufgabe teilen; darüber hinaus verlieren einzelne Regeln an Beachtung. Wenn die Datei wächst, bedeutet dies meist, dass sie mehrere Oberflächen gleichzeitig abdeckt und in eine Root-Datei sowie oberflächenspezifische Dateien aufgeteilt werden sollte.
Was ist der wichtigste Abschnitt?
Die Verbote. 76 % der veröffentlichten Design-Dateien enthalten keine, dabei besteht der Unterschied zwischen einer eigenen Oberfläche und einer generischen primär aus den Dingen, die man niemals tut. Fünfzehn Minuten Arbeit an einem „Never“-Abschnitt verändern den Output stärker als jeder andere Abschnitt vergleichbarer Länge.
Sollte ich meine Token-Werte in die Design-Datei schreiben?
Nein: referenzieren Sie diese. Sobald ein Wert an zwei Stellen existiert, wird einer aktualisiert und der andere nicht, und das Modell wird selbstbewusst die veraltete Kopie verwenden. Geben Sie die Rolle und deren Anwendungsbereich an; die Token-Datei verwaltet den Wert.
Benötige ich immer noch eine Dokumentationsseite, wenn ich eine DESIGN.md habe?
Ja, für Menschen und für die Details der Komponenten-API, die zu umfangreich für eine Datei sind. Die beiden ergänzen sich: Die Website dokumentiert tiefgehend, was existiert; die Datei legt die Entscheidungen fest, die ein Agent vor dem Start benötigt. Große Komponenten-Kataloge werden besser durch einen MCP-Server als durch eine der beiden Optionen bedient.