JPKCom DB

DESIGN.md: Das Design-System als Datei, die auch die KI liest

Was das DESIGN.md-Format von Google Labs wirklich leistet: Hintergrund, Nutzen für KI, Barrierefreiheit und CMS-Anbindung — am lebenden Beispiel und mit den Nachteilen.

von ·

Frag ein beliebiges Projektteam, warum die Buttons abgerundet sind. Du bekommst vier Antworten: „War schon immer so", „Steht im Figma", „Hat der Kunde damals so gewollt" und „Weiß ich nicht, das ist von vor meiner Zeit". Die Werte selbst findet man in zehn Sekunden — sie stehen im CSS. Was fehlt, ist die Begründung. Und mit ihr die Fähigkeit, eine Entscheidung zu wiederholen, zu verteidigen oder bewusst zu revidieren.

Genau diese Lücke will das Format DESIGN.md schließen: eine einzelne Textdatei im Projekt, die maschinenlesbare Design-Tokens mit menschenlesbarer Begründung verbindet. Sie liegt neben dem Code, wandert mit ihm durch Git und ist so geschrieben, dass ein Coding-Agent sie versteht — ohne dass ein Mensch dafür schlechter dran wäre.

Dieser Artikel ist die ausführliche Bestandsaufnahme: woher das Format kommt, was es tatsächlich leistet, was es ausdrücklich nicht leistet, und wie sich das für Entwickler, Designer, Kundenberater und Kunden unterschiedlich anfühlt. Als lebendes Beispiel dient die DESIGN.md meiner Hauptseite jpkc.com — eine echte, gepflegte, 406 Zeilen lange Datei, kein Demo-Schnipsel.

Zur Methodik: Alle Zahlen in diesem Artikel sind selbst gemessen — am Repository des Formats, am Werkzeug, an den beiden lebenden Dateien und am Git-Verlauf. Stand: August 2026. Wo ich etwas nicht belegen konnte, steht das ausdrücklich dabei, statt dass ich es glattbügele.

Was eine DESIGN.md ist

Die Datei hat zwei Schichten. Oben ein Frontmatter — ein YAML-Block, der von ----Zeilen eingefasst wird und maschinenlesbare Werte enthält. Darunter ein normaler Markdown-Text, der erklärt, warum diese Werte so sind.

---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:
  sm: 4px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors

- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.

Ein Design-Token ist dabei nichts anderes als eine benannte Design-Entscheidung: „die Markenfarbe heißt primary und ist #1A1C1E". Der Vorteil des Namens gegenüber dem Wert ist, dass er die Absicht transportiert und an einer Stelle geändert werden kann.

Die Sektionen im Textteil folgen einer festen Reihenfolge — Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Weglassen ist erlaubt, Umsortieren gibt eine Warnung. Innerhalb der Werte kann man mit {colors.primary} auf andere Tokens verweisen, ähnlich wie eine Formel in einer Tabellenkalkulation.

Das war die ganze Mechanik. Interessant wird es bei der Frage, welche der beiden Schichten eigentlich die wichtigere ist — dazu gleich mehr, denn dort liegt der spannendste Widerspruch des Projekts.

Woher das Format kommt

Hier lohnt Genauigkeit, weil die Herkunft die Einordnung verändert.

DESIGN.md ist kein eigenständiges Standardisierungsvorhaben. Es ist das offengelegte Format von Stitch, einem Produkt von Google Labs, das aus Beschreibungen Oberflächen erzeugt. Das Repository nennt als Homepage folgerichtig die Stitch-Dokumentation. Am 21. April 2026 kündigte Cassia Xu, Software Engineer bei Google, die Öffnung auf dem Google-Blog an — wörtlich: „Today, we're open-sourcing the draft specification for DESIGN.md, so it can be used across any single tool or platform."

Die harten Eckdaten, gemessen im August 2026:

Merkmal Wert
Repository google-labs-code/design.md, angelegt am 10.04.2026
Lizenz Apache-2.0
CLI-Paket @google/design.md, Version 0.4.0
Formatversion ausdrücklich alpha
Releases 5 in gut drei Monaten (0.1.0 bis 0.4.0)
Commits 62 auf dem Hauptzweig, von 27 Beitragenden
Reichweite 27.111 Sterne, 2.260 Forks; rund 1,39 Mio. CLI-Downloads

Drei Beobachtungen dazu, die man beim Abwägen braucht:

Der Alpha-Status ist keine Koketterie. Die README sagt es selbst: „The spec, token schema, and CLI are under active development. Expect changes to the format as it matures." Zugleich ist das Format in der Praxis erstaunlich stabil geblieben: Zwischen 0.1.0 und 0.4.0 änderte sich die Spezifikation um +23 / −1 Zeile. Inhaltlich waren es genau zwei Dinge — Farbwerte dürfen seit Juni beliebige CSS-Farbnotationen sein statt nur Hex, und es kam ein optionaler Schlüssel omitted hinzu. Die acht Sektionen und die acht Komponenten-Eigenschaften sind unverändert. Die große Bewegung lag vor dem ersten Release, in den elf Tagen zwischen Repo-Start und Veröffentlichung.

Die Trägerschaft ist gemischt, die Kontrolle nicht. 27 Menschen haben beigetragen, 20 davon mit genau einem Commit — das ist echte externe Beteiligung. Gleichzeitig stammen 37 % der Commits von erkennbar Google-zugehörigen Autoren, alle fünf Releases wurden von einem einzelnen Maintainer veröffentlicht, und jeder Beitrag setzt das Contributor License Agreement von Google voraus — eine Vereinbarung, mit der du Google die Nutzungsrechte an deinem Beitrag einräumst, während du das Urheberrecht behältst. Das ist bei Google-Projekten Standard, aber es ist eine Hürde und eine Governance-Aussage.

Die Aufmerksamkeit ist ungleich verteilt. 27.000 Sterne stehen einer bemerkenswert leisen Fachdiskussion gegenüber: Der meistbeachtete Beitrag auf Hacker News kam auf 37 Punkte und vier Kommentare, der offizielle Ankündigungs-Post auf drei. Viele Sterne, wenig Debatte — das ist ein Muster, das man kennen sollte, bevor man aus der Sternezahl auf Reife schließt.

Und ein Detail, das die Aktivität ehrlich beschreibt: Die Entwicklung läuft schubweise, nicht kontinuierlich — Spitzen an einzelnen Merge-Tagen, dazwischen Ruhe. Zum Zeitpunkt dieser Recherche lag der letzte Commit auf dem Hauptzweig rund zwei Wochen zurück, obwohl in der Zwischenzeit neue Vorgänge eingegangen waren.

Die eigentliche These: Prosa vor Tokens

Wer das Format nur als „YAML mit Kommentaren" liest, verpasst den Kern. Sechs Wochen nach der Öffnung reichte das Projekt eine PHILOSOPHY.md nach — und die dreht die naheliegende Gewichtung um:

„The quality of a generated design is determined less by the precision of its values than by how clearly the intent is described."

Und deutlicher:

„The prose is where the design lives. Everything else in the document exists to support it."

Daraus folgen drei Gedanken, die den praktischen Wert des Formats tragen.

Eine konkrete Referenz schlägt eine Adjektivliste

Das stärkste Argument des Dokuments ist ein Vergleich. „Modern, clean, trustworthy, premium" beschreibt laut PHILOSOPHY.md nichts:

„Adjectives describe a region. A specific reference describes a point."

Dagegen die Alternative:

„A design that references ‚A 1970s graduate lecture handout in the tradition of an old and established university' evokes a complete world: the one color of ink, the generous margins, the serif set at a reading size, and the absence of decoration."

Das ist unmittelbar einleuchtend, sobald man es einmal gelesen hat — und es gilt für Menschen genauso wie für Modelle. Ein Briefing aus vier Adjektiven produziert Durchschnitt, weil der Durchschnitt genau in der Mitte dessen liegt, was die vier Wörter abstecken.

Was du weglässt, definiert den Charakter

Der zweite Gedanke betrifft negative Constraints — also die Dinge, die ein Design ausdrücklich nicht tut:

„A clear design reference carries its restrictions automatically. A model knows what a lecture handout is, and it knows what a lecture handout is not. It does not glow or use a gradient. You don't have to list these. Naming the object names them, the same way naming a dog tells the model that dogs don't meow."

Daraus leitet das Dokument ein brauchbares Qualitätskriterium ab: Eine bewusst gesetzte Verbotsliste ist nützlich — eine lange, wuchernde Verbotsliste ist dagegen meist ein Symptom dafür, dass die Beschreibung zu vage war, um die Verbote von selbst zu tragen.

Der ungelöste Widerspruch — und warum ich ihn stehen lasse

Und jetzt die Stelle, an der das Projekt sich selbst widerspricht, ohne es aufzulösen.

Die README sagt: „The tokens are the normative values. The prose provides context for how to apply them." Die PHILOSOPHY.md sagt: „The prose is the most vital part of the specification" und, noch schärfer: „The token values serve as context and are not rendering instructions."

Das ist nicht dieselbe Aussage. Einmal sind die Tokens verbindlich und die Prosa erklärend, einmal ist die Prosa das Eigentliche und die Tokens nur Kontext. Das Wort „normative" kommt in der PHILOSOPHY.md kein einziges Mal vor. Weder README noch Spezifikation noch Philosophie räumen die Spannung aus.

In der Community ist das aufgefallen. In einem offenen Vorgang schreibt ein Kommentator: „That makes ‚token values serve as context, not rendering instructions' feel contradictory — that's not the nature of machine-readable tokens. We give a token to an agent, they will use it."

Ich entscheide diesen Streit hier bewusst nicht, weil beide Positionen im Projekt stehen. Für die Praxis heißt das schlicht: Behandle beide Schichten als verbindlich und halte sie synchron. Wer sich auf eine Seite verlässt, wird von der anderen überrascht.

Das lebende Beispiel

Die DESIGN.md von jpkc.com beschreibt ein dunkles, monochromes Portfolio in Schieferblau. Sie umfasst rund 35 KB in 406 Zeilen — davon 240 Zeilen Frontmatter mit 89 Tokens (30 Farben, 11 Typografie-Stufen, 5 Rundungen, 12 Abstände, 31 Komponenten) und 166 Zeilen Prosa in den acht kanonischen Sektionen. Beschrieben wird damit ein Stylesheet von rund 2.100 Zeilen.

Interessant ist weniger, was drinsteht, als was ausschließlich dort steht. Drei Beispiele aus der Datei, die in keiner Token-Datei und in keinem Figma-Dokument einen Platz hätten:

Warum die Schriftstärke 300 ist. Die Datei erklärt: „This ultra-light treatment is what makes the design feel airy and editorial despite the dark surface — it is load-bearing, not decorative." Die CSS-Variable --fw-light: 300 trägt von dieser Aussage exakt nichts. Wer sie ohne diesen Satz auf 400 hebt, „repariert" nichts, sondern zerstört den Entwurf.

Ein iOS-Druckfehler samt Ursache. Das dunkle Farbschema führte auf iPhone und iPad dazu, dass die gesamte Druckseite schwarz gerendert wurde — unlesbare PDFs, während Chrome und Firefox auf dem Desktop nie etwas zeigten. Die Datei dokumentiert die Ursache und warnt ausdrücklich, welche zwei Zeilen bei einem späteren Umbau erhalten bleiben müssen. Das ist Wissen, das sonst genau einmal existiert: im Kopf desjenigen, der den Abend mit der Fehlersuche verbracht hat.

Ein Workaround gegen ein Browser-Artefakt. Der weiche Innenschein der Hauptkarte wird auf schmalen Viewports stufenweise reduziert und unterhalb von 500 px ganz entfernt — nicht aus Geschmack, sondern weil backdrop-filter das Element in eine eigene GPU-Ebene zwingt und der breite Schein dort über den Text schmieren kann. Ohne diese Notiz sieht die Abstufung nach Inkonsequenz aus und wird beim nächsten Aufräumen „vereinheitlicht".

Genau das ist der Wert, den die PHILOSOPHY.md meint. Es ist Übergabe-Kapital: das, was beim Wechsel von Agentur, Entwickler oder Werkzeug sonst verloren geht.

Was das Werkzeug kann — und was es nur zu können scheint

Zum Format gehört ein Kommandozeilen-Werkzeug mit vier Befehlen. Ich habe alle vier gegen die lebende Datei laufen lassen.

lint — die Datei prüfen

npx @google/design.md lint DESIGN.md

Der Linter — ein Programm, das eine Datei auf Regelverstöße prüft — kennt in Version 0.4.0 elf Regeln und gibt strukturiertes JSON aus, das ein Agent direkt weiterverarbeiten kann. Auf der jpkc.com-Datei:

{ "summary": { "errors": 0, "warnings": 22, "infos": 1 } }

Von diesen elf Regeln hat allerdings genau eine die Stufe „Fehler": broken-ref, also ein Verweis auf ein Token, das es nicht gibt. Alles Inhaltliche — Kontrast, ungenutzte Tokens, Abweichung vom Code — bleibt Warnung und läuft in einer automatischen Prüfstrecke grün durch. Wer den Linter als Qualitätstor einsetzen will, muss die Warnungen selbst zu Fehlern erklären.

diff — Regressionen erkennen

Der zweite Befehl vergleicht zwei Fassungen derselben Datei. Das ist der interessanteste Teil, weil er das Design-System versionierbar im Wortsinn macht. Ich habe ihn an einer echten Änderung getestet — dazu gleich mehr — und beide Richtungen gemessen:

Fall Ergebnis Exit-Code
Echte Verbesserung (eine Kontrast-Warnung weniger) regression: false, delta.warnings: -1 0
Absichtlich kaputte Token-Referenz regression: true, delta.errors: +1 1

Der Befehl benannte dabei präzise die zwei geänderten Komponenten. Für eine automatische Prüfstrecke ist das brauchbar — mit der Einschränkung, dass diff ausschließlich DESIGN.md gegen DESIGN.md vergleicht, niemals gegen den tatsächlichen Code.

export — Tokens weitergeben

npx @google/design.md export --format css-tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md

Aus der jpkc.com-Datei entsteht so ein 83-zeiliger @theme-Block für Tailwind CSS v4 oder eine Token-Datei im DTCG-Format — dem Design-Tokens-Standard der Design Tokens Community Group beim W3C, den ich im Artikel über CSS-Cascade-Layers genauer beschrieben habe.

Zwei Einschränkungen, die man kennen muss, weil sie in der Werbung untergehen:

Die Bauform stimmt, die Namen nicht. Der Tailwind-Export liefert --color-primary, --color-brand-light und so weiter. Das produktive Stylesheet dieses Blogs führt aber --color-page, --color-accent, --color-surface-d. Ein Export würde den bestehenden Block also nicht ersetzen, sondern danebenstehen. Die Token-Namen einer gepflegten DESIGN.md sind eine handgeschriebene Übersetzungsschicht, die kein Werkzeug abbildet.

Der Export verliert genau das, was die Philosophie zum Kern erklärt. Weder der Tailwind- noch der DTCG-Export nehmen die Prosa mit — im jpkc.com-Beispiel rund 4.500 Wörter. Auch die komplette Komponenten-Schicht mit ihren 31 Einträgen bleibt zurück. Beide Exporte enthalten ausschließlich Token-Werte. Zusätzlich fällt lineHeight unterwegs weg, obwohl Tailwind dafür einen Namensraum hätte.

spec — die Spezifikation ausgeben

Der vierte Befehl gibt die Formatbeschreibung als Text aus, ausdrücklich „useful for injecting spec context into agent prompts". Das ist Autoren-Kontext, keine Design-Information: rund 15.000 Zeichen Format-Regeln, die man einem Agenten mitgeben kann, damit er eine korrekte DESIGN.md schreibt.

Der Nutzen für KI-Agenten — nüchtern betrachtet

Das ist der beworbene Kern des Formats, und hier lohnt es sich, Mechanik und Versprechen sauber zu trennen.

Was belegbar funktioniert

Die Arbeitsteilung ist sinnvoll gedacht: „Tokens give agents exact values. Prose tells them why those values exist and how to apply them." Die Spezifikation formuliert die Rolle der Overview-Prosa präzise — sie diene als Grundlage für stilistische Entscheidungen des Agenten dort, wo keine konkrete Regel oder kein Token definiert ist. Also genau für die tausend Kleinentscheidungen, die kein Design-System vorwegnimmt.

Dazu kommt die maschinenlesbare Rückmeldung: lint liefert JSON mit Pfad, Schweregrad und Meldung plus einen Exit-Code. Ein Agent kann seine eigene Arbeit also prüfen und korrigieren, statt zu raten.

Googles offizielle Positionierung im Ankündigungs-Blogpost ist entsprechend zurückhaltend formuliert: „Instead of guessing intent, AI agents can know exactly what a color is for." Das Versprechen lautet Ersatz für Raten, nicht Durchsetzung.

Was nicht funktioniert — und zwar prinzipiell

Jetzt die vier Punkte, die man vor dem Einsatz wissen sollte.

Es gibt keinen definierten Ladeweg. Weder README noch Spezifikation noch Philosophie erwähnen CLAUDE.md, AGENTS.md, .cursorrules oder vergleichbare Agent-Kontextdateien auch nur ein einziges Mal. Es gibt keine Aussage dazu, wo die Datei liegen soll oder wie ein Werkzeug sie findet. Der Maintainer bestätigt das in einem seit Mai offenen Vorgang selbst: „The spec is not opinionated currently… Firstly, we need to determine how to signal to the agent which DESIGN.md to use." Die Spezifikation definiert einen Inhalts-Standard, keinen Ladeweg.

Praktisch heißt das: Claude Code lädt eine DESIGN.md nicht von allein. Automatisch gelesen werden CLAUDE.md und verwandte Dateien; alles andere kommt nur über einen expliziten Verweis in den Kontext. Genau dieser Fall liegt in meinen eigenen Projekten vor — keine meiner Projekt-Anweisungsdateien importiert die DESIGN.md mit der dafür vorgesehenen Syntax, sie verweist nur im Fließtext darauf. Die verbreitetste Sammlung von DESIGN.md-Dateien beschreibt das Nutzungsmuster folgerichtig zweistufig und manuell: „1. Copy a site's DESIGN.md into your project root 2. Tell your AI agent to use it."

Kontext ist keine Durchsetzung. Selbst wenn die Datei im Kontext landet, ist sie eine Bitte, keine Konfiguration. Die Dokumentation von Claude Code formuliert das für ihre eigenen Kontextdateien unmissverständlich: Der Inhalt wird als Nachricht geliefert, nicht als Systemanweisung — „there's no guarantee of strict compliance". Für eine DESIGN.md gilt dasselbe.

Der Linter prüft die Prosa faktisch überhaupt nicht. Das ist der Befund, der mich am meisten überrascht hat, und er ist dreifach belegt. Das Datenmodell des Linters hält das Frontmatter und die Liste der Überschriften — kein Feld hält den Markdown-Text. Von elf Regeln greift eine einzige überhaupt auf die Sektionen zu, und die prüft nur deren Reihenfolge. Drei Gegenproben:

  1. Eine Kopie meiner DESIGN.md, in der ich in der Prosa die Kontrastwerte verfälscht („9.23 : 1" → „21.00 : 1") und eine Markenfarbe durch Magenta ersetzt habe, erzeugt eine byte-identische Lint-Ausgabe wie das Original.
  2. Selbst das Vorzeigebeispiel aus der README ist immun: alle vier Hexwerte im Text durch widersprechende ersetzt → unverändert null Fehler, null Warnungen.
  3. Ein Prosa-Verweis auf ein Token, das es gar nicht gibt, erzeugt null Meldungen.

Das ist kein Fehler, sondern die Bauform. Aber es bedeutet: Die Schicht, die laut Philosophie „das Eigentliche" ist, wird von keinem Werkzeug abgesichert.

Der Kontext kostet spürbar. Das Design-System-Team von Atlassian hat den Ansatz gegen Alternativen gemessen und im Juni 2026 veröffentlicht. Bei einer einfachen Aufgabe — ein Login-Bildschirm — brauchte die DESIGN.md-Variante rund 92 % mehr Tokens als ein Server, der Design-Wissen auf Abruf liefert, bei etwa 2,7-facher Streuung zwischen den Läufen. Die Begründung ist strukturell und im Original klar benannt: „A DESIGN.md file, by comparison, loads everything, every time." Um überhaupt auf 80 KB zu kommen, mussten sie die Nutzungshinweise ihrer über 50 Komponenten weitgehend streichen — woraufhin die Agenten anfingen, stattdessen die Komponenten-Implementierungen zu lesen, und eher dazu neigten, Komponenten neu zu bauen, statt die vorhandenen zu nutzen.

Fairerweise gehört die Selbsteinschränkung der Autoren dazu: „These results should not be seen as conclusive; this blog is not a research paper." Welches Modell zum Einsatz kam, wird nicht genannt. Als Größenordnung ist die Messung trotzdem das Belastbarste, was öffentlich vorliegt.

Ein Nachsatz mit Symbolkraft: Atlassians eigene, öffentlich verfügbare DESIGN.md fällt durch Googles eigenen Linter — 29 Fehler und 445 Warnungen. Die größte real existierende Datei dieses Formats besteht die Prüfung des Formats nicht.

Barrierefreiheit: echte Hilfe und trügerische Sicherheit

Hier liegt der praktisch greifbarste Nutzen — und zugleich das größte Missverständnis.

Was die Datei leistet

Die jpkc.com-DESIGN.md führt in ihren Do's eine Liste geprüfter Kontrastverhältnisse — das Helligkeitsverhältnis zwischen Text und Hintergrund, das die Barrierefreiheits-Richtlinien WCAG für normalen Text mit mindestens 4,5 : 1 ansetzen. Ich habe alle Werte nachgerechnet: Sie stimmen auf zwei Nachkommastellen.

Wertvoller noch ist die dokumentierte Ausnahme: Ein Token misst 2,58 : 1 und fällt damit durch. Statt es stillschweigend zu benutzen, erklärt die Datei es ausdrücklich zur rein dekorativen Farbe und verbietet es für lesbaren Text. Das ist genau die Sorte Entscheidung, die ohne Dokumentation beim nächsten Redesign versehentlich rückgängig gemacht wird.

Auch die Fokus-Regel ist wörtlich im Code eingelöst: Die Datei beschreibt eine 2 px starke Kontur mit definiertem Abstand, und exakt das steht im Stylesheet.

Der Realfall: Der Linter fand etwas Echtes

Beim Schreiben dieses Artikels habe ich das Werkzeug auf die eigene Seite losgelassen — und es meldete drei Kontrastprobleme. Eines davon war echt:

Weiß auf primary-accent (#647c8c) ergibt 4,37 : 1 und verfehlt damit die 4,5 : 1 für normalen Text. Betroffen waren die kbd-Auszeichnung für Tastenkürzel und der aktive Eintrag im Aufklappmenü. Da die Schriftgröße dort bei 87,5 % liegt, greift auch die großzügigere 3 : 1-Schwelle für großen Text nicht.

Die ehrliche Einordnung gehört dazu: Beide Regeln waren zu diesem Zeitpunkt totes CSS — die Seite rendert weder ein kbd noch das Aufklappmenü. Es war also kein aktiver Verstoß, sondern ein latenter: Er wäre in dem Moment scharf geworden, in dem jemand eines von beidem einsetzt.

Behoben ist er trotzdem — beide Stellen liegen jetzt auf einem Token mit 5,63 : 1, und die DESIGN.md wanderte im selben Zug mit: neue Do's-Regel, angepasste Farbbeschreibung, aktualisierte Komponenten-Tokens. Der diff-Befehl bestätigte anschließend delta.warnings: -1 ohne Regression. Das ist der komplette Zyklus, für den das Werkzeug gemacht ist.

Und jetzt die Grenzen — die sind erheblich

Die Kontrast-Regel des Linters ist bewusst einfach gehalten und dadurch in beide Richtungen unzuverlässig:

  • Sie kennt genau eine Schwelle: 4,5. Keine 3 : 1-Ausnahme für große Schrift, keine Prüfung für Nicht-Text-Elemente wie Icons oder Rahmen, kein AAA.
  • Sie prüft nur Paare innerhalb einer Komponente — Fließtext auf Seitenhintergrund wird nie geprüft, wenn er nicht als Komponente modelliert ist.
  • Sie rechnet ohne Alpha-Compositing, also ohne Berücksichtigung von Transparenz.

Der letzte Punkt erzeugt beide Fehlerarten, und ich habe beide gemessen:

Falscher Alarm: Eine Komponente mit backgroundColor: "transparent" wird als schwarze Fläche gerechnet und mit 2,28 : 1 gemeldet. Das ist die verbliebene Warnung auf meiner Datei — sie ist keine.

Falsche Entwarnung: Eine Komponente mit einer zu 73 % deckenden Hintergrundfarbe läuft als vollständig deckend durch die Prüfung, obwohl der real sichtbare Kontrast ein anderer ist.

Dieselbe Blindheit trifft Googles eigenes Vorzeigebeispiel: Die mitgelieferte Glas-Optik erzeugt vier Kontrastwarnungen mit dem absurden Wert „1.00:1", weil weiße Schrift auf einer zu 10 % deckenden weißen Fläche gegen deckendes Weiß gerechnet wird.

Ein offener Vorgang im Repository bringt das Problem auf den Punkt und nennt zehn weitere Lücken. Der Kernvorwurf lautet „false sense of assurance":

„A file can pass the linter with zero contrast warnings while containing combinations that fail WCAG at implementation time."

Die vier zugehörigen Verbesserungsvorschläge liegen seit Ende Juni offen und sind nicht übernommen. Dem gegenüber verspricht die README pauschal „check WCAG contrast ratios".

Mein Fazit für diesen Punkt: Eine DESIGN.md ist ein hervorragender Ort, um Barrierefreiheits-Entscheidungen festzuhalten und zu begründen. Sie ist kein Prüfwerkzeug. Wer sie dafür hält, tauscht echte Prüfung gegen ein grünes Häkchen.

Ein struktureller Nachtrag, der das unterstreicht: Ausgerechnet die beiden Farben für den Fokus-Rahmen meldet der Linter als „ungenutzt". Der Grund ist das Schema — die acht erlaubten Komponenten-Eigenschaften enthalten schlicht keine für eine Fokus-Kontur. Die für Tastaturbedienung wichtigste Eigenschaft lässt sich im maschinenlesbaren Teil gar nicht ausdrücken.

Usability, Reproduzierbarkeit, Protokollierung

Usability: Zustände werden explizit

Ein unterschätzter Effekt: 48 % der Komponenten meiner Datei sind Zustandsvarianten — 15 von 31, davon acht hover- und sieben active- oder open-Zustände. Das erzwingt eine Frage, die im Entwurf gern untergeht: Wie sieht das eigentlich aus, wenn man draufdrückt?

Ebenso wertvoll: verworfene Entscheidungen bleiben erhalten. Die Datei hält fest, der dunkle Button-Hover sei „no longer the barely-perceptible step it used to be" — und der Git-Verlauf bestätigt es: Der Wert lag früher praktisch auf der Ausgangsfarbe und wurde später bewusst auf einen deutlichen Kontrastsprung gesetzt. Ohne diesen Satz wäre die naheliegende „Korrektur" beim nächsten Aufräumen, den Sprung wieder abzuschwächen.

Reproduzierbarkeit: Werte ja, Namen nein

Der Anspruch, eine Neuimplementierung allein aus der Datei heraus zu ermöglichen, hält teilweise. Die Werte sind vollständig. Die Namen nicht: Die DESIGN.md spricht von primary, primary-dark, on-primary; das CSS heißt --color-brand, --color-brand-dark, --color-text. Identische Werte, völlig verschiedene Namensräume — und keine Zeile Werkzeug, die diese Übersetzung abbildet.

Der eigentliche Engpass liegt aber woanders: Vieles trägt nur die Prosa. Sieben verschiedene Breakpoint-Schwellen und 85 numerische rem-Angaben in 25 verschiedenen Werten stehen ausschließlich im Fließtext. Das Format sieht für Breakpoints keine Kategorie vor — es verbietet sie aber auch nicht, denn eigene Sektionen und Schlüssel sind ausdrücklich erlaubt.

Ein hübsches Detail am Rande, das zeigt, wie genau man hinsehen muss: Die Umrechnung von Transparenzwerten in achtstellige Hexcodes ist auf 8 Bit gerundet, nicht exakt. #ffffff40 bedeutet 0,2510 statt 0,25. Für die Darstellung irrelevant, für einen Generator nicht.

Protokollierung: der Nutzen, der sich still aufbaut

Hier liegt der Vorteil, den man erst nach Monaten bemerkt. Die DESIGN.md der Hauptseite wurde seit Mai in 13 Commits angefasst — und mehrere tragen den Zweck im Titel: „.btn-outline :active states + DESIGN.md sync", „a11y for sticky .navBar … + DESIGN.md sync", „docs: Print-Stylesheet in DESIGN.md aktualisieren, iOS color-scheme-Gotcha dokumentieren". In der Woche vor dieser Recherche wurde die Datei dreimal berührt, jedes Mal gemeinsam mit dem Stylesheet.

Das erzeugt etwas, das ein Figma-Kommentar nicht kann: eine durchsuchbare, datierte Begründungshistorie. Warum ist der Navbar-Hintergrund heute deckend statt durchscheinend? Die Datei bewahrt die Begründung des Rückbaus — und der Commit dazu zeigt, wann und mit welcher CSS-Änderung er passierte.

Drei ehrliche Einschränkungen dazu:

Nichts davon ist erzwungen. Kein Hook, keine automatische Prüfung, kein Zwang. Die Praxis beruht allein auf einer Konvention — und die steht nicht einmal in der DESIGN.md selbst, sondern in der Projektanweisung daneben.

Die Konvention widerspricht sich zwischen meinen eigenen Projekten. Das Hauptprojekt verlangt „zuerst DESIGN.md, dann CSS". Dieses Blog-Projekt verlangt das Gegenteil: den Tailwind-@theme-Block als Quelle der Wahrheit behandeln und die Begründung anschließend spiegeln. Beides ist vertretbar, aber es zeigt, dass die Richtung eine Projektentscheidung ist, die das Format nicht vorgibt — und die man besser einmal bewusst trifft.

Die Datei ist kein Build-Bestandteil. Sie nennt sich selbst „a documentary specification"; weder die Eleventy-Konfiguration noch die package.json referenzieren sie. Sie wirkt ausschließlich über Menschen und Agenten, die sie lesen.

Verhältnis zum klassischen Styleguide

Eine DESIGN.md ersetzt keine Pattern-Library, und zwar aus einem simplen Grund: Es wird nichts gerendert. Meine Datei enthält null Code-Blöcke, kein HTML, keine Komponentenvorschau, keine Zustandsdemo. Wer sehen will, wie der Button aussieht, muss die Seite aufrufen.

Umgekehrt erfasst sie, was eine generische Pattern-Library nicht kennt: projektspezifische Marken-Signaturen. Etwa den Dateinamen-Tag am unteren Rand der Hauptkarte, der die IDE-Metapher trägt und ausdrücklich „should not be removed" ist. Oder die drei Fensterpunkte in der Navigationsleiste, die zugleich ein Zurück-zur-Startseite-Link mit definierter Klickfläche und Fokus-Rahmen sind.

Die beiden Formen ergänzen sich also: Pattern-Library zeigt, DESIGN.md begründet.

Zwei Beobachtungen aus der Praxis:

Die Sektionen sind frei erweiterbar — die Philosophie sagt es ausdrücklich zu. Die DESIGN.md dieses Blogs nutzt drei kanonische und fünf eigene Sektionen, darunter eine ## Implementation map, die jedes Design-Anliegen genau einer CSS-Datei und der nötigen Änderung zuordnet. Der Linter beschwert sich darüber nicht.

Es gibt Scope-Creep, und der ist verräterisch. Meine Datei enthält inzwischen eine reine Redaktionsregel: Sie verbietet den Halbgeviertstrich in Komposita. Das hat mit visuellem Design nichts mehr zu tun. Wenn eine Datei zur zentralen Sammelstelle für „Dinge, an die sich alle halten sollen" wird, ist das ein Zeichen dafür, dass sie funktioniert — und zugleich der Punkt, an dem man aufpassen muss, dass sie nicht zum Sammelbecken wird.

Integration in Stacks und CMS

Eleventy und Tailwind CSS v4

Eleventy gibt keine Style-Schicht vor — die Token-Anbindung ist dort eine reine CSS-Entscheidung. Tailwind v4 ist der einzige direkt bediente Stack: export --format css-tailwind erzeugt einen @theme-Block, den Tailwind unmittelbar versteht.

Mit der oben genannten Einschränkung: Die Bauform passt, die Namen nicht. Der Export stellt sich neben deinen bestehenden Block, statt ihn zu ersetzen. Realistisch ist er damit ein Startpunkt für ein neues Projekt, nicht ein Synchronisierungsmechanismus für ein bestehendes.

WordPress-Themes und theme.json

Für WordPress ist die Frage besonders interessant, weil Block-Themes mit theme.json bereits ein eigenes, gut ausgebautes Token-System haben. Ich habe geprüft, wie weit die Analogie trägt.

Wie theme.json funktioniert. In der aktuellen WordPress-Generation ist die Schemaversion 3 — unverändert seit WordPress 6.6. Die Datei kennt elf Schlüssel auf oberster Ebene; die beiden wichtigen sind settings (was einstellbar ist) und styles (was gilt). Aus settings erzeugt WordPress automatisch CSS-Custom-Properties nach einem festen Schema, zum Beispiel:

settings.color.palette      →  --wp--preset--color--<slug>
settings.spacing.spacingSizes →  --wp--preset--spacing--<slug>
settings.typography.fontSizes →  --wp--preset--font-size--<slug>
settings.custom.<key>       →  --wp--custom--<key>

Es gibt insgesamt zehn solcher Preset-Kategorien. Ein Farbeintrag erzeugt zusätzlich drei nutzbare Klassen (.has-<slug>-color, .has-<slug>-background-color, .has-<slug>-border-color).

Was sich sauber abbilden lässt. Ich habe den Test gemacht: Aus dem DTCG-Export meiner DESIGN.md lässt sich per kleinem Mapping-Skript eine schema-valide theme.json erzeugen — 30 Farben in die Palette, 12 Abstände in spacingSizes, 5 Rundungen in radiusSizes, 11 Typografie-Stufen in fontSizes plus zwei Schriftfamilien. Die Validierung gegen das offizielle WordPress-Schema läuft durch.

Wo die Analogie endet — und das ist der wichtigere Teil:

  • Die 31 Komponenten-Einträge haben keinerlei Entsprechung. theme.json kennt styles.blocks für über hundert Core-Blöcke und styles.elements für gut ein Dutzend Elementtypen — aber das ist eine völlig andere Achse als „Button im Ruhezustand, im Hover, gedrückt".
  • Typografie geht nur teilweise mit. In theme.json sind ausschließlich fontSizes und fontFamilies echte Preset-Listen. fontWeight, lineHeight und letterSpacing sind dort Boolesche Schalter, die lediglich Bedienelemente im Editor freischalten — sie speichern keine Werte und erzeugen keine Custom Properties. Aus meiner Datei bleiben dadurch je nach Zählweise 12 bis 23 Typografie-Angaben ohne Ablageort.
  • Die Slug-Konventionen beißen sich. WordPress empfiehlt für Abstände numerische Kürzel (10, 20, … 50 als Mitte), damit sie sich mit den Vorgaben mischen und sortieren lassen. Meine Abstände heißen xs, sm, md, page-padding-x — keiner beginnt mit einer Ziffer.
  • Der --prefix-Schalter des Exports hilft nicht. Ein Versuch mit dem WordPress-Präfix erzeugt --wp--preset---color-primary statt --wp--preset--color--primary.

Und es gibt kein Werkzeug, das die Lücke schließt. Style Dictionary hat kein WordPress-Format. Eine Repository-Suche nach Konvertern liefert eine Handvoll Projekte, das größte mit 39 Sternen. Das einzige auf npm auffindbare theme.json-Ausgabemodul aus einem Token-System liest kein DTCG, sondern ein hauseigenes Format. Und das einzige DESIGN.md-Werkzeug mit WordPress-Bezug arbeitet in die Gegenrichtung: Es erzeugt eine DESIGN.md aus einer theme.json.

Für klassische Themes ohne Block-Editor gilt: theme.json ist dort seit WordPress 5.8 nutzbar, aber im Wesentlichen für den settings-Teil — Palette, Schriftgrößen, Abstände. Die entsprechenden add_theme_support()-Aufrufe entfallen dann.

Meine Empfehlung für WordPress: DESIGN.md als Begründungsebene führen, theme.json als technische Umsetzung, und die Abbildung als bewusst gepflegtes, kleines Skript verstehen — nicht als Werkzeug, das es fertig zu kaufen gäbe. Der Nutzen liegt dann in der Prosa und in der Nachvollziehbarkeit, nicht in der Automatisierung.

Andere Systeme, kurz und belegt

  • Drupal hat bis heute keine Design-Token-Schnittstelle im Kern. Ein umfangreicher Core-Vorgang dafür ist offen, geplant sind DTCG-Format und CSS-Variablen zur Laufzeit — der Stand ist „Needs work".
  • Shopware 6 besitzt eine namensgleiche, aber inhaltlich unverwandte theme.json. Dort definieren config.fields typisierte Felder (Farbe, Text, Zahl, Schriftfamilie, Medien), die zu SCSS-Variablen und zu Eingabefeldern in der Administration werden. Das ist ein Theme-Konfigurationssystem, kein Token-Format — die Ähnlichkeit ist rein zufällig und eine echte Verwechslungsgefahr.
  • TYPO3 v13 kennt kein Design-Token-Konzept. Site Sets und Site Settings sind der Nachfolger der TypoScript-Konstanten; CSS-Custom-Properties entstehen daraus von selbst nicht.

Die realistische Integrationsstufe

Zusammengefasst: Das Werkzeug kann heute validieren, vergleichen und exportieren — mehr nicht. Es gibt keinen Import, keinen Beobachtungsmodus, keinen CMS-Befehl. Eine automatische Prüfstrecke ist damit ausschließlich für die DESIGN.md selbst möglich. Der Weg in den Stack ist einseitig und für alles außer Tailwind v4 selbst zu schreiben.

Nachteile — sortiert nach Art

Nicht jeder Kritikpunkt wiegt gleich. Ich sortiere in drei Kategorien, weil das die Entscheidung erleichtert.

Strukturelle Nachteile — die bleiben

Prosa und Tokens sind gegeneinander nicht prüfbar. Der wichtigste Punkt, oben belegt. Beide Schichten können auseinanderlaufen, ohne dass irgendetwas anschlägt.

Doppelpflege ist real und im Projekt selbst als offener Vorgang dokumentiert. Ein Vorgang mit dem Titel „Duplicating design facts in front matter and markdown body" wurde am Tag der ersten Veröffentlichung eröffnet und ist bis heute offen. Das Beispiel darin: Das YAML sagt eine Farbe, die Prosa eine andere — „the document still looks authoritative, but now contains two versions of the truth."

Und genau das ist mir passiert. In meiner eigenen Datei deklarieren fünf Komponenten padding: 0.475rem; das produktive CSS setzt padding: .475rem .9rem, und die Prosa derselben Datei nennt korrekt beide Werte. Der maschinenlesbare Teil ist der falsche — und der Linter meldet nichts, weil er den Code nie sieht. Fairerweise: Der korrekte Wert wäre erlaubt gewesen, der Fehler war nicht erzwungen.

Die orphaned-tokens-Regel ist auf Material Design 3 zugeschnitten. Sie meldet 21 von 30 Farben meiner Palette als „ungenutzt" — 20 davon zu Unrecht, denn die Werte sind im CSS in Verwendung. Der Mechanismus erklärt es: Die Regel zählt nur Referenzen aus dem components-Block und kennt zusätzlich eine Positivliste mit genau sieben Material-Design-Familiennamen. Wer eigene Namen wählt, wird bestraft. Der Quellcode-Kommentar sagt es selbst: „Custom tokens … still get flagged when unused."

Am Repository lässt sich das schön zeigen: Alle drei offiziellen Beispiele erzeugen null solcher Warnungen. Benennt man in einem davon zwei Tokens auf projekteigene Namen um, erscheinen sofort zwei Warnungen. Und die Regel lässt sich vollständig abschalten, indem man den components-Block weglässt — je gründlicher du pflegst, desto lauter wird der Linter.

Harte Formatgrenzen. Es gibt kein Light/Dark und kein Multi-Theme (offener Vorgang seit April, vom Maintainer als „at the top of the list" bezeichnet), keine strukturierten Schatten-Tokens trotz einer Sektion „Elevation & Depth", keine Motion-Tokens, keine Icon-Sektion, und als Einheiten nur px, em, rem. Meine Umgehung — Schatten- und Fokusfarben als gewöhnliche Farbtokens abzulegen — führt prompt dazu, dass alle sieben in der Orphan-Liste landen. Das Laufzeit-Light-Theme meiner Seite existiert im Frontmatter überhaupt nicht, nur in der Prosa.

Es gibt keine Möglichkeit, Meldungen zu unterdrücken. Keine Konfigurationsdatei, kein --disable-rule, keine Inline-Kommentare. Der einzige Schalter betrifft ausschließlich fehlende Sektionen.

Alpha-Kinderkrankheiten — die vergehen

Diese Kategorie ist ärgerlich, aber nicht strukturell:

  • Version 0.3.0 wurde mit komplett kaputtem spec-Befehl ausgeliefert — 42 Tage lang, bis 0.4.0 den Pfadfehler behob.
  • Ein CLI-Upgrade allein ließ den Warnungsstand einer unveränderten Datei um den Faktor 7 springen: dieselbe Datei ergab unter 0.3.0 noch 31 Warnungen, unter 0.4.0 dann 228.
  • 196 dieser 228 Warnungen entstanden aus zwei Zeilen — eine Warnung pro Zeichen, weil ein Schriftstapel als Zeichenkette statt als Objekt notiert war und der Linter über die Zeichen iterierte. Nach der Korrektur blieben 32. Das eigentliche Signal war darin schlicht untergegangen.
  • Ein unitloses lineHeight: 1.5 — die Form, die die Spezifikation ausdrücklich empfiehlt — wird von beiden Exporten kommentarlos verworfen. In Anführungszeichen gesetzt überlebt derselbe Wert.
  • Die README hinkte der Regelzahl monatelang hinterher, und ein Exportformat fehlt in der Formattabelle bis heute.

Missverständnisse — die man sich selbst zuschreiben muss

  • „DESIGN.md ersetzt die Token-Pipeline." Nein. Die CLI kann exportieren, nicht importieren. Das Format sitzt vor DTCG, Style Dictionary und Figma, nicht an deren Stelle — und die Philosophie sagt genau das: man wolle nicht „reinvent the decades long work established by languages and tools that came before us."
  • „Der Linter validiert das Design-System." Er validiert die Datei. Kein Befehl liest jemals Anwendungscode. Eine Regel wie „Don't use a webfont" ist prinzipiell nicht prüfbar.
  • „Der Agent lädt das automatisch." Es gibt keinen definierten Ladeweg, und Kontext ist keine Durchsetzung.
  • „Vendor-Lock-in." Der ist tatsächlich gering: Markdown mit YAML, keine proprietäre Komponente, Apache-2.0, ein einziges Paket mit vier Befehlen. Selbst wenn das Projekt morgen eingestellt würde, bliebe die Datei lesbar und der Export nach DTCG vorhanden.
  • „Kein Renderer ist ein Mangel." Nein, das ist erklärte Absicht.

Der prägnanteste Einwand kam aus der Fachdiskussion — und er trifft einen wunden Punkt:

„My first reaction is that everything I see defined here in DESIGN.md is already codified in my actual themes configs, or component files."

Das stimmt — für den Token-Teil. Für die 4.500 Wörter Begründung stimmt es nicht: Die haben in keiner Theme-Konfiguration einen Ort.

Vier Perspektiven

Dieselbe Datei sieht aus vier Blickwinkeln unterschiedlich aus. Das ist keine Fleißaufgabe — wer sie einführen will, muss vier verschiedene Fragen beantworten.

Entwicklerin und Entwickler

Was du gewinnst: Regeln mit direktem Code-Bezug statt Absichtserklärungen. Die Fokus-Regel meiner Datei steht wörtlich so im Stylesheet. Die ## Implementation map des Blog-Projekts ordnet jedes Anliegen genau einer Datei zu. Dazu Übergabewissen, das sonst nirgends steht — der iOS-Druckfehler, der Compositing-Workaround. Und ein maschinenlesbares Tor für eine Fehlerklasse: kaputte Referenzen und Parse-Fehler brechen mit Exit-Code 1.

Was es kostet: Doppelpflege. Meine Datei wurde in einer Woche dreimal angefasst, jedes Mal zusammen mit dem CSS. 89 Tokens plus 166 Zeilen Prosa neben rund 2.100 Zeilen Stylesheet. Die Namensübersetzung machst du von Hand.

Woran du es merkst: Der Linter ist grün, während der maschinenlesbare Teil falsch ist. Ein Werkzeug-Update lässt eine unveränderte Datei von 31 auf 228 Warnungen springen. Ein Export läuft durch, ersetzt aber nichts.

Designerin und Designer

Was du gewinnst: Deine Begründungen überleben. „Schriftstärke 300 ist tragend, nicht dekorativ" ist eine Aussage, die keine Variable transportiert. Verbote bekommen benannte Ausnahmen statt Grauzonen. Zustände werden systematisch mitgedacht — knapp die Hälfte der Komponenten sind Zustandsvarianten.

Was es kostet: Enge Leitplanken, teils weit über Farbe hinaus — keine zusätzlichen Grid-Abstraktionen, maximal drei Verschachtelungsebenen im CSS, kein Framework. Und das Format kennt kein Light/Dark, keine Schatten-, Motion- oder Icon-Tokens.

Woran du es merkst: Der Weg zu Figma ist Einbahnstraße und lückenhaft. Der DTCG-Export trägt nur Farben, Abstände, Rundungen und Typografie — keine Komponenten, keine Prosa, kein lineHeight. Und ein Wert wie system-ui, der in zehn von elf Typografie-Stufen steht, ist ein 16-teiliger Fallback-Stapel, der sich in einem Design-Werkzeug nicht sinnvoll auflösen lässt.

Kundenberatung und Projektbetreuung

Was du gewinnst: fertige Scope-Einordnungen, die du zitieren kannst. „Adding @font-face is a substantive change, not a styling choice" beendet eine Diskussion darüber, ob eine neue Hausschrift „nur eine Kleinigkeit" ist. Und du kannst am Realfall zeigen, dass Sonderwünsche im System gelöst werden können: Der Bedarf nach einem hervorgehobenen Navigations-Button wurde als neue Button-Variante umgesetzt — DESIGN.md und CSS im selben Commit, Kontrast nachgerechnet, Monochromie-Regel unverletzt.

Was es kostet: Die Datei trifft keine Aufwandsaussage. Keine Stunden, keine Tage, keine Aufwandsklasse. Sie klassifiziert die Art der Änderung, nicht ihren Preis. Und die Governance — wer wann was zuerst ändert — steht nicht in der DESIGN.md, ist nicht erzwungen und war in meinen beiden Projekten sogar gegenläufig definiert.

Woran du es merkst: Du kannst „ist im System vorgesehen" gegen „ist ein Sonderwunsch" belegen statt behaupten. Für „wie lange dauert das" liefert die Datei nichts.

Eine ehrliche Einschränkung zu meinem Beispiel: jpkc.com ist meine eigene Seite. Der Button-Fall war eine Eigenanforderung, kein Kundenwunsch eines Dritten. Die Mechanik ist übertragbar, die Konfliktdynamik einer echten Kundenbeziehung bildet er nicht ab.

Kundin und Kunde

Was du gewinnst: Unabhängigkeit. Dein Design-System liegt als lesbare Textdatei in deinem eigenen Repository — 30 Farben, 11 Typografie-Stufen, 12 Abstände, 5 Rundungen, 31 Komponenten im Klartext, ohne dass du ein Werkzeug oder ein Abonnement brauchst. Das Format ist Apache-lizenziert, das Werkzeug ein einziges Paket. Ein Wechsel von Agentur oder Werkzeug kostet dich die Werte nicht.

Dazu kommt Markenkonsistenz über Projektgrenzen: Mein Blog-Projekt erbt den Ton der Hauptseite und benennt seine drei bewussten Abweichungen namentlich, statt sie stillschweigend zu vollziehen.

Was es kostet: Die Substanz liegt in der Prosa — und kein Exporter nimmt sie mit. Der Wert steckt im gepflegten Text, nicht im Werkzeug. Und die Doppelpflege bezahlst du als laufende Position.

Woran du es merkst: Bei einem Wechsel gehen dir nicht die Farbwerte verloren, sondern die Erklärung — genau das, was die Philosophie des Formats als Kern bezeichnet. Und: Der Kontrastfehler, den die Prosa bis dahin nicht beziffert hatte, wurde gefunden und behoben. Beides ist im Git nachlesbar. Das ist die Sorte Nachvollziehbarkeit, die man erst schätzt, wenn man sie einmal gebraucht hat.

Wann lohnt sich das — und wann nicht

Es lohnt sich, wenn:

  • Du regelmäßig mit Coding-Agenten arbeitest und es leid bist, dieselben Design-Entscheidungen in jeder Sitzung neu zu erklären.
  • Dein Projekt länger lebt als dein Gedächtnis — also praktisch immer.
  • Mehrere Menschen oder mehrere Schwesterprojekte dieselbe Marke tragen.
  • Du Design-Entscheidungen gegenüber Dritten begründen musst.
  • Barrierefreiheits-Entscheidungen dokumentiert werden sollen, damit sie nicht versehentlich zurückgedreht werden.

Es lohnt sich eher nicht, wenn:

  • Das Projekt klein ist und eine Person es allein trägt. Dann ist die Doppelpflege teurer als der Nutzen.
  • Du ein etabliertes Design-System mit einer funktionierenden Token-Pipeline hast. Dann ist der Token-Teil Dopplung — und du solltest, wenn überhaupt, nur die Prosa-Schicht übernehmen.
  • Du dir davon eine Barrierefreiheits-Prüfung erhoffst. Dafür ist es nicht gebaut.
  • Du sehr große Design-Systeme an Agenten übergeben willst. Ab einer gewissen Größe kippt der Kontextvorteil, wie Atlassians Messung zeigt.

Ein pragmatischer Mittelweg, den ich für die meisten Projekte empfehlen würde: Fang mit der Prosa an. Overview, Colors, Do's and Don'ts. Die Tokens kannst du später ergänzen — oder auch gar nicht, wenn deine Werte ohnehin schon in einer Token-Pipeline leben. Die Begründungsschicht ist der Teil, der nirgends sonst existiert; der Werteteil ist der, den du vermutlich schon hast.

Glossar

Begriffe, die im Text vorkommen und dort den Satz überladen hätten.

Begriff Bedeutung
Alpha-Compositing Die Berechnung, welche Farbe tatsächlich sichtbar wird, wenn eine teildurchsichtige Fläche über einer anderen liegt.
CLA (Contributor License Agreement) Vereinbarung, mit der du einem Projektträger die Nutzungsrechte an deinem Beitrag einräumst; das Urheberrecht bleibt bei dir.
DTCG Design Tokens Community Group beim W3C — die Gruppe hinter dem herstellerneutralen Standardformat für Design-Tokens.
Exit-Code Rückgabewert eines Kommandozeilen-Programms. 0 heißt Erfolg, alles andere Fehler — daran erkennt eine automatische Prüfstrecke, ob sie abbrechen soll.
Frontmatter Ein Metadaten-Block am Dateianfang, hier in YAML und von ----Zeilen eingefasst.
Linter Programm, das eine Datei auf Regelverstöße prüft, ohne sie auszuführen.
Material Design 3 Googles Design-System; seine Token-Namen (primary, surface, on-primary …) prägen die Voreinstellungen des Linters.
Pattern-Library Sammlung gerenderter Komponenten mit ihren Zuständen — zeigt, wie etwas aussieht, statt es zu beschreiben.
Preset (WordPress) Vordefinierter Wert in theme.json, aus dem WordPress automatisch eine CSS-Variable und Hilfsklassen erzeugt.
Slug Kurzer, technischer Bezeichner ohne Sonderzeichen, der in Klassennamen und Variablennamen einfließt.
WCAG Web Content Accessibility Guidelines — der internationale Standard für barrierefreie Webinhalte; Stufe AA verlangt 4,5 : 1 Kontrast für normalen Text.

Fazit

DESIGN.md ist ein gutes Format mit einem überzogenen Versprechen und einem schwachen Werkzeug — und trotzdem würde ich es wieder einführen.

Gut ist die Grundidee: Design-Entscheidungen dorthin schreiben, wo der Code liegt, in einer Form, die Mensch und Maschine gleichermaßen lesen. Die These aus der Philosophie — eine konkrete Referenz trägt mehr als eine Adjektivliste — ist die beste Kurzfassung guter Design-Kommunikation, die ich seit Langem gelesen habe.

Überzogen ist das Versprechen rund um KI und Barrierefreiheit. Es gibt keinen definierten Ladeweg, Kontext ist keine Durchsetzung, und die Kontrastprüfung ist so vereinfacht, dass sie in beide Richtungen irrt. Wer „check WCAG contrast ratios" wörtlich nimmt, kauft sich ein grünes Häkchen statt einer Prüfung.

Schwach ist das Werkzeug an genau der Stelle, die das Projekt selbst zum Kern erklärt: Die Prosa wird von keiner einzigen Regel angefasst. Man kann sämtliche Begründungen in Unsinn verwandeln, ohne dass der Linter zuckt.

Drei Dinge nehme ich aus der Arbeit an diesem Artikel mit:

  1. Der Wert liegt in der Prosa, nicht im Werkzeug. Was mir meine Datei tatsächlich zurückgegeben hat, war nie eine Lint-Meldung, sondern der Satz über den iOS-Druckfehler und die Begründung der Schriftstärke 300.
  2. Der Linter ist ein Rauchmelder, kein Brandschutzgutachten. Er hat auf meiner eigenen Seite ein echtes Kontrastproblem gefunden, das ich übersehen hatte — und gleichzeitig 20 von 21 „ungenutzten" Farben falsch gemeldet. Beides gehört zur Wahrheit.
  3. Die Doppelpflege ist der Preis, und er ist real. Dreimal in einer Woche dieselbe Datei anfassen ist kein Nebeneffekt, sondern die Eintrittskarte. Wer ihn nicht zahlen will, sollte nur die Prosa führen.

Wenn du eine eigene DESIGN.md anlegen willst: Fang nicht mit den Farben an, sondern mit dem Satz, den niemand sonst aufschreiben würde — der Begründung, warum dein Design so aussieht und nicht anders. Die Werte findest du später ohnehin im CSS.

Aus diesem Blog: