Wie Farb-Tokens wirklich funktionieren: der Mechanismus aus Primitiven, Rollen und Aliasen, der Themes erst möglich macht

    20. November 2026
    8 Min. Lesezeit
    Von Emil Thornovik
    Diesen Artikel teilen

    Eine Entwicklerin schreibt in eine Komponente den Namen color.action.background.primary und denkt nicht mehr darüber nach, welches Blau dahintersteht. Im hellen Theme der Hauptmarke wird daraus ein kräftiges Mittelblau, im dunklen Theme ein helleres, in der Zweitmarke ein Petrol.

    Genau diese Entkopplung ist der Sinn eines Farb-Tokens: Ein Name beschreibt eine Aufgabe, und erst eine Kette von Verweisen entscheidet, welcher Farbwert am Ende auf dem Bildschirm landet. Wie lang diese Kette sein soll, ist die eigentliche Strukturfrage. Diese Vorlage bereitet sie so auf, dass ein Designteam sie in einer Sitzung entscheiden kann.

    Die Entscheidung, um die es geht

    Die Ausgangslage ist illustrativ, aber typisch für Produktteams mit gewachsenem Designsystem. Eine B2B-Plattform betreibt zwei Marken auf derselben Codebasis, die Hauptmarke und eine Whitelabel-Variante für einen Großkunden. Beide brauchen ein helles und ein dunkles Theme. In Figma existieren 140 Farbstile, davon tragen etwa 60 Namen wie Blue 500, der Rest Namen wie Button Primary oder Card Border. Im Code liegen 210 CSS-Variablen, von denen 35 in keiner Komponente mehr verwendet werden. Niemand weiß genau, welche Figma-Farbe zu welcher Variablen gehört.

    Der Auslöser für die Entscheidung ist konkret. Der Großkunde möchte im nächsten Quartal ein drittes Theme mit erhöhtem Kontrast für seine Mitarbeitenden mit Sehbeeinträchtigung. Bei der aktuellen Struktur müsste das Team jede Komponente einzeln anfassen. Eine grobe Schätzung ergibt 18 Personentage für das Theme allein, und jedes weitere würde wieder so viel kosten.

    Zur Wahl stehen drei Optionen. Option A ist eine flache Palette: alle Farben als Rohwerte mit Namen nach Farbton und Helligkeit, die Komponenten verweisen direkt darauf. Option B sind zwei Ebenen: Primitive als Rohwerte, darüber semantische Tokens, die eine Rolle beschreiben, und Komponenten verweisen nur auf die semantische Ebene. Option C sind drei Ebenen: zusätzlich zu B eine Komponentenebene, auf der jede Komponente eigene Tokens hat, die wiederum auf semantische verweisen.

    Die Entscheidung betrifft Design und Entwicklung gleichermaßen. Sie bestimmt, wie Figma-Variablen organisiert werden, wie die JSON-Dateien aussehen, die ein Werkzeug wie Style Dictionary in CSS übersetzt, und wie lange ein neues Theme dauert. Revidieren lässt sie sich später nur mit einer Migration aller Komponenten, deshalb lohnt es sich, sie bewusst zu treffen.

    Wie die Ebenen ineinandergreifen

    Der Mechanismus hinter allen drei Optionen ist das Alias. Ein Token enthält entweder einen Rohwert, etwa einen Hex-Code, oder einen Verweis auf ein anderes Token. Das Format der W3C Design Tokens Community Group schreibt solche Verweise in geschweiften Klammern, Figma Variables lösen sie über Collections und Modes auf. Beim Bauen wird die Kette verfolgt, bis ein Rohwert erreicht ist.

    In Option B sieht das so aus: Die Komponente nutzt color.text.default. Dieses Token zeigt im Mode Hell auf das Primitive grey.900 und im Mode Dunkel auf grey.50. Nur die semantische Ebene kennt Themes. Die Primitive bleiben in jedem Theme gleich, sie sind schlicht der Farbkasten.

    Damit diese Kette lesbar bleibt, braucht jedes Team eine feste Grammatik für Namen und eine harte Regel für Kontrast. Beides lässt sich als Formel aufschreiben:

    Token-Name  = Kategorie . Rolle . Element . Variante . Zustand
    Beispiel    = color . action . background . primary . hover
    Pflicht     = Kategorie, Rolle, Element
    Optional    = Variante, Zustand (weglassen, wenn es nur eine gibt)
    
    Kontrast    = (L_hell + 0,05) / (L_dunkel + 0,05)
    L           = relative Leuchtdichte nach WCAG, Wert zwischen 0 und 1
    Mindestwert = 4,5 für normalen Text, 3 für großen Text und UI-Grenzen (WCAG 2.x, Stufe AA)
    

    Die Reihenfolge der Namensteile ist kein Detail. Steht die Rolle vor dem Element, sortieren sich in Figma und im Code alle Tokens einer Rolle zusammen: Alles, was zu action gehört, steht beieinander, egal ob Hintergrund, Text oder Rahmen. Steht das Element vorn, landen alle Hintergründe beieinander, und die Zusammengehörigkeit eines Buttons zerfällt über die Liste. Für Designsysteme mit vielen Zuständen hat sich die Rolle vorn als besser durchsuchbar erwiesen.

    Die Kontrastformel gehört in die Struktur, weil sie Paare prüft, keine Einzelfarben. Ein semantisches Paar wie color.text.default auf color.surface.default muss in jedem Mode den Mindestwert erreichen. Wer die Paare als Liste pflegt, kann den Test automatisieren: Ein Skript löst alle Aliase je Mode auf, berechnet die Verhältnisse und bricht den Build ab, wenn ein Paar unter 4,5 fällt. Für das geplante Theme mit erhöhtem Kontrast setzt man die Schwelle auf 7, den Wert der Stufe AAA für normalen Text.

    Drei Optionen im Vergleich

    Mit dem Mechanismus im Kopf lassen sich die Optionen an Kriterien messen, die für die konkrete Plattform zählen. Die Zahlen in der Tabelle sind Schätzungen für das illustrative System mit rund 40 Komponenten und gelten nur als Größenordnung.

    Kriterium A: flache Palette B: Primitive und Semantik C: drei Ebenen
    Anzahl Tokens etwa 60 etwa 60 plus 90 etwa 60 plus 90 plus 400
    Aufwand für ein neues Theme 15 bis 20 Personentage 2 bis 3 Personentage 2 bis 4 Personentage
    Einzelne Komponente anpassen im Komponentencode nur über neues semantisches Token ein Komponenten-Token umbiegen
    Einarbeitung neuer Teammitglieder sofort etwa eine Woche zwei bis drei Wochen
    Risiko für Wildwuchs hoch, jede Komponente wählt frei mittel, Rollen müssen gepflegt werden hoch, viele fast gleiche Tokens
    Automatischer Kontrasttest kaum möglich gut, Paare auf Rollenebene gut, aber viele Paare

    Option A ist billig im Aufbau und teuer bei jedem Theme. Sie passt zu einem einzelnen Produkt ohne Dark Mode und ohne Markenvarianten, also nicht zur beschriebenen Plattform. Die 18 geschätzten Personentage für das Kontrast-Theme sind genau ihr Preis.

    Option B verschiebt den Aufwand in die Pflege der Rollen. Rund 90 semantische Tokens klingen nach viel, decken aber Text, Flächen, Rahmen, Aktionen, Status und Fokus in allen gängigen Varianten ab. Neue Themes entstehen, indem man den semantischen Tokens einen neuen Mode mit anderen Verweisen gibt. Keine Komponente muss angefasst werden.

    Option C bietet die feinste Steuerung. Ein Kunde, der nur die Buttons in seiner Hausfarbe möchte, bekommt einen Override auf Komponentenebene, ohne dass sich Links oder Fokusringe mitändern. Der Preis sind Hunderte zusätzliche Tokens, von denen die meisten eins zu eins auf ein semantisches Token zeigen und nur dem Ordnungssinn dienen. Ohne strenge Pflege entsteht genau der Wildwuchs, den die Struktur verhindern sollte, nur eine Ebene höher.

    Entscheidungsbaum für das eigene System

    Nicht jedes Team hat die Ausgangslage der Beispielplattform. Die folgenden Fragen führen in der Reihenfolge, in der sie gestellt werden sollten, zu einer der drei Optionen. Jede Antwort sollte sich auf den Plan für die nächsten 12 bis 18 Monate beziehen, nicht nur auf den Ist-Zustand.

    1. Gibt es oder kommt in absehbarer Zeit mehr als ein Theme, also Dark Mode, eine Zweitmarke oder ein Kontrast-Theme? Nein: Option A reicht, aber mit sauberer Namensgrammatik, damit ein späterer Umbau leichter fällt. Ja: weiter mit Frage 2.
    2. Unterscheiden sich die Themes nur in den Farbwerten, während die Logik gleich bleibt, also Primärfarbe bleibt Primärfarbe? Ja: weiter mit Frage 3. Nein, einzelne Komponenten verhalten sich je Marke grundlegend anders: weiter mit Frage 4.
    3. Gibt es mehr als zwei oder drei Komponenten, die regelmäßig eine Sonderfarbe brauchen, die keiner Rolle entspricht? Nein: Option B. Ja: Option B mit einer kleinen Zahl gezielter Komponenten-Tokens nur für diese Ausnahmen.
    4. Haben Design und Entwicklung zusammen mindestens eine Person, die zu einem festen Anteil ihrer Zeit, etwa 20 Prozent, für das Designsystem zuständig ist? Ja: Option C ist tragbar. Nein: Option B wählen und die Markenunterschiede über zusätzliche semantische Rollen abbilden, weil drei Ebenen ohne Pflegeverantwortung innerhalb eines Jahres verwildern.
    5. Wird das System von externen Teams oder Kunden konsumiert, die eigene Themes bauen sollen? Ja: Die öffentliche Schnittstelle sollte die semantische Ebene sein, unabhängig davon, ob intern eine Komponentenebene existiert. Externe dürfen Primitive nie direkt referenzieren.

    Für die Beispielplattform ergibt sich der Weg 1 ja, 2 ja, 3 ja. Zwei Komponenten, eine Diagrammbibliothek und ein Kalender, brauchen eigene Farben, die keiner Rolle entsprechen. Das Ergebnis ist Option B mit wenigen gezielten Komponenten-Tokens.

    Empfehlung, Risiken und Umsetzung in Figma und Code

    Empfohlen wird für die Plattform Option B mit dokumentierten Ausnahmen. In Figma bedeutet das zwei Collections: Primitives ohne Modes, Semantic mit den Modes Hell, Dunkel und später Kontrast, jeweils für beide Marken. Ob die Marke als eigener Mode oder als eigene Collection abgebildet wird, hängt vom Figma-Tarif ab, weil die Zahl der Modes pro Collection je nach Plan begrenzt ist. Primitive werden für Designer in der Veröffentlichung verborgen, damit niemand sie direkt auf eine Fläche zieht.

    Im Code liegen die Tokens als JSON im Format der Design Tokens Community Group, mit einem Eintrag für Wert und Typ pro Token. Ein Build mit Style Dictionary erzeugt daraus CSS Custom Properties pro Theme, die über ein Attribut am Wurzelelement umgeschaltet werden. Die 35 ungenutzten CSS-Variablen fallen bei der Migration weg. Für die rund 40 Komponenten rechnet das Team mit 12 bis 15 Personentagen Umstellung, einmalig.

    Drei Risiken sollten im Protokoll stehen. Erstens die Versuchung, semantische Tokens nach Komponenten zu benennen, etwa color.card.background: Das ist durch die Hintertür Option C ohne deren Ordnung. Zweitens Rollen, die sich überlappen, zum Beispiel surface.raised und surface.elevated für dasselbe. Ein vierteljährlicher Abgleich mit Nutzungszahlen aus dem Code fängt das ab. Drittens der Kontrasttest, der nur hilft, wenn er im Build läuft und nicht als einmalige Prüfung.

    Unterm Strich ist es ein Tausch. Option B kauft schnelle Themes und einen automatisierbaren Kontrasttest mit einer Woche Einarbeitung und der Pflicht, rund 90 Rollen sauber zu halten. Option C wäre feiner, kostet aber Pflegezeit, die das Team heute nicht hat, und Option A spart nur so lange, bis das nächste Theme kommt. Für eine Plattform mit zwei Marken und einem angekündigten dritten Theme ist das ein Tausch, der sich schon beim ersten neuen Mode auszahlt.

    Ähnliche Artikel