Konventionen zur Benennung von Tokens

Bei inkonsistenten Token-Namen lässt sich nicht erkennen, was ein Token bewirkt, ohne seinen Wert zu lesen. Eine klare, vorhersehbare Benennungskonvention ist die Grundlage für ein skalierbares Token-System.

Ein häufig verwendetes Muster ist: [category]-[property]-[variant]. Beispiele: color-text-primary, color-text-secondary, spacing-inset-sm. Jedes Segment schränkt die Bedeutung schrittweise ein.

Vermeiden Sie in Komponenten Palettennamen wie blue-500. Verwenden Sie semantische Namen wie color-action-default oder color-feedback-error. Semantische Namen überstehen Änderungen der Markenfarbe, ohne dass Komponenten aktualisiert werden müssen.

Fügen Sie den Status am Ende an: color-button-bg-default, color-button-bg-hover, color-button-bg-disabled. Einheitliche Statussuffixe machen Token-Sets vorhersehbar und vollständig.

Verwenden Sie entweder T-Shirt-Größen (xs, sm, md, lg, xl) oder numerische Skalen (100, 200 … 900) konsequent. Numerische Skalen erlauben das Einfügen von Zwischenwerten; T-Shirt-Größen sind bei kleinen Mengen leichter verständlich.

Versehen Sie Tokens in Systemen für mehrere Marken oder Produkte mit einem Namespace-Präfix: brand-a-color-primary im Vergleich zu brand-b-color-primary. Namespaces verhindern Kollisionen beim Zusammenführen von Token-Sets.

Kebab-Case wird direkt in CSS Custom Properties übernommen: color-text-primary wird zu --color-text-primary. Camel-Case-Tokens müssen umgewandelt werden, Kebab-Case-Tokens hingegen nicht.

Gute Namen sind selbsterklärend: spacing-stack-md (vertikaler Abstand zwischen gestapelten Elementen, mittel) vermittelt die Absicht ohne Kommentar. Bei schlechten Namen wie s3 ist zum Verständnis eine externe Dokumentation erforderlich.

Sobald Tokens verwendet werden, sind Umbenennungen inkompatible Änderungen. Verwenden Sie Aliasnamen zur Abkündigung: Behalten Sie den alten Namen bei, lassen Sie ihn aber auf den neuen Token verweisen. Geben Sie den Nutzern eine Übergangsfrist, bevor Sie abgekündigte Tokens entfernen.

Prüfen Sie Token-Namen mit benutzerdefinierten Regeln in Style Dictionary oder einem CI-Skript. Lehnen Sie Tokens ab, die nicht dem Benennungsmuster entsprechen. Automatisierte Prüfungen verhindern, dass die Benennung mit wachsendem System uneinheitlich wird.

Veröffentlichen Sie einen Leitfaden zur Benennung mit Beispielen für korrekte und inkorrekte Namen. Führen Sie einen kurzen Workshop durch, damit sich Design- und Engineering-Teams auf Konventionen einigen, bevor das System wächst. Konsistenz erfordert ein gemeinsames Verständnis, nicht nur Dokumentation.

Warum sollten Komponenten-Tokens semantische Namen statt Palettennamen wie "blue-500" verwenden?

Eine konsistente Konvention zur Benennung von Tokens mit Mustern aus Kategorie, Eigenschaft und Variante, semantischen Namen, Zustands-Suffixen und Namespace-Präfixen macht Tokensysteme vorhersehbar, selbstdokumentierend und robust gegenüber Markenänderungen, ohne den Komponentencode zu beeinträchtigen.