Token Architecture

Search intent: design tokens color design system token architecture semantic tokens primitive tokens color variables figma tokens design system color guide

Design Token Architecture for Color: Building Scalable, Maintainable Systems

A well-structured token architecture makes color systems easier to maintain, theme, and evolve. The three-tier model — primitive, semantic, component — provides the foundation for color systems that survive rebrands, multi-theme requirements, and team scale.

Design TokensDesign SystemsArchitecture

Key points

The three-tier token architecture (primitive → semantic → component) enables brand refreshes through a single file change — components never reference raw color values, only roles.

Token naming should encode design intention (action-primary, surface-default) rather than color values (blue-500, gray-100) — names should communicate what a token is for, not what color it currently holds.

Figma Variables and automated token pipelines enable bidirectional sync between design files and production code — eliminating the translation errors that occur when developers manually transcribe color values.

The three-tier model

Color token architecture organizes tokens into three tiers. The primitive tier holds raw color values with no semantic meaning — cobalt-500, amber-300, neutral-100. The semantic tier maps primitives to roles — text-primary maps to neutral-900, surface-default maps to neutral-50, action-primary maps to cobalt-500. The component tier maps semantic tokens to specific UI elements — button-background maps to action-primary, card-border maps to border-subtle. When the brand palette changes, only the semantic-to-primitive mapping needs to update. Component code is never touched. This architecture requires more upfront structure but creates dramatically lower maintenance cost over a system's lifetime.

Token naming principles

Token naming is a consequential design decision that most teams underestimate. Names that encode color values (gray-100, blue-500) are quick to define but create ambiguity about intent — the same blue-500 might be used as an action color in buttons and as a decorative color in illustrations, and the name provides no guidance about which uses are correct. Names that encode role (action-primary, interactive-default, text-heading) communicate intent precisely but can become verbose. The practical rule: semantic and component tokens should have role-based names; primitive tokens can have value-based names since they carry no intent themselves.

Multi-mode and multi-theme support

The semantic tier is where theme variation lives. For dark mode, define an alternate semantic-to-primitive mapping that uses different primitive values for the same roles: surface-default maps to neutral-900 in dark mode instead of neutral-50. For brand variants or white-label products, define alternate primitive tiers with different hue families, with the semantic and component tiers remaining unchanged. This architecture means a single component codebase can support unlimited visual variations through token set switching — a significant maintenance advantage over component-level theming.

Tooling and pipeline

Figma Variables (native) and Tokens Studio (plugin) are the primary tools for managing token systems in design files. Both support multi-mode definitions and JSON export. The critical engineering requirement is an automated pipeline from token JSON to production code — a build step that converts token definitions into CSS custom properties, Tailwind configuration, or framework-specific variables. Any change in the design file should propagate to production automatically. Manual transcription of token values from design tools to code is a reliability and velocity liability that the pipeline eliminates.

Practical next step

Move from the guide into a concrete palette lane

Guides explain the use case. Collections prove the taste. Packs handle the export and implementation layer.

Browse packs More guides

Related guides

Design Systems

Color Token Naming Conventions: Primitive, Semantic, and Component Layers

How to structure a three-layer token naming system that scales from a small product to a multi-brand design system — with practical naming patterns used by leading teams.

Design Systems

Color Token Architecture: Building Maintainable Design Token Systems

A poorly designed token architecture makes dark mode a two-week rebuild. A well-designed one makes it a two-hour configuration change. This guide covers the structural principles — primitive, semantic, and component tier design — that determine how maintainable your color system is over time.

Design Systems Guide

How to Build a Color Token System: The Complete Designer's Guide

A color token system is the infrastructure layer between your abstract brand palette and the code that implements it. Tokens translate color decisions into reusable, maintainable variables that can be updated globally, themed, and exported to any platform. Building a token system is not about adding complexity — it is about removing the hidden complexity that accumulates when colors are hard-coded directly into components.