Benennung von Design-Tokens: Das Drei-Ebenen-System und seine Schwachstellen

Die Konvention ist nahezu universell, was es einfach macht, die Struktur ohne die zugrunde liegende Logik zu übernehmen. Jede Ebene beantwortet eine andere Frage; zu wissen, welche das ist, verhindert, dass Dinge an der falschen Stelle platziert werden.

Die Regel, die dies ermöglicht, und diejenige, die am häufigsten verletzt wird: Nichts außerhalb der semantischen Ebene darf ein Primitive referenzieren. In dem Moment, in dem eine Komponente blue-600 direkt verwendet, wird die Primitive-Ebene zu einer öffentlichen API, und ein Wert kann nicht mehr geändert werden, ohne die gesamte Codebasis zu prüfen – was genau der Grund für die Einführung der Ebenen war.

:root {
  /* Tier 1: primitives. Values only. Nobody uses these directly. */
  --blue-600: #2563eb;
  --red-600:  #dc2626;
  --gray-500: #6b7280;

  /* Tier 2: semantic. Roles. This is the public API. */
  --color-primary:   var(--blue-600);
  --color-danger:    var(--red-600);
  --text-muted:      var(--gray-500);

  /* Tier 3: component. Only where a component truly deviates. */
  --button-danger-bg: var(--color-danger);
}

/* ✅ product code */
.alert { color: var(--color-danger); }

/* ❌ reaches past the semantic layer */
.alert { color: var(--red-600); }

Von links nach rechts lesen, von allgemein zu spezifisch: Kategorie, Rolle, Variante, Zustand. Nicht jeder Token benötigt alle vier; diejenigen, die es tun, sind in der Regel interaktiv.

Konsistenz ist weitaus wichtiger als das gewählte Muster. Eine Codebasis, in der die Hälfte der Tokens text-color-muted und die andere Hälfte color-text-muted heißt, zwingt alle Beteiligten dauerhaft zu einem unnötigen Nachschlagen. Legen Sie eine Reihenfolge fest, dokumentieren Sie diese und setzen Sie sie im Review durch.

Hier ist das angewendete Muster anstatt einer bloßen Beschreibung. Achten Sie auf die Rollennamen, nicht auf die Farben – die Frage, die jeder Name beantworten muss, lautet: „Wofür wird dies verwendet?“. Ein Name, der nur beantwortet, „Welche Farbe hat es?“, ist für seine Ebene ungeeignet.

Eine einzige Frage löst die meisten Diskussionen über die Benennung in Sekunden:

Wendet man dies auf reale Fälle an, sind die Antworten eindeutig:

Der Fall --shadow-card ist subtil und eine nähere Betrachtung wert. Wenn ein Token nach seiner Implementierung benannt wird, fixiert dies die Implementierung. Sobald jede Karte in der Codebasis box-shadow: var(--shadow-card) verwendet, wird ein Wechsel zu einer rahmenbasierten Elevation zu einem Refactoring statt zu einer einfachen Token-Änderung – genau die Kopplung, die Tokens eigentlich verhindern sollten.

Die meisten Token-Systeme scheitern genau hier. Die Komponenten-Ebene beginnt klein und legitim, absorbiert dann aber alles, bis man schließlich vierhundert Tokens hat, von denen die Hälfte nur einen einzigen Consumer besitzt.

Der Mechanismus ist immer derselbe: Jemand benötigt einen Button-Hintergrund, der nicht ganz --color-primary entspricht. Das Hinzufügen von --button-primary-bg dauert dreißig Sekunden, während die Aufnahme in die semantische Ebene eine Abstimmung erfordern würde. Also wird das Komponenten-Token eingeführt, die nächste Person macht es genauso, und die semantische Ebene hört auf, die „Source of Truth“ zu sein, ohne dass dies jemals explizit so entschieden wurde.

Ein nützliches Audit: Zählen Sie die Tokens der Komponenten-Ebene, die genau einen Consumer haben. Ist diese Zahl hoch, wird die Ebene als Notausgang genutzt; die Lösung liegt dann weiter oben in der Hierarchie.

Diese Fehler treten in fast jedem Token-System auf, das nicht mehr genutzt wird. Jeder davon lässt sich frühzeitig günstig beheben, wird aber teuer, wenn man es ignoriert.

1. 1

   Nummerierte Skalen ohne Anker

   color-1 bis color-12 sagt niemandem etwas; die Zahlen erhalten ihre Bedeutung nur durch informelles Wissen. Nummerierte Skalen sind in der primitiven Ebene in Ordnung, wo die Zahl eine reale Dimension wie die Helligkeit abbildet. In der semantischen Ebene sind sie niemals akzeptabel, da der Zweck dieser Ebene darin besteht, die Funktion eines Elements zu definieren.

2. 2

   Kodierung des Themes im Namen

   Wenn --light-bg und --dark-bg separate Tokens sind, muss jede Komponente auf beide referenzieren und verzweigen. Ein Name, zwei Werte, gewechselt durch das Theme – genau das ist die Aufgabe der Token-Schicht. Wenn Sie if (theme === 'dark') im Komponenten-Code finden, sind die Tokens falsch benannt.

   Copy

   /* ❌ */  --light-bg: #fff;  --dark-bg: #0a0a0a;
   /* ✅ */  --surface-base: #fff;
            [data-theme="dark"] { --surface-base: #0a0a0a; }

3. 3

   Größen, die nach ihrem aktuellen Verwendungszweck benannt sind

   --text-hero ist in Ordnung, bis die Hero-Größe plötzlich in einer Preistabelle auftaucht. --text-4xl oder --font-scale-7 benennen die Stufe, nicht die Seite, und bleiben bei einer Wiederverwendung gültig. Benennen Sie nach der Position in einer Skala, nicht nach dem ersten Kunden.

4. 4

   Statusfarben, die gleichzeitig als Markenfarben dienen

   Der häufigste Grund, warum ein System nicht mehr in der Lage ist, Zustände darzustellen. Wenn das Marken-Grün und das Erfolgs-Grün derselbe Token sind, kann die Marke nicht ohne Änderung der Erfolgsdarstellung neu gestaltet werden, und eine korrekte Zeile lässt sich nicht von einer markenspezifischen unterscheiden. Halten Sie den Status-Satz reserviert und vermerken Sie dies in einem Kommentar.

5. 5

   Abkürzungen, die nur eine Person versteht

   --clr-bg-scndry spart elf Zeichen und kostet jeden Leser für immer einen Dekodierungsschritt – einschließlich eines Modells, das raten muss, ob scndry für secondary steht oder ein Tippfehler ist. Autocomplete macht die Länge nahezu vernachlässigbar. Schreiben Sie die Wörter aus.

Tokens müssen zunehmend wandern: von einem Design-Tool zu CSS, in ein Tailwind-Theme, in eine native Plattform, in ein shadcn-Registry-Element, in eine DESIGN.md, die ein Agent liest. Das stellt eine Anforderung an die Namen, über die die meisten Teams erst nachdenken, wenn der erste Export fehlschlägt.

Die praktische Regel: Wählen Sie Namen, die gleichzeitig eine gültige CSS-Custom-Property, ein gültiger JSON-Key und eine lesbare englische Phrase sind. Flach, kleingeschrieben und mit Bindestrichen erfüllt alle drei Kriterien. Zudem lassen sich die verschachtelten Gruppen des DTCG/W3C-Token-Formats wesentlich einfacher aus einem flachen Set generieren als umgekehrt.

Die effektivste Entscheidung bei der Benennung ist nicht das Muster. Es ist die Frage, ob die Namen in Ihrem Design-Tool identisch mit den Namen im Code sind.

Salesforce's SLDS 2 ist das deutlichste veröffentlichte Beispiel: Die Figma-Bibliothek verwendet dieselben semantischen Hook-Namen wie das CSS – Beispiele hierfür sind radius-border-4 und font-scale-4 – sodass Designs eins-zu-eins auf den Live-Code abgebildet werden. Das erklärte Ziel ist ein gemeinsames Vokabular, das Design und Entwicklung verbindet.

Die praktische Folge ist, dass eine ganze Klasse von Handoff-Bugs verschwindet. Wenn ein Designer font-scale-4 sagt und ein Entwickler font-scale-4 tippt, gibt es keinen Übersetzungsschritt und somit keinen Raum für Missverständnisse. Vergleichen Sie dies mit einem Figma-Style namens "Heading / Large", der auf eine CSS-Variable namens --text-2xl abgebildet wird, wobei jeder Handoff eine Nachschlageaktion und jeder Nachschlag eine Chance für eine Fehlinterpretation ist.

Die Benennung von Tokens war früher eine Frage der menschlichen Ergonomie – Autocomplete, Lesbarkeit, Onboarding. Zunehmend ist der intensivste Leser Ihrer Token-Datei ein Coding-Agent, was verändert, welche Fehler kritisch sind.

Ein Mensch, der nicht weiß, welches von zwei Grautönen zu verwenden ist, wird nachfragen oder einen wählen und im Review korrigiert werden. Ein Modell wird stillschweigend in jeder Datei, die es bearbeitet, einen auswählen, und die Inkonsistenz breitet sich schneller aus, als ein Review sie erfassen kann. Mehrdeutigkeit in der semantischen Ebene ist heute ein wesentlich kostspieligerer Defekt als früher.

Wir haben 299 DESIGN.md-Dateien analysiert, die für Agents veröffentlicht wurden, und festgestellt, dass 86 % Farben als reine Hex-Werte ohne jegliche semantische Rolle angeben. Nicht schlecht benannte Tokens – sondern gar keine Tokens. Ein Modell, dem #6b7280 gegeben wird und dem gesagt wird, dass dies Teil der Palette ist, wird es überall verwenden, wo ein mittleres Grau plausibel ist: Fließtext, Rahmen, Icons, Platzhalter, deaktivierte Zustände. Fünf verschiedene Aufgaben, ein Wert, keine Möglichkeit, diese später unabhängig voneinander zu ändern.

Die zweite Version kostet drei zusätzliche Zeilen, ermöglicht aber die Möglichkeit, Rahmen abzudunkeln, ohne die Bildunterschriften abzudunkeln – eine Änderung, die gewünscht sein wird und die in der ersten Version ohne eine prüfung des gesamten Codebases unmöglich gemacht wird.

Wenn ein System von Grund auf benannt wird, ist dies ein vertretbares Minimum. Es ist bewusst klein gehalten – ein System, das niemand im Kopf behalten kann, wird ignoriert.

/* Surfaces — what things sit on */
--surface-base        /* the page */
--surface-raised      /* cards, panels */
--surface-overlay     /* modals, popovers */
--surface-sunken      /* wells, inset areas */

/* Text — by emphasis, never by colour */
--text-primary
--text-secondary
--text-muted
--text-disabled
--text-on-accent      /* text sitting on the accent colour */

/* Borders — by weight of presence */
--border-subtle
--border-strong
--border-focus

/* Action — the interactive colour and its states */
--action-primary
--action-primary-hover
--action-primary-active

/* Status — reserved. Nothing decorative uses these. */
--status-success
--status-warning
--status-danger
--status-info

Zwei Anmerkungen zu diesem Set. Text-Tokens werden nach der Betonung statt nach der Farbe benannt, damit sie im Dark-Mode konsistent bleiben. Status-Tokens enthalten einen Kommentar, der sie reserviert, da das häufigste Problem bei Status-Systemen darin besteht, dass Designer das Erfolgs-Grün als dekorativen Akzent verwenden und niemand mehr eine gesunde Zeile von einer markenspezifischen unterscheiden kann.