DESIGN.md — Ein Single-File-Format für Design-Systeme für AI-Coding-Tools (koreanische Zusammenfassung)

Das von Google Labs im Stitch-Projekt vorgeschlagene Format DESIGN.md fand ich so interessant, dass ich mir einige Tage lang die Spezifikation genauer angesehen habe. Weil es zu schade wäre, das nur für mich zu behalten, habe ich sie auf Koreanisch in Form eines Curriculums mit 28 Kapiteln aufbereitet. Die Idee dabei war, dass Menschen, die sich mit demselben Thema beschäftigen, nicht von Anfang an die englische Spezifikation durchforsten müssen – und dass diejenigen, die wie ich die Frage haben, „Wie bringt man einer AI ein Design-System bei?“, alles in einem Rutsch überblicken können.

DESIGN.md ist ein Format, das ein Design-System in einer einzigen Markdown-Datei ausdrücken will. Werte wie Farben, Typografie, Spacing, Radius und Component Tokens werden im YAML-Frontmatter in maschinenlesbarer Form abgelegt. Im darunterliegenden Markdown wird dann festgehalten, „warum man diese Farbe verwendet“, „in welchen Situationen dieser Button-Stil eingesetzt wird“ oder „welche Muster vermieden werden sollten“. Es ist also nicht nur ein einfacher Styleguide, sondern eher die „Quelldatei des Design-Systems“, auf die sich AI-Coding-Agenten wie Claude Code, Cursor oder Codex immer wieder beziehen können.

Hintergrund — Veränderungen, die mir beim Aufbereiten noch einmal klar wurden

• Frühere Frage: „Wie organisiert man ein Design-System gut in Figma?“
• Heutige Frage: „Wie bringt man AI-Coding-Tools dazu, unser Design-System zu lesen?“ und „Was braucht es, damit AI beim Erstellen neuer Seiten die Farb-, Abstands- und Komponentenregeln unserer Marke einhält?“
• Im Zusammenspiel mit Entwicklungen wie Claude Design, Claude Code und Figma MCP bleibt das Design-System nicht mehr nur in Figma, sondern wandert in die Codebase, wird in PRs überprüft und wird zum „dauerhaften Kontext“ für AI-Agenten

Kernpunkte des DESIGN.md-Formats (was mich beim Lesen der Spezifikation besonders beeindruckt hat)

• Doppelte Struktur aus YAML (für Maschinen) + Markdown (für Menschen und AI) — Tokens werden maschinell geparst, der Fließtext hält die Begründungen für Entscheidungen fest
• Tokens sind die Wahrheit, der Text erklärt das Warum — es ist sauber gelöst, dass die Priorität bereits festgelegt ist, falls beide voneinander abweichen
• Die Reihenfolge von 8 Abschnitten ist fest vorgegeben — Bereiche wie colors, typography und spacing dienen selbst als Mental Model des Design-Systems
• lint / diff / export / spec CLI — prüft automatisch Dinge wie fehlerhafte Referenzen, unzureichenden Kontrast, verwaiste Tokens oder Verstöße gegen die Abschnittsreihenfolge
• Interoperabilitätsregeln mit DTCG, Tailwind und Figma-Variablen werden separat festgelegt

Aufbau des Curriculums (28 Kapitel, 7 Module)

• M1 Formatphilosophie · 3 Kapitel — welches Problem dieses Format lösen will, die doppelte Struktur, Priorität von Tokens und Text
• M2 Token-Schema · 5 Kapitel — gesamtes Schema / Farben / Längen und Einheiten / Schriften / Token-Referenzen
• M3 Abschnittsstruktur · 6 Kapitel — Reihenfolge der 8 Abschnitte und die Gestaltungsprinzipien jedes Abschnitts
• M4 Praktische Beispiele lesen · 3 Kapitel — die Fälle Atmospheric Glass, Paws & Paths, Totality Festival
• M5 CLI · 4 Kapitel — lint, diff, export, spec
• M6 Lint-Regeln · 4 Kapitel — 8 Regeln wie broken-ref, contrast, orphaned, section-order usw.
• M7 Erweiterbarkeit · 2 Kapitel — Richtlinien zum Umgang mit unbekannten Inhalten, Beziehung zu DTCG und Tailwind
• Abschließende Zusammenfassung · 1 Kapitel — Zusammenfassung der 27 Kapitel + 10 Prinzipien für die Praxis

Gedanken, die mir beim Aufbereiten kamen

• Je mehr AI UI erzeugt, desto wichtiger werden Design-Systeme vermutlich eher noch. Die Frage verschiebt sich offenbar von „Kann AI gut designen?“ zu „Wie klar hat das Team die Regeln dokumentiert, denen AI folgen soll?“
• DESIGN.md ist ein praktischer Versuch, diese Regeln nicht in Notion oder PDF, sondern innerhalb der Codebase zu verankern. Das bedeutet auch, dass die Ergebnisse von Designer:innen Gegenstand von Reviews auf PR-Ebene werden
• Ich teile das, weil es für alle nützlich sein könnte, die ein Design-System aufbauen oder beim Erstellen von UI mit AI-Coding-Tools schon einmal dachten: „Warum sehen die Ergebnisse jedes Mal so unterschiedlich aus?“ Wenn ich etwas falsch verstanden oder ungenau zusammengefasst habe, sagt mir gern in den Kommentaren Bescheid, dann passe ich es an.

[m00nlygreat]

Ich habe eine Frage dazu: Wenn man DESIGN.md als Anweisung zum Ableiten des Designs versteht, wird es am Ende doch für die ersten paar Seiten – oder sogar nur für eine Seite – verwendet, um ein Moodboard zu erzeugen. Entsteht danach nicht eine Diskrepanz zwischen dem Code und der Anweisungen.md, sodass man sie fortlaufend in beide Richtungen synchronisieren muss?

Letztlich sollte man für das spätere Design doch den Code als Source of Truth betrachten und Dinge wie Variablen oder Bezeichnungen konsistent wiederverwenden. Wenn man DESIGN.md nicht laufend aktualisiert und als SSoT verwaltet, führt das dann nicht dazu, dass Tokens immer wieder hartcodiert werden? Mich würde interessieren, ob es in der praktischen Nutzung damit keine Probleme gibt.

[neostom432]

Bei DESIGN.md lässt sich die Richtung des Codes zwar leicht automatisieren, aber umgekehrt werden neu entstandene Muster im Code nicht automatisch in DESIGN.md übernommen, sodass man sich manuell darum kümmern muss. Mit der Zeit sammeln sich im Code kleine Hardcodings an, die nicht in die Dokumentation einfließen, und das summiert sich.

Allerdings zielt die Philosophie dieses Formats selbst eher darauf ab, „das Design-System innerhalb der Codebasis kontinuierlich weiterzuentwickeln“, daher würde ich das weniger als Nachteil denn als beabsichtigte Betriebsweise sehen. Da Leitfäden, die sonst in Notion oder als PDF eingefroren waren, auf die Ebene von Reviews pro PR heruntergeholt werden, bringt die Struktur offenbar auch die Verantwortung mit sich, dass Menschen sie regelmäßig pflegen. Wir haben es in unserem Projekt eingeführt, und die Konsistenz der Oberflächen ist im Vergleich zu vorher klar gestiegen; da der Nutzen spürbar ist, fühlt sich auch das manuelle Review nicht belastend an. Letztlich ist es eine Frage, wie klar das Team die Maßstäbe festhält, denen die AI folgen soll, und ich würde es so zusammenfassen, dass die Struktur vorsieht, dass Menschen die Pflege übernehmen, damit diese Maßstäbe lebendig bleiben.