Design Tokens vs. Styleguide

Das neue Markenportal wurde unter Applaus veröffentlicht: jede Farbe als großzügige Farbfläche dargestellt, hex-Codes in den Bildunterschriften gesetzt, Abstandsdiagramme, eine Seite pro Komponente. Innerhalb eines Jahres war es klammheimlich falsch. Ein Kontrast-Fix hatte das Markenblau im Code verschoben; das Portal zeigte weiterhin den alten Wert; und die Designer hatten gelernt, stattdessen die Farbe mit der Pipette vom neuesten Production-Screen abzugreifen. Die sorgfältigste Dokumentation im Unternehmen war zur am wenigsten vertrauten geworden.

Ein Styleguide und Design Tokens dokumentieren zwei verschiedene Hälften eines Systems: Der Styleguide trägt Absicht und Verwendung für Menschen — wann welche Überschriftenebene gilt, wie die Stimme klingt, wie ein Don’t aussieht — während Tokens die Werte für Maschinen tragen, als benannte Einträge, die ein Build-Schritt direkt liest. Sie spielen per Referenz zusammen: Der moderne Guide benennt Tokens (accent, space-4), statt ihre Werte einzubetten, und kann deshalb nicht so veralten wie jenes Portal. Dieser Artikel nimmt die Perspektive der Dokumentations-Architektur ein; die Token-Grundlagen findest du in unserem Design-Tokens-Leitfaden. (Falls die Begriffe verschwimmen: Ein Design System ist der Überbau, und der Styleguide und die Token-Datei sind zwei seiner Schichten — in diesem Text geht es darum, wie sich diese beiden die Arbeit teilen.)

Was leistet ein Styleguide, das Tokens nicht können?

Ein Styleguide ist eine Sammlung von Standards dafür, wie Dinge gestaltet und geschrieben werden, und sein unersetzlicher Inhalt ist Urteilsvermögen, nicht Zahlen. Wann welche Überschriftenebene zu verwenden ist und warum es schadet, eine zu überspringen. Wie sich die Fotografie anfühlen soll, gezeigt als gutes und schlechtes Beispiel nebeneinander. Warum die Akzentfarbe Aktionen vorbehalten ist, samt der Begründung aus Sicht der Barrierefreiheit, welche Kombinationen erlaubt sind. Wie die Marke klingt — mit dem Satz, den sie sagen würde, und dem Satz, den sie nicht sagen würde.

Nichts davon passt in ein Token-Schema. Ein Token kann festhalten, dass text-primary ein bestimmtes Fast-Schwarz ist; es kann nicht erklären, was als primärer Text zählt, oder ein Don’t-Beispiel enthalten — was zu den informationsdichtesten Formen von Design-Dokumentation gehört und kein Token-Äquivalent hat. Das ist die eigentliche Aufgabe des Styleguides, und Tokenisierung rührt sie nicht an. Was stirbt, ist nur die andere Gewohnheit des Guides: Werte zu tragen.

Was halten Design Tokens fest, das ein Styleguide nicht kann?

Die exakten Antworten. brand-600 ist ein bestimmtes Blau — #2563eb, also oklch(0.546 0.215 262.9) — einmal gespeichert, in einer Datei, die Figma, ein Stylesheet-Build und eine native App ohne Menschen dazwischen lesen. Ein Guide kann nur ein Bild dieses Wertes zeigen und hoffen, dass jeder Leser ihn getreu herauszieht; das Token ist der Wert, ohne Rendering-Schritt, den es überstehen müsste, und ohne Leser, der es annähern müsste.

Wie wurden Styleguides “living”, und warum reichte das nicht?

Die Geschichte verläuft in drei Generationen. Die erste war statisch: gedruckte Handbücher, dann PDFs und Webseiten, mit Werten, die in Farbflächen und Bildunterschriften gemalt wurden — Kopien vom Tag ihrer Veröffentlichung. Die zweite, der Living Styleguide, generierte seine Seiten aus dem Production-Code, sodass die Farbflächen zeigten, was tatsächlich ausgeliefert wurde — aber er war weiterhin nur lesend: ein Spiegel der Werte statt einer Quelle für sie, wahr, solange man hinsah, ohne Autorität über die nächste Änderung. Die dritte Form kehrt das Verhältnis um: Die Dokumentation referenziert Tokens per Namen, die Token-Datei besitzt die Werte, und andere Artefakte — einschließlich der eigenen Farbflächen des Guides — werden daraus gerendert. Ein so gebauter Guide kann nicht über Werte lügen, weil er keine trägt.

Warum verrotten dokumentierte Werte?

Weil jeder Wert, den ein Dokument einbettet, eine Kopie ist, und Kopien, die von verschiedenen Händen gepflegt werden, driften auseinander — derselbe Ein-Satz-Mechanismus, der hinter den meisten Geschichten von Design-gegen-Code-Drift steckt. Ein Guide, der #2563EB sagt, ist korrekt bis zur ersten Nachjustierung irgendwo sonst im System; ein Guide, der brand-600 sagt, bleibt durch jede Nachjustierung korrekt, weil er eine Beziehung angibt statt einer Momentaufnahme. Die intuitive Fassung: Eine Kopie kann veraltet sein, ein Zeiger nicht. Den Leser eine Sache nachschlagen zu lassen, ist der Preis dafür, ihm nie etwas Falsches zu sagen.

Wie sieht dieselbe Button-Dokumentation in beiden Varianten aus?

Werte-eingebettet, so wie es das Portal der ersten Generation schrieb:

Primäre Buttons verwenden das Markenblau (#2563EB) als Hintergrund, mit weißem Text, 16px seitlichem Padding und 6px Eckenradius.

Token-referenziert:

Primäre Buttons verwenden accent als Hintergrund, mit on-accent-Text, space-3 seitlichem Padding und radius-sm-Ecken. Verwende einen pro Ansicht, für die Hauptaktion der Seite; alles andere bekommt einen sekundären Button. Die aktuellen Werte leben in der Token-Datei.

Jetzt lass ein Rebranding durch beide laufen. Die Palette wird neu aus einer petrolfarbenen Ausgangsfarbe abgeleitet: brand-600 behält seinen Namen und speichert einen neuen Wert, und accent — die Rolle, die die Button-Dokumentation benennt — zeigt weiterhin darauf. Der token-referenzierte Absatz bleibt unangetastet und weiterhin wahr. Der werte-eingebettete Absatz gibt jetzt einen falschen hex-Wert an — und seine drei anderen eingebetteten Werte (weiß, 16px, 6px) sind separate Risiken, jedes wartet auf seine eigene Nachjustierung. Beachte auch, wofür die Token-Variante Platz gewonnen hat: befreit davon, Werte zu tragen, verbringt sie ihre Länge mit Verwendung — einer pro Ansicht — was der Inhalt ist, für den ein Guide existiert.

Öffne die Rollen, die diese Dokumentation benennt, in Scale Composer — die semantische Ebene mit accent, on-accent und den übrigen abgeleiteten Rollen neben ihren aktuellen Werten und den Kontrast-Untergrenzen, gegen die jede Kombination geprüft wird. Das ist die Hälfte des Paars, auf die ein token-referenzierter Guide zeigt: Justiere die Ausgangsfarbe neu, und die Namen halten, während die Werte anders antworten.

Wie spielen Tokens, Dokumentation und Beispiele zusammen?

Als Trio mit einer einzigen Referenzrichtung. Die Token-Datei hält die Werte. Der Styleguide hält Absicht und Verwendung und benennt Tokens überall dort, wo ein Wert gemeint ist. Live-Beispiele — gerenderte Komponenten, Farbflächen-Seiten, Beispieltext — werden aus der Token-Datei generiert, sodass selbst die Bilder Ansichten der Quelle sind statt Konkurrenten zu ihr. Jedes Artefakt erledigt die eine Aufgabe, für die es strukturell geeignet ist: Prosa überträgt Urteilsvermögen, Tokens übertragen Werte, und gerenderte Beispiele übertragen die Gestalt, die weder Prosa noch JSON übertragen können. Teams fahren das Trio manchmal als Paar — Tokens plus einen referenzierenden Guide, Beispiele zurückgestellt — und das funktioniert; der Kollaps auf ein einziges Artefakt ist die Anordnung, die scheitert, welches auch immer behalten wird.

Schreibe einen Absatz deines Guides um

Die Verschiebung lässt sich am einfachsten an einem einzelnen Absatz beurteilen. Nimm eine werte-tragende Regel aus deinem aktuellen Guide — die Button-Spezifikation oben ist eine Vorlage — und schreibe sie so um, dass sie Rollen benennt, statt Zahlen einzubetten. Generiere das Token-Set, auf das dein Guide verweisen soll — seed es mit deiner Markenfarbe, lass die abgeleiteten Rollen zu den Namen werden, auf die deine Dokumentation zeigt, und exportiere die Datei, damit die Werte des Guides ein Zuhause haben, das nicht der Guide selbst ist.