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. Man kann dann keinen Wert mehr ändern, 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 jedem Zeitpunkt zu einer erneuten Überprüfung. Legen Sie eine Reihenfolge fest, dokumentieren Sie diese und setzen Sie sie im Review durch.

Hier ist das angewendete Muster, statt einer bloßen Beschreibung. Achten Sie auf die Rollennamen, nicht auf die Farben. Die Frage, die jeder Name beantworten muss, lautet: „Wofür ist dies gedacht?“. Ein Name, der nur beantwortet, „welche Farbe hat es“, erfüllt die Anforderungen seiner Ebene nicht.

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 ein subtiler, aber wichtiger Punkt. Einen Token nach seiner Implementierung zu benennen, zwingt die Implementierung auf. Sobald jede Card im Codebase box-shadow: var(--shadow-card) verwendet, wird der Wechsel zu einer border-basierten Elevation zu einem Refactoring statt zu einer Token-Änderung – genau die Kopplung, die Design-Tokens eigentlich vermeiden sollten.

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

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, aber das Hinzufügen zur semantischen Ebene erfordert eine Besprechung. Also wird der Komponententoken eingefügt, die nächste Person macht dasselbe, und die semantische Ebene verliert ihre Funktion als Source of Truth, ohne dass dies jemals explizit entschieden wurde.

Ein nützliches Audit: Zählen Sie die Tokens der Komponentenebene mit exakt einem Consumer. Wenn diese Zahl hoch ist, wird die Ebene als Notlösung missbraucht; die Lösung liegt eine Ebene höher.

Diese Fehler treten in fast jedem Token-System auf, das irgendwann nicht mehr genutzt wird. Jeder Fehler ist leicht zu beheben, wenn er früh erkannt wird, und teuer, wenn nicht.

1. 1

   Nummerierte Skalen ohne Anker

   color-1 bis color-12 sagt niemandem etwas, und die Zahlen erhalten ihre Bedeutung nur durch Folklore. Nummerierte Skalen sind in der Primitive-Ebene völlig 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, zu sagen, wofür etwas da ist.

2. 2

   Das Theme im Namen kodieren

   --light-bg und --dark-bg als separate Tokens zu verwenden bedeutet, dass jede Komponente beide referenziert und verzweigt. Ein Name, zwei Werte, gewechselt durch das Theme: Genau dafür ist die Token-Ebene da. Wenn Sie if (theme === 'dark') im Komponentencode 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 benennt die Stufe, nicht die Seite, und bleibt auch 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 eine Ä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-Library verwendet dieselben semantischen Hook-Namen wie das CSS (ihre Beispiele sind radius-border-4 und font-scale-4), sodass Designs eins-zu-eins auf den Live-Code abgebildet werden. Ihr erklärtes 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 Suche ist und jede Suche eine Chance für eine Fehlinterpretation.

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, und das ändert die Art der Fehler, die relevant sind.

Ein Mensch, der nicht weiß, welches von zwei Grautönen er verwenden soll, 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 ein weitaus teurerer 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: gar keine Tokens. Ein Modell, dem #6b7280 gegeben wird und dem gesagt wird, dass dies Teil der Palette ist, wird es überall dort 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 zu verdunkeln, ohne die Bildunterschriften zu verdunkeln – eine Änderung, die gewünscht sein wird und die in der ersten Version ohne eine prüfung des gesamten Codebases unmöglich wäre.

Wenn ein System von Grund auf benannt wird, ist dies ein vertretbares Minimum. Es ist bewusst klein gehalten. Ein System, das niemand mehr 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 zur Reservierung, da das häufigste Problem bei Status-Systemen darin besteht, dass Designer das „Success-Grün“ als dekorativen Akzent verwenden und niemand mehr eine funktionierende Zeile von einer markenspezifischen unterscheiden kann.