Wie man ein Designsystem dokumentiert, damit eine KI es tatsächlich befolgt

Der 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.

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 ist es, was eine komponentenorientierte Seite niemals abdeckt.

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 Komponentenseite wird diese jemals erwähnen.

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.

Setzen Sie die letzten beiden Zeilen in Beziehung zueinander. 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 reproduziert – genau jenen generischen Look, den die Datei eigentlich verhindern sollte.

Jede dieser Änderungen korrespondiert mit einem oben gemessenen Fehler. Zusammen angewandt, verwandeln sie eine Beschreibung in etwas Ausführbares.

1. 1

   Jeder Farbe eine Rolle zuweisen, nicht nur einen Wert

   #6b7280 ist 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 eine klare 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.

   Copy

   --text-muted: #6b7280   /* secondary and supporting text only */
   --border-subtle: #e5e7eb /* structural edges, dividers */
   --text-disabled: #9ca3af /* disabled controls only */

2. 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 anhand eines gerenderten Screens überprüft werden kann, ist er reine Dekoration.

3. 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.

   Copy

   ## 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. 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ß souverän aussah, blendet auf fast schwarzem Grund. Ein zweiter Token-Satz kostet eine Stunde Zeit und eliminiert eine ganze Kategorie von Nachbesserungen.

5. 5

   Die Entscheidung zur Dichte explizit festlegen

   Ob es sich um ein dichtes Tool oder eine luftige Marketing-Flä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. 6

   Mindestens zwei Motive benennen

   Die wiederkehrenden spezifischen Elemente, 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. 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.

Das Ergebnis dieser sieben Änderungen ist eine Datei, deren Werte ein Agent auflösen kann, ohne etwas erfinden zu müssen. Dies ist dieselbe Information, jedoch gerendert statt geschrieben – nützlich als Checkliste dafür, was Ihre eigene Datei beantworten können muss:

Nicht alle Verbote funktionieren gleich gut. Drei Eigenschaften unterscheiden diejenigen, die den Output verändern, von denen, die ignoriert werden.

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.

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 Intention und die Verbote an den Anfang. Ein Modell, das von oben nach unten liest, stößt zuerst auf die allgemeine Regel und dann auf den Sonderfall. Dies entspricht der 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 ours

Nicht alles sollte in der Datei stehen; der Versuch, alles unterzubringen, führt dazu, dass sie ihren Nutzen verliert. Die Trennlinie ist, ob der Agent die Information vor einer Entscheidung benötigt oder nur bei Bedarf.

IBM's Carbon MCP server ist ein gutes Vorbild 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 – denn ein Retrieval-Tool liefert nur das, wonach der Agent explizit gefragt hat. Mehr zur Aufteilung.

Die Datei zu schreiben und einfach vorauszusetzen, dass sie funktioniert, führt dazu, dass Teams das Problem erst drei Wochen später bemerken. Vier Prüfschritte, aufsteigend nach Aufwand.

1. 1

   Suche nach expliziten Farbwerten mittels Grep

   Wenn der Agent semantische Rollen befolgt, sollten sich außerhalb der Token-Datei keine Hex-Werte befinden.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Suche nach den untersagten Schriftschnitt-Gewichten mittels Grep

   Bei den Gewichten fällt die Hierarchie oft unbemerkt auf den Standard zurück; sie sind das schnellste Signal dafür, dass ein Verbot nicht greift.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' src | head -30

3. 3

   Fordern Sie denselben Screen zweimal in separaten Sessions an

   Die Konsistenz über Sessions hinweg ist der eigentliche Test. Wenn zwei Durchläufe bei Abständen, Radien oder Hierarchien signifikant voneinander abweichen, schränkt die Datei das Notwendige nicht ausreichend ein – und der Diff zeigt genau, welcher Abschnitt fehlt.

4. 4

   Erstellen Sie zuerst einen Screen im Dark Mode

   Falls der Dark Mode eher abgeleitet als definiert wurde, zeigt sich dies hier. 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.