Figma-Variablen-Architektur: So baust du ein Token-System, das die Produktion überlebt

Die meisten Teams, die Figma-Variablen nutzen, bauen auf einem Style-Mental Model auf, und genau das ist das Problem. Variablen ohne Architektur sind nur Styles mit zusätzlichen Klicks.

Die Teams, die es richtig machen, behandeln Figma-Variablen als echte Design-Tokens-Ebene: strukturiert, mit Aliasen, mit Scoping und exportierbar. Die Teams, die es falsch machen, sind nur einen Dark-Mode-Wunsch von einem kompletten Neuaufbau entfernt. Das hier ist die Architektur, die die Produktion überlebt.

Variablen sind keine Styles, sie sind die Token-Ebene

Figma-Styles sind Presets. Du definierst eine Farbe, einen Textstil, einen Effekt und wendest ihn direkt auf eine Ebene an. Das funktioniert für eine Datei mit einer Marke, einem Modus und ohne Dev-Handoff-Anforderungen. Es funktioniert nicht mehr, sobald sich irgendetwas ändert.

Figma-Variablen sind Tokens. Eine Variable hält einen Wert, kann aber auch eine Referenz auf eine andere Variable halten. Diese Referenzkette und die Möglichkeit, ganze Sets aufgelöster Werte über Modes umzuschalten, machen Variablen architektonisch anders als Styles. Der Unterschied ist nicht kosmetisch. Es ist der Unterschied zwischen einem Preset-System und einem Token-System.

Die Drei-Ebenen-Token-Architektur

Primitive, Semantic, Component. Jedes funktionierende Variablen-System hat diese drei Ebenen. Die Semantic-Ebene zu überspringen ist heute der häufigste Architekturfehler in Figma-Dateien.

Die drei Ebenen entsprechen drei Aufgaben: Primitive halten rohe Werte, Semantic-Tokens tragen Bedeutung, und Component-Tokens beziehen sich auf eine einzelne Komponentenfamilie. Jede Ebene spricht nur mit der Ebene unter ihr. Kein Überspringen, keine Abkürzungen.

Die drei Ebenen sind nicht je nach Projektgröße optional. Ein kleines System mit fünf Komponenten braucht trotzdem alle drei Ebenen, sonst sprengt der erste Theme-Wunsch es in die Luft.

Ebene eins: Primitive

Primitive sind die rohen Werte. blue-500, gray-900, space-4, radius-md. Sie sind die Palette, die Skala, das Fundament. Sie werden nie direkt an eine Komponentenebene gehängt.

Die Aufgabe eines Primitives ist es, zu existieren, von oben aliasiert zu werden und im Weg zu stehen, ohne zu stören. Wenn ein Designer zu blue-500 greift, um es auf einen Button anzuwenden, ist die Architektur schon kaputt. Primitive gehören in die Primitives-Collection und nirgendwo sonst hin.

Die Namenskonvention ist hier wichtig. Primitive sollten skalen- oder palettenbasiert benannt sein, nie semantisch. blue-500 ist richtig. button-blue als Primitive ist ein Kategorienfehler, der im großen Maßstab Schmerzen verursacht.

Ebene zwei: Semantic

Semantic-Tokens tragen Bedeutung. surface, surface-elevated, text-primary, text-muted, border-default, border-focus. Sie beantworten „Wofür ist diese Farbe?" statt „Welche Farbe ist das?"

Semantic-Tokens sind Aliase auf Primitive. Das ist die einzige Beziehung, die sie haben. Semantic-zu-Semantic-Aliasing erzeugt Unklarheit darüber, wo der Wert liegt, und macht Mode-Overrides unzuverlässig.

In dieser Ebene leben deine Light-, Dark- und Brand-Modes. Ein Semantic-Token löst je nach aktivem Mode in ein anderes Primitive auf, und so funktioniert Theming tatsächlich. Das Primitive blue-500 ändert sich nicht. Das Semantic-Token text-link ändert, worauf es je nach Mode auflöst.

Ebene drei: Component

Component-Tokens beziehen sich auf eine einzelne Komponentenfamilie. button-bg, button-text, button-border, card-surface, card-border, input-bg. Sie sind Aliase auf Semantic-Tokens, nie auf Primitive.

Die Aufgabe eines Component-Tokens ist Spezifität ohne Kopplung. button-bg löst auf surface-action auf, das auf blue-500 auflöst. Wenn sich die Marke ändert, aktualisierst du die Semantic-Ebene, und der Button zieht mit. Das Component-Token bleibt unberührt.

Ein häufiger Einwand lautet, das fühle sich nach zusätzlichen Tokens ohne Grund an. Der Grund ist, dass button-bg und surface-action auseinanderlaufen können. Irgendwann verlangt eine Produktentscheidung, dass der Button eine leicht andere Fläche nutzt. Component-Tokens geben dir den Override-Punkt, ohne das Semantic-System anzufassen.

Modes versus Collections: der Entscheidungsbaum

Modes schalten Werte innerhalb einer Collection um. Collections trennen Zuständigkeiten. Das sind zwei verschiedene Dinge, und sie zu vermischen ist die Quelle der meisten Architekturverwirrung in Figma-Variablen-Setups.

Die Regel: eine Collection pro Zuständigkeit, Modes für Varianten derselben Zuständigkeit. Farbe ist eine Zuständigkeit. Abstand ist eine Zuständigkeit. Light und Dark sind keine getrennten Zuständigkeiten. Sie sind Modes derselben Farb-Zuständigkeit.

Wann ein Mode, wann eine neue Collection:

• Anderer Wert für dieselbe Sache? Mode.
• Etwas völlig anderes? Collection.
• Umschalten zwischen Light und Dark? Mode innerhalb der Farb-Collection.
• Umschalten zwischen kompaktem und komfortablem Abstand? Mode innerhalb der Abstands-Collection.
• Eine Marke hinzufügen? Mode in der Semantic-Ebene, keine neue Collection.

Die vier Scoping-Regeln

Variablen-Scoping steuert, wo eine Variable in Figma angewendet werden kann. Wer das falsch macht, lässt Designer versehentlich zu Primitiven statt zu Semantic-Tokens greifen, und die Architekturdisziplin bricht an der Stelle der Anwendung zusammen.

Die vier Regeln sind nicht verhandelbar:

1. Scope Primitive auf none. Primitive sollten nirgendwo anwendbar sein. Sie sind interne Werte, keine Tokens für Konsumenten. Blende sie im Apply-Dropdown komplett aus.
2. Scope Semantic-Tokens auf ihren Typ. Ein Farb-Semantic-Token bekommt Scope auf Fills und Strokes. Ein Abstands-Token bekommt Scope auf Gap-, Padding- und Größenfelder. Halte den Scope eng.
3. Scope Component-Tokens auf ihre Familie. Ein Button-Token sollte nicht auf eine Card anwendbar sein. Ist der Scope zu breit, ist die Komponentengrenze bedeutungslos.
4. Setze Primitive nie Konsumenten aus. Wenn ein Designer oder Entwickler ein Primitive auf eine Ebene anwendet, hat das System auf der Scoping-Ebene versagt. Das ist ein Prozessfehler, kein Nutzerfehler.

Die Alias-Kette, die Themes möglich macht

Ein funktionierendes Theme ist eine Kette von Aliasen: Component aliasiert auf Semantic, Semantic aliasiert auf Primitive, Primitive hält den Wert. Die Kettenlänge ist drei, immer drei.

Eine Kette aus zwei Gliedern (Component auf Primitive) überspringt die Übersetzungsebene und macht Modes ohne manuelle Overrides an jedem Component-Token unmöglich. Eine Kette aus vier Gliedern erzeugt Unklarheit darüber, welche Semantic-Ebene den Mode trägt, und das Auditieren wird zur Debugging-Übung statt zum Nachschlagen.

button-bg → surface-action → blue-500 → #0066FF

Copy

Diese Kette übersteht Dark Mode, indem surface-action im Dark Mode der Semantic-Collection auf blue-300 zeigt. Das Token button-bg aktualisiert sich automatisch. Das Primitive blue-500 löst weiterhin auf #0066FF auf. Sonst muss sich nichts ändern.

Light-, Dark- und Brand-Modes

Die drei Modes, die die meisten Variablen-Systeme brauchen, sind Light, Dark und Brand. Nur die Semantic-Ebene trägt sie. Nie die Primitive-Ebene.

Modes auf Primitive anzuwenden ist ein Kategorienfehler. blue-500 ist immer #0066FF. Es ist ein Primitive. Es hat keine Light- oder Dark-Variante, weil es keine Bedeutung trägt. Das Semantic-Token text-link hat eine Light- und eine Dark-Variante, weil es Bedeutung trägt, die in verschiedenen Kontexten unterschiedlich aufgelöst wird.

Brand-Modes funktionieren genauso. Eine zweite Marke braucht keine zweite Primitive-Palette, es sei denn, die Marke nutzt wirklich andere Rohwerte. Meistens ist ein Brand-Mode in der Semantic-Ebene, der auf eine andere Teilmenge bestehender Primitive zeigt, die richtige Wahl. Zwei vollständige Primitive-Collections für zwei Marken sind meist übertrieben. Wie Farbentscheidungen weiter oben in der Kette das prägen, erfährst du im Beitrag zum Dark-Mode-Farbsystem, den du lesen solltest, bevor du die Struktur deiner Semantic-Ebene festlegst.

Number-, String- und Boolean-Variablen

Figma-Variablen sind nicht nur Farben. Number-Variablen steuern Abstand, Größen und Radius. String-Variablen steuern Texte in Designdateien. Boolean-Variablen steuern die Sichtbarkeit von Ebenen, was direkt auf Komponenten-Props abbildet.

Das ist der Teil des Variablen-Systems, den die meisten Teams nicht nutzen, und er schließt die Lücke zwischen Design und Code am dramatischsten. Eine Abstandsskala, die als Number-Variablen definiert und auf Auto-Layout-Gaps angewendet wird, bedeutet: Eine Änderung der Variable aktualisiert jede Komponente, die dieses Token nutzt. Das ist es, was ein echtes Token-System tut.

String-Variablen mit Locale-Modes lassen Designer eine Datei zwischen Englisch und Arabisch umschalten und das Layout in Echtzeit brechen sehen. Boolean-Variablen, die auf Komponenten-Props abbilden, bedeuten: Die Figma-Komponente und die Code-Komponente haben eine Eins-zu-eins-Prop-Beziehung, wodurch der Dev-Handoff überprüfbar statt interpretierbar wird.

Handoff in den Code: das Muster, das funktioniert

Ein Variablen-System ist nur so gut wie sein Export. Das funktionierende Handoff-Muster ist Tokens Studio oder die Figma Variables REST API, plus eine Transform-Pipeline, plus ein Import-Skript auf der Code-Seite.

Tokens Studio exportiert Variablen-Collections in ein strukturiertes JSON-Format, das mit Style Dictionary kompatibel ist. Style Dictionary wandelt dieses JSON in jede Ausgabe um, die die Codebasis braucht: CSS Custom Properties, Swift-Color-Sets, Kotlin-Ressourcendateien, Tailwind-Config. Im Transform-Schritt werden Namenskonventionen normalisiert und alle Figma-spezifischen Namen, die nicht auf Code-Konventionen passen, bereinigt.

Die Pipeline sollte bei jedem Variablen-Update laufen, nicht manuell. Eine GitHub Action, die bei einem Tokens-Studio-Push triggert, oder ein Figma-Webhook, der bei Variablenänderungen feuert, hält die Tokens auf der Code-Seite synchron, ohne dass jemand daran denken muss zu exportieren. Dieses Muster betreiben Stripe und Atlassian im großen Maßstab, und es ist in jeder Codebasis mit Build-Schritt machbar. Für Format-Entscheidungen bei Farb-Tokens in dieser Ausgabe lohnt sich OKLCH-Farbe, bevor du CSS-Custom-Property-Werte festlegst.

---

Du willst ein Figma-Variablen-System, das Modes, Marken und Dev-Handoff ohne Rewrites übersteht? Brainy entwirft produktionsreife Token-Architekturen in Figma mit dem Drei-Ebenen-Modell, der Alias-Kette und der Export-Pipeline, die sauber in deine Codebasis passt. Brainy beauftragen

---

Sieben häufige Fehler, die Variablen-Systeme brechen

Die meisten dieser Fehler haben dieselbe Ursache: Das Variablen-Panel wird als besseres Styles-Panel behandelt statt als Architekturebene. Der Wechsel des Mental Models ist die Lösung. Alles andere folgt daraus.

Das Variablen-System-Audit

Lass dieses Audit über jedes Figma-Variablen-System laufen, und du erwischst die Architekturschulden, bevor sie live gehen.

Struktur

• Mindestens drei Collections: Primitive, Semantic, Component (oder gleichwertige Benennung)
• Jede Collection hat genau eine klare Zuständigkeit
• Keine Collection mischt Typen (Farbe und Abstand in derselben Collection ist ein Fehler)

Alias-Kette

• Jedes Component-Token aliasiert auf ein Semantic-Token, nicht auf ein Primitive
• Jedes Semantic-Token aliasiert auf ein Primitive, nicht auf ein anderes Semantic-Token
• Kein Token hält einen rohen Wert außer Primitive
• Die Alias-Kettenlänge beträgt für alle Farb-Tokens genau drei

Modes

• Light und Dark sind Modes in der Semantic-Collection, keine getrennten Collections
• Brand-Varianten sind Modes in der Semantic-Collection, keine getrennten Dateien
• Die Primitive-Collection hat keine Modes

Scoping

• Primitive Variablen haben Scope none (nirgendwo anwendbar)
• Semantic-Variablen sind auf ihren Typ gescoped (Farbe auf Fills/Strokes, Abstand auf Layout-Felder)
• Component-Variablen sind auf ihre Komponentenfamilie gescoped

Handoff

• Variablen sind über Tokens Studio oder die REST API exportierbar
• Eine Transform-Pipeline existiert und ist automatisiert
• Tokens auf der Code-Seite entsprechen der Figma-Variablen-Namenskonvention, mit dokumentierten Ausnahmen

Wenn mehr als drei davon durchfallen, braucht das System einen Neuaufbau, keinen Patch. Eine Markenfarbpalette deckt die Farbentscheidungen weiter oben ab, die in die Primitive-Ebene einfließen, falls das Audit dort die meisten Schulden aufdeckt.

FAQ

Was ist der Unterschied zwischen Figma-Variablen und Figma-Styles?

Styles sind Presets, die direkt auf Ebenen angewendet werden. Variablen sind Tokens, die aufeinander verweisen und Werte über Modes umschalten können. Variablen können alles, was Styles können, plus Theming, plus Dev-Handoff per Export. Für ein neues Design System sind Variablen die richtige Wahl. Für eine bestehende Datei mit ausgereiftem Style-System lohnt es sich, vor dem Wechsel einen Migrationsplan zu schreiben.

Wie viele Collections sollte ein Figma-Variablen-System haben?

Drei bis fünf für die meisten Systeme: Primitive, Semantic, Component und optional separate Abstands- und Typografie-Collections, wenn diese Skalen komplex genug für eigene Scoping-Regeln sind. Mehr als fünf Collections sind meist ein Zeichen dafür, dass Zuständigkeiten nicht richtig gruppiert werden.

Können Figma-Variablen Tokens Studio ersetzen?

Für das Erstellen und Bearbeiten innerhalb von Figma: ja. Das native Variablen-Panel erledigt das meiste von dem, was Tokens Studio vor dem Start der Variables API getan hat. Für Export und Transform bringt Tokens Studio weiterhin Mehrwert, weil es eine ausgereifte Pipeline zu Style Dictionary hat und Randfälle abdeckt, die der native Export nicht kann. Die beiden Tools ergänzen sich derzeit, sie konkurrieren nicht.

Was passiert, wenn ich ein Semantic-Token auf ein anderes Semantic-Token aliasiere?

Die Mode-Auflösung wird mehrdeutig. Wenn text-secondary auf text-primary aliasiert und du in den Dark Mode wechselst, löst Figma die Kette auf und wendet den Dark-Mode-Override womöglich nicht dort an, wo du ihn erwartest. Semantic-zu-Semantic-Aliasing macht außerdem das Auditieren des Systems im großen Maßstab nahezu unmöglich. Die Regel ist hart: Semantic-Tokens aliasieren nur auf Primitive.

Wie gehe ich mit einer dritten Marke um, ohne das System neu aufzubauen?

Füge der Semantic-Collection einen dritten Mode hinzu. Die Primitive-Collection wird von allen Marken geteilt, es sei denn, die Marken nutzen wirklich unterschiedliche Rohwerte. Ein Brand-Mode in der Semantic-Ebene, der auf eine andere Teilmenge von Primitiven zeigt, ist die richtige Architektur. Sind die Marken so verschieden, dass sich ihre Primitive-Paletten nicht überlappen, sind zwei Primitive-Collections mit gemeinsamer Semantic-Struktur der Fallback.

Ist das Drei-Ebenen-Modell für kleine Projekte nötig?

Ja, aber jede Ebene wird kleiner. Ein kleines Projekt hat vielleicht fünfzehn Primitive, acht Semantic-Tokens und zwei Component-Tokens pro Komponente. Die Architektur bleibt trotzdem dreischichtig. Die Versuchung, Semantic bei kleinen Projekten zu überspringen, ist der Grund, warum so viele kleine Projekte in dem Moment zu Architekturschulden werden, in dem ein zweiter Designer oder ein Dark-Mode-Wunsch auftaucht. Wie die Token-Architektur in die breitere Stack-Entscheidung passt, dazu liefert der Beitrag Framer vs Webflow vs Next.js Kontext.

Der Wandel, den Figma-Variablen tatsächlich freischalten

Ein echtes Variablen-System in Figma ist das Nächste, was Design und Entwicklung an eine Single Source of Truth herangebracht hat. Kein Handoff-Dokument. Kein Zeplin-Link. Eine lebendige, exportierbare, strukturierte Token-Ebene, die beide Seiten aus denselben Definitionen lesen.

Die Teams, die Variablen als Architektur behandeln, halbieren ihre Design-System-Schulden, nicht weil Variablen Magie wären, sondern weil die architektonische Disziplin, die ein gutes Variablen-System verlangt, auch die Entscheidungen erzwingt, die Design Systems ständig aufgeschoben haben. Was bedeutet dieses Token? Worauf darf es aliasieren? Wem gehört das Primitive? Diese Fragen haben jetzt Antworten, und die Antworten leben in der Datei.

Variablen ohne Architektur sind nur Styles mit zusätzlichen Klicks. Variablen mit dem Drei-Ebenen-Modell, der Alias-Kette, den Scoping-Regeln und der Export-Pipeline sind ein Design System, das eine zweite Marke, einen Dark Mode und einen Entwickler übersteht, der Figma nie geöffnet hat.

Bau die Architektur, nicht nur die Tokens.