Namenskonventionen für Design Tokens

Der Name eines Design Tokens ist ein Pfad, gelesen von breit zu schmal: category-concept-variant-state — wie in color-background-subtle, space-4, text-heading-lg. Die Konventionen, die sich über die Zeit bewähren, folgen fünf Regeln: benenne die Entscheidung statt des Werts, stelle bei Primitives die Position vor das Aussehen, stelle bei semantischen Tokens die Rolle vor den Kontext, reserviere einen festen Satz von State-Suffixen und wähle genau einmal eine Schreibweise. Alles unterhalb dieser Regeln — bg oder background, sm oder small — ist eine Mikro-Entscheidung, die man einmal trifft, festhält und nicht mehr aufrollt.

Dieser Artikel behandelt die Namenskonventionen, die sich durch jede Token-Kategorie ziehen; er ist das Namens-Kapitel unseres Design-Tokens-Leitfadens. Farbe und Typografie fügen auf diesen Regeln domänenspezifische Argumente hinzu — die Regeln selbst sind das gemeinsame Fundament.

Wie ist ein Token-Name aufgebaut?

Als ein Pfad, bei dem jedes Segment das vorige einengt. Die Kategorie sagt, welche Art von Wert das ist (color, space, text); das Konzept sagt, welchen Teil der Oberfläche er bedient (background, border, heading); die Variante unterscheidet Geschwister (subtle, raised, lg, 4); der State — falls vorhanden — benennt einen Interaktionszustand (hover, disabled). Nicht jeder Name nutzt alle vier Segmente: space-4 ist eine Kategorie und eine Variante mit nichts dazwischen, weil Abstände keine Konzepte zu unterscheiden haben.

Zwei Konventions-Familien tragen denselben Pfad. Hyphen-case schreibt ihn flach — color-background-subtle — was CSS Custom Properties verlangen. Dot-Pfade schreiben ihn als Verschachtelung — color.background.subtle — was das DTCG-Format erzeugt, wo Gruppen verschachtelte Objekte sind und der Name der Pfad zum Blatt ist. Die Abbildung zwischen beiden ist eine mechanische Zeile: ersetze Punkte durch Bindestriche und stelle -- voran, und jeder DTCG-Pfad wird zu einem gültigen Custom-Property-Namen. Weil die Abbildung mechanisch ist, überträgt sich die Design-Arbeit — die Wahl der Segmente — unverändert zwischen den Formaten; nur die Interpunktion ist formatspezifisch.

Welche Namensregeln überstehen den Kontakt mit der Realität?

1. Benenne die Entscheidung, nicht den Wert. Das ist das Gesetz im Kern davon, was Design Tokens sind, und jede Token-Kategorie führt es aus: brand-600 überlebt den Rebrand, der die Markenfarbe zu Türkis ändert, während blue-600 entweder über seinen Inhalt lügt oder einen Rename über jede Datei erzwingt, die es referenziert. Dasselbe Gesetz schließt space-16px aus (falsch an dem Tag, an dem der Schritt auf 14 umgestimmt wird) und bevorzugt Namen, die sagen, wofür ein Token da ist — denn das „Wofür” ist die stabile Tatsache und der Wert der veränderliche.

2. Position vor Aussehen, bei Primitives. 600 benennt einen Platz in einer Rampe; dark beschreibt, wie der Wert heute zufällig aussieht. Wenn eine Rampe umgestimmt wird — die Helligkeitskurve angepasst, ein Schritt eingefügt —, behalten Positionen ihre Bedeutung, während Aussehens-Wörter stillschweigend aufhören, wahr zu sein: ist blue-dark nach der Umstimmung noch dunkler als blue-darker? Nummerierte Positionen überleben jede Umstimmung, indem sie nie etwas über den Wert behaupten.

3. Rolle vor Kontext, bei semantischen Tokens. text-primary benennt eine Aufgabe und überträgt sich auf jeden Screen, der primären Text hat; article-heading-color benennt einen Ort und ist dort gestrandet. Kontexte vermehren sich grenzenlos — article, card, modal, sidebar, settings — während Rollen zählbar bleiben: die meisten Systeme brauchen ein oder zwei Dutzend. Benennung nach Rolle hält den Token-Satz auf der Größe der Rollenliste statt auf der Größe des Produkts.

4. Reserviere die State-Suffixe. Deklariere ein kurzes, festes Vokabular — -hover, -pressed, -focus, -disabled, -selected —, das nur je am Ende eines Namens auftaucht und nur je Interaktionszustand bedeutet. Der Gewinn ist Vorhersagbarkeit: wer weiß, dass fill-brand existiert, kann fill-brand-hover schreiben, ohne eine Datei zu öffnen. Ein nicht reserviertes Vokabular verfällt zu einem Nebeneinander von fill-brand-hover, fill-brandHover2 und fill-brand-mouseover.

5. Wähle eine Schreibweise und rolle sie nie wieder auf. kebab-case, camelCase oder Dot-Pfade — die Belege dafür, dass eine davon überlegen wäre, sind dünn, was genau der Grund ist, warum die Debatte nie an ihren Sachargumenten endet. Namenskonventionen gehören zu den ältesten Debatten-Magneten der Programmierung, und Token-Benennung erbt die Steuer: Teams können hier Wochen verbrennen, und die Wochen bringen nichts, denn jede konsistente Konvention schlägt eine perfekte, über die noch gestritten wird — Konsistenz ist das, worauf sich die Regeln 1–4 und jeder Export in der Toolchain verlassen. Entscheide in einem Meeting, halte die Entscheidung fest, schließe das Thema.

Öffne ein generiertes Token-System und lies seine Namen über die Formate hinweg — dieselben Pfade geschrieben als DTCG-Gruppen, als CSS Custom Properties und als Figma-Variablennamen, die Segmente in jeder Darstellung sichtbar.

Sollte es bg oder background heißen, sm oder small?

Es ist weniger wichtig, was du wählst, als dass du einmal wählst und es festhältst. Diese Mikro-Entscheidungen sind der Ort, an dem sich Namensdebatten verstecken, nachdem die großen Regeln geklärt sind — hier also ein vertretbarer Satz an Entscheidungen, jeweils mit einer Zeile Begründung:

Die Aufgabe der Tabelle ist es, fertig zu sein, nicht perfekt. Wenn dein Team schon die Hälfte davon anders schreibt, behalte die bestehenden Entscheidungen und dokumentiere sie — eine geerbte konsistente Konvention rangiert über einer besseren inkonsistenten, was wieder Regel 5 ist, nur in anderen Kleidern.

Was macht einen Token-Namen gut?

Er kann von jemandem vorhergesagt werden, der ihn nie gesehen hat. Das ist der praktische Test: zeig einem neuen Teammitglied color-background-subtle und color-text-primary und frag dann, wie ein gedämpfter Rahmen heißen würde. Antwortet es color-border-subtle — und existiert das —, tut die Konvention ihre Arbeit.

Der intuitive Grund, warum Vorhersagbarkeit mehr zählt als Eleganz: eine Namenskonvention ist eine kleine Grammatik, und Menschen verallgemeinern aus Grammatiken automatisch nach einer Handvoll Beispiele. Namen, die der Grammatik folgen, werden vorhergesagt statt nachgeschlagen — jede richtige Vorhersage ist eine Doku-Suche, die nie stattfindet, ein Beinahe-Duplikat, das nie geprägt wird, ein Review-Kommentar, der nie geschrieben werden muss. Namen, die die Grammatik brechen, kosten je ein Nachschlagen, für immer. Der Test läuft auch rückwärts: wenn jeder Name die Doku offen braucht, tragen die Namen keine Struktur, die zu lernen sich lohnt.

Wie sieht der Token-Satz einer Komponente aus, gut und schlecht benannt?

Eine Card-Komponente braucht fünf Farbentscheidungen. Hier sind sie zweimal — einmal so, wie Token-Sätze anzuwachsen pflegen, wenn niemand eine Konvention hält, einmal nach den obigen Regeln:

Beide Spalten rendern heute dieselbe Card. Die Probleme der linken Spalte sind allesamt Zukunftsprobleme: drei Schreibweisen in fünf Namen (Regel 5); blueDark benennt einen Wert und wird nach einem Rebrand lügen (Regel 1); card_outline_gray bricht zwei Regeln in einem Namen — einen Kontext und ein Aussehen — sodass die nächste Komponente, die denselben Rahmen braucht, entweder ein „card”-Token borgt oder ein Duplikat prägt (Regeln 2 und 3); cardBgHover2 trägt einen nicht reservierten State und eine mysteriöse Seriennummer (Regel 4). Die rechte Spalte löst sich über eine semantische Ebene in Rampenschritte auf, die aus einer Ausgangsfarbe abgeleitet sind — auf dieser Palette #2563eb, also oklch(0.546 0.215 262.9) — und ihr sechstes Token ist erratbar, bevor es existiert: ein Pressed-State auf dem Button wäre color-fill-brand-pressed, und jeder Leser kennt es schon.

Stresstest der Namen gegen Veränderung

Ein Namensschema beweist sich bei Ereignissen, nicht in Review-Meetings: Rebrands, Rampen-Umstimmungen, Dark Mode. Lade eine Token-Datei und benenne ein wert-benanntes Primitive in einen Entscheidungsnamen um — re-exportiere, und der Round-Trip bewahrt jeden Abschnitt, den du nicht angefasst hast; ändere dann die Ausgangsfarbe und beobachte, wie das umbenannte Token weiter die Wahrheit sagt, während sich der Wert darunter bewegt.