I've seen design systems die for many reasons. Lack of governance. Team turnover. Partial adoption by engineers. But over the past two years I've identified a recurring pattern in the ones that collapse fastest: they have flat tokens, no semantics, built to look organized without actually being so.
A file with 200 CSS variables named --color-blue-500, --color-blue-600, and so on is not a design system. It's a palette with a different name. And when the request comes in to support dark mode, a second brand, or a low-vision accessibility theme, that file becomes a serious problem.
The three-tier hierarchy that works
The model I use across all my enterprise projects has three distinct tiers, with separate responsibilities and clear dependency rules.
Tier 1 — Primitives. These are raw values: exact colors, sizes, typefaces, durations. They carry no semantic meaning. They are the raw vocabulary of the system. Primitive tokens are never used directly in components — they exist only to be referenced by the next tier.
Tier 2 — Semantic tokens. This is where the magic happens. Semantic tokens map primitives to interface meanings. They don't describe a color — they describe a function: --color-background-default, --color-text-primary, --color-border-subtle. In dark mode, the value of --color-background-default changes, but every component using that token updates automatically — without touching a single component file.
Tier 3 — Component tokens. Specific to a single component or pattern. --button-primary-background points to --color-action-primary, which in turn points to the correct primitive for the active theme. This tier is optional for small systems, but becomes indispensable with multi-brand.
The problem with aliases that lack semantics
Many teams implement something that looks like a three-tier system but is really just one tier deep. An alias like --brand-primary: var(--color-blue-600) is not a semantic token — it's an alias. It doesn't describe a function in the interface; it just gives a specific color a shorter name.
If I have to explain what a token does, the name is wrong.
The difference becomes clear the moment you try to build an alternative theme. If a button uses --brand-primary as its background, what happens when the second brand uses red as its primary color? The correct semantic token is --color-action-primary-background: it describes the function, the role, and can be mapped to any primitive in any theme without breaking anything.
A practical naming structure
The naming convention I use follows this pattern: category — property — variant — state. Not every segment is always needed, but the order is always the same.
--color-background-default— category: color, property: background, variant: default--color-text-on-primary— text sitting on top of a primary-background element--color-border-focus— border in the focus state (for WCAG accessibility)--size-spacing-md— medium-scale spacing--duration-interaction-fast— duration for quick interactions
The guiding principle is that a semantic token name should be readable by a designer and a developer alike, without any additional context.
Dark mode without overriding everything
The practical payoff of a semantic hierarchy shows up most clearly with dark mode. Instead of overriding every individual CSS variable with hundreds of exceptions, you only redefine the mapping between semantic tokens and primitives.
Components don't change — they always reference the same semantic token. The dark theme is simply a substitution layer at Tier 2, not a rewrite of component CSS. With this approach, on a system with 60 components, the dark theme CSS takes fewer than 80 lines.
Multi-brand in production
On the Exein project I had to manage three brands with very different visual identities on the same component system. The solution was to build semantic tokens in a brand-neutral way — they describe functions, not identities — and author a separate theme file for each brand.
A well-designed semantic token has no idea which brand it belongs to. It only knows what it needs to do in the interface.
The practical result: adding a fourth brand took less than half a day. Create a primitives file, map it to the existing semantic tokens, verify WCAG contrast ratios. Zero changes to components.
Tooling in 2026
Token Studio for Figma remains the reference for the design-to-development bridge. Amazon's Style Dictionary is the most flexible tool for distributing tokens as CSS, JSON, Swift, and Kotlin. But the choice of tooling comes after the choice of architecture. A poorly designed system doesn't become a good one by switching software.
If you're redesigning your design system or building one from scratch, I can help you establish the right structure before it becomes too costly to change.
Ho visto i design system morire per molte ragioni. Mancanza di governance. Ricambio del team. Adozione parziale da parte degli ingegneri. Ma negli ultimi due anni ho identificato un pattern ricorrente in quelli che crollano più velocemente: hanno token piatti, nessuna semantica, costruiti per sembrare organizzati senza esserlo davvero.
Un file con 200 variabili CSS chiamate --color-blue-500, --color-blue-600 e così via non è un design system. È una palette con un altro nome. E quando arriva la richiesta di supportare il dark mode, un secondo brand o un tema di accessibilità per ipovedenti, quel file diventa un problema serio.
La gerarchia a tre livelli che funziona
Il modello che uso in tutti i miei progetti enterprise ha tre livelli distinti, con responsabilità separate e regole di dipendenza chiare.
Livello 1 — Primitivi. Sono valori grezzi: colori esatti, dimensioni, font, durate. Non portano nessun significato semantico. Sono il vocabolario grezzo del sistema. I token primitivi non vengono mai usati direttamente nei componenti — esistono solo per essere referenziati dal livello successivo.
Livello 2 — Token semantici. Qui avviene la magia. I token semantici mappano i primitivi ai significati dell'interfaccia. Non descrivono un colore — descrivono una funzione: --color-background-default, --color-text-primary, --color-border-subtle. In dark mode, il valore di --color-background-default cambia, ma ogni componente che usa quel token si aggiorna automaticamente — senza toccare un singolo file di componente.
Livello 3 — Token di componente. Specifici per un singolo componente o pattern. --button-primary-background punta a --color-action-primary, che a sua volta punta al primitivo corretto per il tema attivo. Questo livello è opzionale per sistemi piccoli, ma diventa indispensabile con il multi-brand.
Il problema degli alias privi di semantica
Molti team implementano qualcosa che sembra un sistema a tre livelli ma è in realtà un solo livello di profondità. Un alias come --brand-primary: var(--color-blue-600) non è un token semantico — è un alias. Non descrive una funzione nell'interfaccia; dà solo a un colore specifico un nome più corto.
Se devo spiegare cosa fa un token, il nome è sbagliato.
La differenza emerge nel momento in cui si prova a costruire un tema alternativo. Se un pulsante usa --brand-primary come sfondo, cosa succede quando il secondo brand usa il rosso come colore primario? Il token semantico corretto è --color-action-primary-background: descrive la funzione, il ruolo, e può essere mappato su qualsiasi primitivo in qualsiasi tema senza rompere nulla.
Una struttura di naming pratica
La convenzione di naming che uso segue questo pattern: categoria — proprietà — variante — stato. Non ogni segmento è sempre necessario, ma l'ordine è sempre lo stesso.
--color-background-default— categoria: colore, proprietà: sfondo, variante: default--color-text-on-primary— testo posizionato sopra un elemento con sfondo primario--color-border-focus— bordo nello stato di focus (per l'accessibilità WCAG)--size-spacing-md— spaziatura a scala media--duration-interaction-fast— durata per interazioni rapide
Il principio guida è che il nome di un token semantico deve essere leggibile da un designer e da uno sviluppatore allo stesso modo, senza nessun contesto aggiuntivo.
Dark mode senza sovrascrivere tutto
Il beneficio pratico di una gerarchia semantica emerge più chiaramente con il dark mode. Invece di sovrascrivere ogni singola variabile CSS con centinaia di eccezioni, si ridefinisce solo il mapping tra token semantici e primitivi.
I componenti non cambiano — referenziano sempre lo stesso token semantico. Il tema scuro è semplicemente un layer di sostituzione al livello 2, non una riscrittura del CSS dei componenti. Con questo approccio, su un sistema con 60 componenti, il CSS del tema scuro occupa meno di 80 righe.
Multi-brand in produzione
Nel progetto Exein ho dovuto gestire tre brand con identità visive molto diverse sullo stesso sistema di componenti. La soluzione è stata costruire i token semantici in modo brand-neutral — descrivono funzioni, non identità — e creare un file di tema separato per ciascun brand.
Un token semantico ben progettato non sa a quale brand appartiene. Sa solo cosa deve fare nell'interfaccia.
Il risultato pratico: aggiungere un quarto brand ha richiesto meno di mezza giornata. Creare un file di primitivi, mapparlo sui token semantici esistenti, verificare i rapporti di contrasto WCAG. Zero modifiche ai componenti.
Il tooling nel 2026
Token Studio per Figma rimane il riferimento per il ponte design-sviluppo. Style Dictionary di Amazon è lo strumento più flessibile per distribuire i token come CSS, JSON, Swift e Kotlin. Ma la scelta del tooling viene dopo la scelta dell'architettura. Un sistema mal progettato non diventa buono cambiando software.
Se stai ridisegnando il tuo design system o stai costruendone uno da zero, posso aiutarti a stabilire la struttura giusta prima che diventi troppo costoso cambiarla.
我见过设计系统以多种原因死亡。缺乏治理、团队人员流动、工程师部分采用。但过去两年，我在那些崩溃最快的系统中发现了一个反复出现的模式：它们有扁平的token、没有语义，构建得看起来有组织，实则并非如此。
一个包含200个CSS变量的文件，命名为--color-blue-500、--color-blue-600等等，不是设计系统。它只是一个换了名字的调色板。当支持暗色模式、第二品牌或低视力无障碍主题的需求到来时，那个文件就成了严重的问题。
有效的三层层级
我在所有企业项目中使用的模型有三个不同层级，各有独立职责和清晰的依赖规则。
第一层 — 原始值（Primitives）。这些是原始值：精确的颜色、尺寸、字体、时长。它们不携带任何语义含义。它们是系统的原始词汇。原始token从不直接在组件中使用——它们只存在于被下一层引用。
第二层 — 语义token（Semantic tokens）。这是魔法发生的地方。语义token将原始值映射到界面含义。它们不描述一个颜色——它们描述一个功能：--color-background-default、--color-text-primary、--color-border-subtle。在暗色模式下，--color-background-default的值改变，但每个使用该token的组件会自动更新——无需触碰任何组件文件。
第三层 — 组件token（Component tokens）。特定于单个组件或模式。--button-primary-background指向--color-action-primary，后者再指向当前主题的正确原始值。这一层对小型系统是可选的，但在多品牌场景中变得不可或缺。
缺乏语义的别名问题
许多团队实现了看起来像三层系统的东西，但实际上只有一层深度。像--brand-primary: var(--color-blue-600)这样的别名不是语义token——它只是一个别名。它不描述界面中的功能；它只是给一个特定颜色起了个更短的名字。
如果我需要解释一个token是做什么的，那名字就是错的。
当你尝试构建替代主题时，差异就清晰了。如果一个按钮使用--brand-primary作为背景，当第二个品牌使用红色作为主色时会发生什么？正确的语义token是--color-action-primary-background：它描述功能、角色，可以在任何主题中映射到任何原始值而不破坏任何东西。
实用的命名结构
我使用的命名约定遵循这个模式：类别 — 属性 — 变体 — 状态。不是每个片段都总是需要的，但顺序始终相同。
--color-background-default— 类别：颜色，属性：背景，变体：默认--color-text-on-primary— 位于主色背景元素上方的文本--color-border-focus— 焦点状态下的边框（用于WCAG无障碍）--size-spacing-md— 中等间距--duration-interaction-fast— 快速交互的时长
指导原则是：语义token名称应该对设计师和开发者都同样可读，无需任何额外背景。
暗色模式无需覆盖一切
语义层级的实际价值在暗色模式中最为清晰。无需用数百个例外覆盖每个单独的CSS变量，你只需重新定义语义token与原始值之间的映射。
组件不会改变——它们始终引用相同的语义token。暗色主题只是第二层的一个替换层，而不是组件CSS的重写。用这种方法，在一个有60个组件的系统中，暗色主题CSS不到80行。
生产中的多品牌
在Exein项目中，我需要在同一个组件系统上管理三个视觉标识截然不同的品牌。解决方案是以品牌中立的方式构建语义token——它们描述功能，而非标识——并为每个品牌编写一个独立的主题文件。
一个设计良好的语义token不知道自己属于哪个品牌。它只知道自己在界面中需要做什么。
实际结果：添加第四个品牌花了不到半天。创建一个原始值文件，将其映射到现有的语义token，验证WCAG对比度比值。零组件修改。
2026年的工具链
Token Studio for Figma仍然是设计到开发桥梁的参考工具。亚马逊的Style Dictionary是以CSS、JSON、Swift和Kotlin分发token的最灵活工具。但工具的选择在架构选择之后。一个设计不良的系统不会因为换软件而变好。
如果你正在重新设计你的设计系统或从头开始构建一个，我可以帮助你在更改成本太高之前建立正确的结构。
Ich habe Design Systems aus vielen Gründen scheitern sehen. Fehlende Governance. Teamfluktuation. Unvollständige Adoption durch Entwickler. Aber in den letzten zwei Jahren habe ich ein wiederkehrendes Muster bei den schnellsten Zusammenbrüchen identifiziert: Sie haben flache Tokens, keine Semantik, aufgebaut um organisiert auszusehen, ohne es wirklich zu sein.
Eine Datei mit 200 CSS-Variablen namens --color-blue-500, --color-blue-600 und so weiter ist kein Design System. Es ist eine Palette mit einem anderen Namen. Und wenn die Anforderung kommt, Dark Mode, eine zweite Marke oder ein Barrierefreiheits-Theme für Sehbehinderte zu unterstützen, wird diese Datei zu einem ernsthaften Problem.
Die Drei-Ebenen-Hierarchie, die funktioniert
Das Modell, das ich in all meinen Enterprise-Projekten verwende, hat drei verschiedene Ebenen mit getrennten Verantwortlichkeiten und klaren Abhängigkeitsregeln.
Ebene 1 — Primitives. Das sind rohe Werte: exakte Farben, Größen, Schriften, Dauern. Sie tragen keine semantische Bedeutung. Sie sind das rohe Vokabular des Systems. Primitive Tokens werden nie direkt in Komponenten verwendet — sie existieren nur, um von der nächsten Ebene referenziert zu werden.
Ebene 2 — Semantische Tokens. Hier geschieht die Magie. Semantische Tokens bilden Primitives auf Interface-Bedeutungen ab. Sie beschreiben keine Farbe — sie beschreiben eine Funktion: --color-background-default, --color-text-primary, --color-border-subtle. Im Dark Mode ändert sich der Wert von --color-background-default, aber jede Komponente, die diesen Token verwendet, aktualisiert sich automatisch — ohne eine einzige Komponentendatei anzufassen.
Ebene 3 — Komponenten-Tokens. Spezifisch für eine einzelne Komponente oder ein Muster. --button-primary-background zeigt auf --color-action-primary, was wiederum auf das korrekte Primitive für das aktive Theme zeigt. Diese Ebene ist für kleine Systeme optional, wird aber bei Multi-Brand unverzichtbar.
Das Problem mit semantiklosen Aliasen
Viele Teams implementieren etwas, das wie ein Drei-Ebenen-System aussieht, aber in Wirklichkeit nur eine Ebene tief ist. Ein Alias wie --brand-primary: var(--color-blue-600) ist kein semantischer Token — es ist ein Alias. Er beschreibt keine Funktion im Interface; er gibt einer bestimmten Farbe nur einen kürzeren Namen.
Wenn ich erklären muss, was ein Token tut, ist der Name falsch.
Der Unterschied wird klar, sobald man versucht, ein alternatives Theme zu bauen. Wenn ein Button --brand-primary als Hintergrund verwendet, was passiert, wenn die zweite Marke Rot als Primärfarbe hat? Der korrekte semantische Token ist --color-action-primary-background: er beschreibt die Funktion, die Rolle, und kann in jedem Theme auf jedes Primitive abgebildet werden, ohne etwas zu brechen.
Eine praktische Namensstruktur
Die Namenskonvention, die ich verwende, folgt diesem Muster: Kategorie — Eigenschaft — Variante — Zustand. Nicht jedes Segment wird immer benötigt, aber die Reihenfolge ist immer gleich.
--color-background-default— Kategorie: Farbe, Eigenschaft: Hintergrund, Variante: Standard--color-text-on-primary— Text auf einem Element mit primärem Hintergrund--color-border-focus— Rahmen im Fokuszustand (für WCAG-Barrierefreiheit)--size-spacing-md— Mittlerer Abstand--duration-interaction-fast— Dauer für schnelle Interaktionen
Das Leitprinzip ist, dass ein semantischer Token-Name von einem Designer und einem Entwickler gleichermaßen gelesen werden kann, ohne zusätzlichen Kontext.
Dark Mode ohne alles zu überschreiben
Der praktische Nutzen einer semantischen Hierarchie zeigt sich am deutlichsten beim Dark Mode. Statt jede einzelne CSS-Variable mit Hunderten von Ausnahmen zu überschreiben, definiert man nur die Zuordnung zwischen semantischen Tokens und Primitives neu.
Komponenten ändern sich nicht — sie referenzieren immer denselben semantischen Token. Das Dark Theme ist einfach eine Substitutionsschicht auf Ebene 2, keine Neufassung des Komponenten-CSS. Mit diesem Ansatz benötigt das Dark-Theme-CSS bei einem System mit 60 Komponenten weniger als 80 Zeilen.
Multi-Brand in der Produktion
Im Exein-Projekt musste ich drei Marken mit sehr unterschiedlichen visuellen Identitäten auf demselben Komponentensystem verwalten. Die Lösung bestand darin, semantische Tokens markenneutral aufzubauen — sie beschreiben Funktionen, keine Identitäten — und für jede Marke eine separate Theme-Datei zu erstellen.
Ein gut gestalteter semantischer Token weiß nicht, zu welcher Marke er gehört. Er weiß nur, was er im Interface leisten muss.
Das praktische Ergebnis: Eine vierte Marke hinzuzufügen dauerte weniger als einen halben Tag. Eine Primitives-Datei erstellen, sie auf die bestehenden semantischen Tokens abbilden, WCAG-Kontrastverhältnisse prüfen. Null Änderungen an Komponenten.
Tooling 2026
Token Studio für Figma bleibt die Referenz für die Design-Entwicklungs-Brücke. Amazons Style Dictionary ist das flexibelste Tool zur Verteilung von Tokens als CSS, JSON, Swift und Kotlin. Aber die Wahl des Toolings kommt nach der Wahl der Architektur. Ein schlecht gestaltetes System wird durch einen Software-Wechsel nicht besser.
Wenn Sie Ihr Design System neu gestalten oder von Grund auf neu aufbauen, kann ich Ihnen helfen, die richtige Struktur festzulegen, bevor eine Änderung zu teuer wird.