Open Design System Format: übergib dein Designsystem einem Agenten
Coding-Agenten schreiben gutes UI und schlechte Versionen deines UI. Das Open Design System Format verpackt ein Designsystem als Bündel aus Markdown, HTML und CSS, das ein Agent lesen und davon bauen kann: Tokens, die einmal existieren und als CSS rendern, typisierte Konzepte in einem Graphen und selbstrendernde Beispiele. Es ist ein striktes Profil von Googles Open Knowledge Format. Hier ist, was es ist, und der odsf-Skill, den ich dazu ausgeliefert habe.
Bitte einen Coding-Agenten um eine Einstellungsseite, und du bekommst eine Einstellungsseite. Sie wird sauber sein, sie wird plausibel sein, und sie wird auf subtile Weise nicht deine sein. Das Primary ist ein leicht anderes Blau. Das Card-Padding liegt ein paar Pixel neben deiner Skala. Der Empty State ignoriert das Pattern, das dein Team letztes Quartal standardisiert hat. Der Agent ist gut in UI. Er ist schlecht in deinem UI, weil ihm nie jemand gesagt hat, was deines ist.1
Das Wissen, das ihm fehlt, existiert. Es liegt in einer Figma-Library, einem Komponenten-Repo, einem Storybook, einer Seite Brand-Guidelines und einer Handvoll Entscheidungen, die nur mündlich getroffen wurden. Nichts davon liegt in einer Form vor, die der Agent während der Arbeit laden kann. Also rekonstruiert er es in jeder Sitzung neu oder rät, und liefert plausible, aber falsche Defaults.
Das Open Design System Format (ODSF) ist ein Weg, dem Agenten stattdessen die Antwort zu übergeben.
Die Form des Problems
Die üblichen Behelfslösungen scheitern jeweils auf eine bestimmte Weise.
Zeig dem Agenten deine Komponenten-Library, und er rekonstruiert das System aus der Implementierung, inkonsistent, und nimmt die Zufälle mitsamt der Absicht mit. Gib ihm Screenshots, und er sieht Pixel ohne Semantik: er kann eine primäre Aktion nicht von einer destruktiven unterscheiden, oder ein Token von einem Einzelfall. Gib ihm eine einzelne Design-Token-Datei, und du hast Farben und Spacing abgedeckt, aber nicht die Komponenten, Patterns, Behaviors und Do-and-Don't-Regeln, die darüber entscheiden, ob das Ergebnis tatsächlich richtig ist. Stell einen Server hin, der deine Designdaten streamt, und du hast dir eine Plattform, eine Abhängigkeit und etwas zum Laufenhalten gekauft, für etwas, das im Kern ein Haufen Fakten ist.
Was ein Agent braucht, ist das Designwissen selbst, in einer Form, die er direkt lesen, nach Relevanz navigieren und aus der er kopieren kann. Dateien, kein Dienst.
Was ODSF ist
ODSF verpackt ein Designsystem als ein in sich geschlossenes Bundle: ein Verzeichnis aus Markdown, HTML und CSS unter Versionskontrolle, das ein Agent lesen, navigieren und auf eine Aufgabe anwenden kann, ohne SDK, ohne Plattform und ohne Lock-in.1
Dafür erfindet es keinen neuen Container. ODSF ist ein striktes Profil von Googles Open Knowledge Format (OKF), der herstellerneutralen Spezifikation für agentenlesbares Wissen: ein Bundle aus Markdown-Konzepten, je ein Pflichtfeld, ein nachsichtiger Consumer-Vertrag, Links als Graph.2 Alles, was OKF über Bundles, Konzepte, Frontmatter, Links, Indizes und Versionierung sagt, gilt in ODSF unverändert. Auf diesen Container setzt es das Token-Modell von Google Labs' design.md auf,3 und ergänzt dann den Rest eines Designsystems: Komponenten, Patterns, Behaviors und Guidelines als typisierte Konzepte erster Klasse, dazu lauffähige Beispiel-Assets.
Ein Bundle hat eine vorhersehbare Form, organisiert nach Design-Domäne:
Diese Ordner sind Konvention, keine Pflicht. Die eigentliche Struktur sind die Links zwischen den Konzepten, die die Hierarchie frei kreuzen.
Zwei Regeln und ein nachsichtiger Leser
Die Konformität ist bewusst winzig. Ein Bundle ist ein gültiges ODSF-Bundle, wenn zwei Dinge gelten: Es ist ein gültiges OKF-Bundle (jede Konzeptdatei beginnt mit YAML-Frontmatter, das ein nicht-leeres type trägt), und seine Wurzel-index.md deklariert eine odsf_version. Das ist die gesamte harte Anforderung. Das Token-Modell, die Asset-Konventionen, das Typ-Vokabular, die Body-Abschnitte: all das ist empfohlene Struktur, der ein Produzent folgen sollte und deren Abwesenheit ein Consumer tolerieren muss.
Verbreitung schlägt Durchsetzung
ODSF erbt OKFs nachsichtigen Consumer-Vertrag. Ein Leser darf ein Bundle nicht
ablehnen, weil ein Token-Block fehlt, ein Beispiel-Asset abwesend ist, ein
Konzepttyp unbekannt ist oder ein Link kaputt ist. Er liest, was da ist, und
degradiert sanft durch das, was fehlt, bis hinunter zu einem Haufen
typisierten Markdowns, der immer noch nützlich ist.
Aus Regel eins folgt etwas Praktisches. Weil Regel eins die OKF-Konformität ist, ist jedes bestehende OKF-Bundle nur eine odsf_version-Zeile davon entfernt, ein ODSF-Bundle zu sein. Das Format zu übernehmen ist eine Änderung plus optionale Anreicherung, kein Neubau. Und ein reines OKF-Werkzeug, ein generischer Agent oder ein Graph-Viewer, liest ein ODSF-Bundle unverändert und verliert nur die designspezifischen Annehmlichkeiten.
Tokens, die einmal existieren und zweimal rendern
Der Kern von ODSFs "mehr" gegenüber einer reinen Token-Datei ist, dass ein Token einmal aufgeschrieben wird und in zwei synchronisierten Projektionen auftaucht, sodass das Beschreiben des Systems und das Benutzen nie auseinanderdriften.
Die kanonische Definition liegt im Frontmatter des Foundation-Konzepts, dem sie gehört:
foundations/color.md
tokens:
colors:
primary:"#3b5bdb"
on-primary:"#ffffff"
Das projiziert mechanisch auf ein Stylesheet, das der Agent (und der Code, den er schreibt) direkt konsumieren kann. Jeder Token-Pfad wird zu einer CSS Custom Property, mit Bindestrichen verbunden:
css
/* styles/tokens.css */
:root{
--colors-primary:#3b5bdb;
--colors-on-primary:#ffffff;
}
Eine Komponente wiederholt nie einen Wert. Sie referenziert ein Foundation-Token mit der {group.name}-Syntax von design.md und drückt interaktive Zustände als separate, mit Suffix versehene Einträge aus:
components/button.md
tokens:
button-primary:
backgroundColor:"{colors.primary}"
textColor:"{colors.on-primary}"
button-primary-hover:
backgroundColor:"{colors.primary-strong}"
Foundation-Tokens werden zu Custom Properties; eine Komponenten-Referenz wird zu einer Regel in styles/components.css, die sie mit var(...) konsumiert, nie einem fest verdrahteten Wert:
css
/* styles/components.css */
.btn--primary{
background:var(--colors-primary);
color:var(--colors-on-primary);
}
Das Frontmatter ist die Quelle der Wahrheit, das CSS ist seine Projektion. Ändere das Token, und jedes Beispiel, das das Stylesheet verlinkt, rendert passend neu. Die Beschreibung und die lauffähigen Werte können nicht auseinanderlaufen, weil es nur eine Version gibt.
Zeigen, nicht nur beschreiben
Ein als Prosa geschriebenes Designsystem sagt einem Agenten, was er tun soll. ODSF zeigt es ihm außerdem, denn ein Agent kopiert ein korrektes Beispiel weit zuverlässiger, als er einem Absatz folgt.
Jedes Konzept kann ein begleitendes Asset ausliefern: ein button.example.html, das ein vollständiges, eigenständiges Dokument ist und genau das eine rendert, was das Konzept lehrt, indem es die eigenen tokens.css und components.css des Bundles verlinkt, sodass es automatisch wahr bleibt. Guidelines und Komponenten können ein kontrastierendes Paar ausliefern, color-not-alone.do.html neben color-not-alone.dont.html, sodass der Agent sowohl das beabsichtigte Ergebnis als auch genau den zu vermeidenden Fehler sieht. Der Body erklärt, warum das Don't falsch ist; das Asset zeigt, wie es aussieht.
Ein konsistenter Do-and-Don't-Abschnitt mit verlinkten Assets ist die einzelne wertvollste Konvention, um einen Agenten von plausiblem, aber falschem Output wegzulenken. Es ist der Teil, den design.md implizit ließ und den ODSF konkret macht.
Ein Graph, kein Ordner
Konzepte sind typisiert, und der Typ ist das, was einem Agenten das Routen erlaubt. Foundations (Color, Typography, Spacing, Elevation, Shape, Motion, Layout) tragen die Designsprache. Bausteine und Regeln (Component, Pattern, Behavior, Guideline, Accessibility, Voice) tragen alles, was darauf aufbaut. Wie bei OKF ist das Vokabular beschreibend und offen: nimm den spezifischsten Typ, der passt, erfinde einen, wenn keiner passt, und ein Leser toleriert Werte, die er nie gesehen hat.
Konzepte verlinken sich mit ganz normalen Markdown-Links, und die Prosa um den Link benennt die Beziehung: eine Komponente zeigt auf die Foundations, deren Tokens sie nutzt, und die Behaviors, die ihre Interaktion regeln; ein Pattern zeigt auf die Komponenten, die es komponiert; alles zeigt auf die Guidelines und Accessibility-Regeln, die es einschränken. Das Ergebnis ist ein Graph, den ein Agent von einer Aufgabe ("baue ein Anmeldeformular") bis zu genau den Patterns, Komponenten, Tokens, Behaviors und Regeln abläuft, die diese Aufgabe braucht, ohne das ganze Bundle zu lesen. Das ist OKFs progressive Offenlegung, auf Design spezialisiert.
Drei echte Systeme, eine Form
Ein Format ist eine Behauptung, bis etwas darin ausgeliefert wird. ODSF kommt mit drei durchblätterbaren Beispiel-Bundles, von denen jedes ein echtes Designsystem nachbaut, gewählt, um verschiedene Ecken der Spezifikation zu belasten: Anthropics Claude, eine feste warme Markenstimme; GitHubs Primer, ein thembares System mit Light- und Dark-Mode; und Vercels Geist, eine monochrom-orientierte Library, die Dutzende Komponenten umspannt.1 Eine festgelegte Marke, ein Mehrmodus-Komponentensatz und ein umfassendes System passen alle in dieselbe Bundle-Form, was der Sinn dabei war, alle drei zu bauen.
Das Repository liefert die funktionierenden Teile neben der Prosa: die normative Spezifikation, ein Philosophie-Dokument, kopierfertige Templates für jeden Konzepttyp, einen abhängigkeitsfreien Validator, der nur an den zwei harten Regeln scheitert und bei den weichen Empfehlungen warnt, und einen Viewer als einzelne HTML-Datei, der jedes Bundle im Browser rendert. Kein Build-Schritt, kein Account, kein Dienst.
Ich habe einen Skill dafür gebaut
Eine Spezifikation zu lesen ist das eine. Einen Agenten dazu zu bringen, ein konformes Bundle zu erzeugen und es konform zu halten, während Tokens nachjustiert und Varianten ergänzt werden, ist etwas anderes. Also habe ich den gesamten Workflow als Agenten-Skill verpackt.
Der odsf-Skill bringt einem Agenten bei, ODSF-Bundles zu erstellen, zu validieren und zu pflegen. Er stellt die Befehle bereit, die das Format nahelegt (init, add, token, asset, edit, enrich, link, index, log, validate, export, migrate, consume), und läuft ebenso nützlich implizit: bitte ihn, eine Farbskala zu dokumentieren, eine Komponente zu spezifizieren oder einen Figma-Export in etwas zu verwandeln, von dem ein Agent bauen kann, und er liefert das Ergebnis als konformes Bundle mit lauffähigem Beispiel statt loser Prosa. Er trägt die Spezifikation, die Templates und den Validator, und er folgt bei jeder Änderung einer Ripple-Checkliste, sodass eine einzige Token-Änderung die Foundation, tokens.css, die Komponente, components.css, das Beispiel-Asset, die Varianten-Tabelle, die Timestamps und das Log erreicht, ohne dass eines ausgelassen wird. Genau dort verrotten Bundles still, und genau das ist die Buchhaltung, in der ein Agent besser ist als ein Mensch.
Er läuft in jedem Agenten, der das skills.sh-Format spricht (Claude Code, Cursor, Codex, Cline, Windsurf, OpenCode). Installiere ihn einzeln:
Die vollständige Aufschlüsselung findest du auf der odsf-Skill-Seite.
Die Wette
Der Agent, in den du dieses Jahr dein Designsystem verdrahtest, ist vielleicht nicht der, zu dem du nächstes Jahr greifst. ODSFs Wette, von OKF geerbt, ist, dass ein als schlichte, verknüpfte, versionierte Dateien geschriebenes Designsystem das Werkzeug überlebt, für das du es geschrieben hast. Markdown hat schon ein Dutzend Editoren überlebt. Deine Farbrollen, deine Spacing-Skala und die Regeln, zu denen sich dein Team durchgerungen hat, verdienen dieselbe Haltbarkeit, und sie sollten für den nächsten Agenten genauso lesbar sein wie für den aktuellen.
Wenn ein Coding-Agent immer wieder plausible, aber falsche Versionen deiner Oberfläche liefert, ist die Lösung kein besserer Prompt. Es ist, dem Agenten dein Designsystem in einer Form zu geben, die er tatsächlich lesen kann. Schreib jedes Stück einmal auf, gib ihm einen Typ, liefere sein Beispiel aus, und committe es.
