Token-Änderungen in Git prüfen

Die Akzentfarbe änderte sich an einem Dienstag, und niemand hatte das entschieden. Der Pull Request trug den Titel „regenerate tokens after spacing fix”; die Token-Datei zeigte einundvierzig geänderte Zeilen, von denen eine accent von brand-600 auf secondary-500 umbog. Der Reviewer sah eine generierte Datei und einen grünen Build und gab frei. Drei Wochen später fragte das Marketing, warum die Signup-Buttons auf den neuen Screenshots eine andere Farbe hatten. git log -p fand die Zeile in etwa einer Minute — was die bittere Pointe der Geschichte ist: die Historie war perfekt, und die Prüfung, die sie ermöglichen soll, hätte zehn Sekunden gedauert, die sich niemand nahm.

Design Tokens gehören unter Versionskontrolle, weil sie Design- Entscheidungen sich wie Code verhalten lassen: die Historie hält fest, wer die Akzentfarbe geändert hat, wann und — in der Commit-Nachricht — warum; ein Pull Request wird zu einem Design-Review-Artefakt; und eine schlechte Änderung ist ein git revert statt eines Archäologie-Projekts. Doch die Vorteile stellen sich nur mit Workflow-Disziplin ein: Diffs, die klein und stabil bleiben, eine Prüf-Checkliste, die Token-Zeilen als Design- Entscheidungen liest, und regenerierte Änderungen, die von Handbearbeitungen getrennt werden.

Dies ist das Governance-Kapitel unseres Design-Tokens-Leitfadens: wie ein Token-Diff sich liest, was ein Reviewer von ihm verlangen sollte und die Etikette, die eine generierte Datei prüfbar hält. Es setzt das Projekt-Muster voraus, bei dem die Token-Datei im Repository liegt und durch dasselbe Gate läuft wie Code.

Warum gehören Design Tokens unter Versionskontrolle?

Versionskontrolle verleiht jeder Datei drei Eigenschaften — eine zugeordnete Historie, geprüfte Änderungen, eine wiederherstellbare Vergangenheit — und Tokens sind unter den Design-Artefakten insofern ungewöhnlich, als sie alle drei zugleich einsammeln können. Design-Entscheidungen haben ansonsten eine notorisch dünne Herkunft: die Antwort auf „Warum ist die Akzentfarbe genau dieses Blau?” steckt meist in einem stillgelegten Chat-Verlauf, einem alten Deck oder jemandes Gedächtnis. Sobald die Entscheidung eine Zeile in einer versionierten Datei ist, wird die Commit-Nachricht zum Ort, an dem die Begründung dauerhaft neben der Änderung sitzt, die sie erklärt — re-point accent to secondary for the promo quarter; revert after Q3 dokumentiert eine Design-Entscheidung dauerhafter, als die meiste Design-Dokumentation es schafft.

Rollback ist dieselbe Eigenschaft, rückwärts gelesen. Ein Rebranding, das zurückgenommen werden muss, ist ein einziger Revert, wenn es token-förmig ist; ohne die Datei ist es eine Suche durch Stylesheets nach jedem Wert, der sich geändert hat — Wochen, nachdem sich noch jemand erinnert, ihn geändert zu haben.

Der intuitive Grund, warum Prüfung hier funktioniert und bei den meisten Design-Artefakten nicht: Prüfung setzt voraus, dass eine Änderung klein genug ist, um sie im Kopf zu behalten. Eine Änderung an einer Design-Datei ist ein Bild — der Reviewer sieht den neuen Zustand, nicht das Delta. Eine Token-Änderung ist das Delta: eine Handvoll benannter Zeilen. Tokens komprimieren die Design-Ebene auf eine Größe herunter, die Prüfung tatsächlich verarbeiten kann, und alles Weitere in diesem Artikel stützt sich auf diese Kompression.

Wie liest sich ein Token-Diff?

Hier ist ein sechs Zeilen langer Diff, auf die geänderten Zeilen gekürzt und mit den Abschnitten annotiert, in denen sie stehen — eine Abstandsstufe verengt, eine Akzentfarbe umgebogen, eine semantische Rolle hinzugefügt:

@@ spacing @@
-"space-3":    { "$value": "16px", "$type": "dimension" }
+"space-3":    { "$value": "14px", "$type": "dimension" }
@@ semantic @@
-"accent":     { "$value": "{color.brand.600}",     "$type": "color" }
+"accent":     { "$value": "{color.secondary.500}", "$type": "color" }
+"text-promo": { "$value": "{color.neutral.900}",   "$type": "color" }
@@ semantic-dark @@
+"text-promo": { "$value": "{color.neutral.50}",    "$type": "color" }

Jede Zeile sollte eine bestimmte Prüffrage auslösen:

space-3, 16px → 14px. Ein Primitive — die Änderung fächert zu jedem Konsumenten aus. Wer liest space-3? Wenn die Antwort Card-Padding, Listenabstände und Formularzeilen lautet: liest sich die Verengung in allen wie beabsichtigt, oder war sie auf einen einzigen überfüllten Screen gemünzt? Ein Primitive, das bearbeitet wird, um eine Komponente zu reparieren, ist ein klassischer Token-Smell; der gezielte Fix gehört an die Komponente, nicht in die gemeinsame Stufe.
accent, umgebogen. Ein Semantic — gezielt, aber tragend: welche Komponenten konsumieren accent, und schafft der bestehende Text auf dem Akzent noch seinen Kontrast-Mindestwert gegen die neue Füllung? Eine Zeile im Diff, eine vollständige Neuverifizierung dahinter. Dazu eine Prozessfrage: ist diese Umbiegung das, was der PR-Titel sagt, dass der PR tut?
text-promo, zweimal hinzugefügt. Eine neue Rolle: ist es ein echter Job, den je ein zweiter Konsument nutzen wird, oder ein Einzelfall, der näher an seine Komponente gehört? Folgt der Name den Konventionen? Er taucht in beiden Theme-Abschnitten auf — gut; ein Semantic nur für den Light-Mode ist ein Dark-Mode-Bug mit Zeitverzögerung.

Beachte, was der Reviewer nie gefragt hat: ob das JSON parst. Maschinen prüfen Syntax, bevor die Prüfung beginnt; die gesamte Aufgabe des Reviewers ist die Menge an Design-Fragen, die kein Linter stellen kann.

Öffne die Datei, aus der diese Zeilen stammen, in Scale Composer — die kanonische Token-Datei, wie sie in einem Repository liegt, Abschnitte in stabiler Reihenfolge, mit denselben Namen, die der Diff zeigt.

Scale Composer zeigt die kanonische DTCG-Token-Datei eines Projekts — die stabile Abschnitts- und Schlüsselreihenfolge, die ihre Git-Diffs klein hält

Was sollte ein Token-Pull-Request-Review prüfen?

Vier Prüfungen decken das meiste ab, was zählt:

Blast Radius. Welche Ebene hat sich geändert? Eine Änderung an einem Primitive fächert zu allem aus, was es referenziert — direkt oder über Aliase; eine einzeilige Bearbeitung kann die größte Änderung im Release sein. Eine semantische Umbiegung ist gezielt: die Konsumenten dieser einen Rolle. Lies zuerst die Ebene; sie legt die Tiefe fest, die der Rest der Prüfung braucht.
Kontrast, für jede Farbzeile. Jede geänderte Füllung oder umgebogene Text-Rolle bedeutet, die Paarungen neu zu verifizieren, an denen sie beteiligt ist — hier nur eine Zeile, weil Kontrast-Verifizierung eine Disziplin für sich ist; die Prüfung ist der Ort, an dem sie eingeplant wird.
Konsistente Benennung. Prüfe neue Tokens gegen die Konventionen des Projekts im letzten günstigen Moment: vor dem Merge ist eine Umbenennung ein Review-Kommentar; nach dem Merge ist sie ein Breaking Change für jeden Konsumenten.
Keine Waisen. Ein neues Token sollte von irgendetwas konsumiert werden, sonst geht es als Spekulation raus, die jemand später per Namensabgleich einordnen muss. Ein gelöschtes Token sollte von nichts referenziert werden — eine baumelnde {reference} ist ein Fehler beim nächsten Export, jetzt gefunden oder später.

Wie hältst du generierte Diffs lesbar?

Generierte Dateien haben in der Prüfung einen besonderen Fehlermodus: wenn das Tool bei jedem Speichern Schlüssel umsortiert oder neu formatiert, ist jeder Diff eine Neufassung, und Reviewer gewöhnen sich das Überfliegen an — genau so ging die Dienstags-Akzentfarbe raus. Drei Disziplinen verhindern das:

Stabile Serialisierung. Das Tool muss die Datei jedes Mal auf dieselbe Weise schreiben. Scale Composer serialisiert kanonisch — stabile Abschnittsreihenfolge, stabile Schlüsselreihenfolge; Speichern, Laden und erneutes Speichern ist ein getesteter Fixpunkt — sodass eine Änderung an einem Wert einen Diff von etwa einer Zeile erzeugt und einundvierzig geänderte Zeilen einundvierzig Entscheidungen bedeuten statt Rauschen.
Regenerierung von Handbearbeitungen trennen. Ein Commit, der das System neu ableitet („re-derive after seed change”), und ein Commit, der von Hand einen Abschnitt hinzufügt, verlangen unterschiedliche Prüfmodi — der erste wird auf seine Parameter geprüft, der zweite Zeile für Zeile. Sie zu vermischen begräbt das Urteil im Rauschen.
Commit-Nachrichten, die die Entscheidung benennen. „tighten space-3 to 14px — density pass on forms” liest sich ein Jahr später als Design- Begründung; „update tokens” liest sich als nichts.

Eine Grenze ist bewusst gezogen: Scale Composer hat keine Diff-Ansicht. Das Diffen ist Sache von Git — die Aufgabe des Tools ist es, die Datei diff-fähig zu halten, weshalb kanonische Serialisierung das Feature ist und eine Diff-Oberfläche nicht.

Schick die nächste Änderung durch die Prüfung

Der Workflow spricht für sich selbst, sobald ein Diff zum ersten Mal etwas abfängt. Justiere einen Wert in Scale Composer nach und exportiere — verenge eine Abstandsstufe oder biege eine Rolle um, speichere über die committete Datei und lies, was git diff dir zeigt: die ganze Änderung in ein paar stabilen Zeilen, bereit für die vier Fragen eines Reviewers.