Design and engineering teams waste an enormous amount of time on the same problems: a designer updates a color in Figma and the change never makes it to code; a developer hard-codes a hex value that drifts from the style guide over the next six sprints; a new dark mode requirement arrives and the codebase has to be combed by hand. Design tokens exist to break that cycle.
What Design Tokens Actually Are
A design token is a named variable that stores a single design decision: a color, a typeface, a spacing unit, a border radius, a shadow. The name carries meaning. #1A2B3C is a hex value. color.text.primary is a decision.
That distinction matters more than it sounds. When a value is named by its role rather than its appearance, it can be changed globally in one place and that change propagates everywhere the token is referenced: in Figma, in CSS, in iOS Swift files, in Android XML, in React Native themes. The value is abstract; the token is the contract.
“A design token is a design decision stored in a way that code can consume. The token is the API between design and engineering.”
Design tokens are not a new idea. Salesforce’s Lightning Design System popularized the term around 2014, but the core idea of centralizing style decisions predates that by decades. What has changed is tooling: platforms like Style Dictionary, Tokens Studio for Figma, and the emerging W3C Design Tokens specification have made the practice accessible to teams that are not Salesforce.
The Three-Tier Model
Most mature token systems organize tokens into three tiers: primitives, semantics, and component tokens. Understanding all three is what separates a token system that scales from one that collapses under its own complexity.
Tier 1: Primitives
Primitives (also called global tokens or raw tokens) define the full design vocabulary with no semantic meaning attached. They are facts, not decisions.
color.palette.blue.500 = #1D4ED8
color.palette.blue.600 = #1E40AF
spacing.4 = 16px
font.size.lg = 1.125rem
border.radius.md = 6pxA well-formed primitive tier is exhaustive at the scales you need and nothing more. If your type scale has eight steps, the primitive tier names all eight. It does not name “button text” or “error state”; that is the next tier’s job.
Tier 2: Semantics
Semantic tokens give meaning to primitives. They answer the question: what is this value for?
color.text.primary → color.palette.neutral.900
color.text.inverse → color.palette.neutral.0
color.text.error → color.palette.red.600
color.surface.raised → color.palette.neutral.0Every semantic token references a primitive. No raw hex values at this layer. The payoff is theming: for a dark mode, you re-point the semantic tokens to different primitives. color.text.primary shifts from neutral.900 to neutral.50. Every component in the system picks up the correct value without any component-level change.
This is where most teams fail. They define a handful of semantic tokens and then litter their codebase with primitive references everywhere else. The result: theming requires hunting down hundreds of hard-coded values instead of swapping a mapping file.
Tier 3: Component Tokens
Component tokens are scoped to a specific UI element. They reference semantic tokens (almost never primitives directly) and give teams flexibility to tune a component without breaking the broader system.
button.primary.background → color.interactive.primary
button.primary.background.hover → color.interactive.primary.hover
button.primary.label → color.text.on-primary
input.border.default → color.border.subtle
input.border.focused → color.interactive.primaryComponent tokens are optional in small systems. They become essential when a product has multiple themes, a white-label requirement, or many component variants. They act as a controlled override mechanism, a way to say “this specific component is allowed to deviate here” without opening the door to ad-hoc decisions.
Naming Conventions That Hold Up
Token naming is where most systems get into trouble early and pay for it later. A few rules that survive real projects:
- Object-property-modifier pattern.
{category}.{property}.{modifier}, for examplecolor.text.secondaryorspacing.inset.sm. Consistent hierarchy makes tokens predictable. - Describe role, not value.
color.feedback.errorages better thancolor.red. When the brand red shifts to orange-red, the token name stays accurate. - Avoid device-specific names at the semantic layer.
color.text.primaryworks everywhere.color.ios.navigationBar.titlebelongs in a platform-specific extension, not the core system. - Limit depth. Four levels is usually the ceiling. Deeper hierarchies are hard to navigate and produce names nobody memorizes.
The W3C Design Tokens Community Group specification is worth tracking. It is not yet ratified, but it is converging on a standard JSON format that major tools already support. Building toward that format now means less migration work later.
Tokens and Theming: How It Works in Practice
Theming (dark mode, brand variants, high-contrast accessibility modes) is the clearest demonstration of why the three-tier model earns its complexity.
The mechanism is simple: you maintain one primitive tier (the full palette) and swap semantic mapping files per theme. At build time or runtime, each theme resolves semantic tokens to its own set of primitives. Components are authored against semantic tokens only. They are, by construction, theme-agnostic.
For a practical example: a product with a default light theme and a dark theme ships two mapping files. Light maps color.surface.default to white. Dark maps the same token to neutral.950. Every component that uses color.surface.default renders correctly in both themes. No component code changes. No conditional logic inside components. The design decision lives at the token layer, where it belongs.
Multi-brand products follow the same pattern with a third dimension: a brand mapping file sits above the semantic layer and points primitives at brand-specific palette values. This is how enterprise platforms support white-labeling without fracturing the component library.
Token Formats and Tooling
The practical question is always: where do tokens live and how do they get to the platforms that need them?
Style Dictionary (Amazon, open source) remains the industry default. You define tokens in JSON or YAML, write transforms and formatters, and generate outputs for CSS custom properties, Sass variables, Swift, Kotlin, JavaScript ES modules, or anything else you can write a formatter for. The config is code; the output is whatever you need.
Tokens Studio for Figma bridges the design file to the token repository. Designers work with named tokens in Figma rather than raw values. Changes sync to a JSON file (or directly to a GitHub repo), and Style Dictionary picks them up. This is the closest the industry currently gets to a live, bi-directional design-to-code link.
CSS custom properties are the native delivery mechanism for the web. A token like color.text.primary becomes --color-text-primary in the stylesheet. At the semantic layer, custom properties referencing other custom properties enable runtime theming. Swapping a class on the root element changes the entire visual system without a page reload or JavaScript state update.
Tokens in a Design System Context
Tokens are not a design system on their own. They are the foundation layer beneath a design system: the values that components, documentation, and design patterns are built on. A team can have design tokens without a full design system. No team should have a design system without tokens.
If you are evaluating whether a design system makes sense for your team’s stage and size, Design Systems for Lean Teams lays out the decision framework honestly, including when the overhead is not yet justified.
Tokens also connect directly to the handoff problem. The Figma-to-production gap (where design intent leaks or warps in translation) shrinks dramatically when both Figma and the codebase are driven by the same token set. That gap and how to close it is covered in detail in Figma to Production: Closing the Handoff Gap.
A token system is also an accessibility instrument. When semantic tokens encode roles such as color.text.primary, color.border.focus, and color.feedback.error, it becomes much easier to audit contrast ratios systematically and ensure every theme meets WCAG thresholds. Accessibility Is a Design Decision, Not a Checklist covers the broader principle.
Common Mistakes Worth Avoiding
Starting with component tokens. Teams often reach for component-level specificity before they have a coherent primitive and semantic layer. The result is a flat list of component overrides with no underlying structure. Start at the primitive layer and work down.
Token proliferation. More tokens is not better. A token that gets used in one place is just a variable. A token system earns its value through reuse and consistency. Audit regularly: tokens that are no longer referenced should be removed, not accumulated.
Skipping documentation. A token named color.interactive.focus-visible means something to the person who named it and nothing to the engineer joining the team six months later. Short descriptions alongside each token, covering what it is for and what it is not for, pay compound interest.
Coupling semantics to visual appearance. color.blue.interactive is a primitive masquerading as a semantic token. When the interactive color changes to green, the name becomes a lie. Keep semantic names role-based.
How Strynal Approaches Token Systems
At Strynal, token architecture is part of the UI/UX design process from the first week of an engagement, not a retrofit at the end. Every interface we design and build starts from a blank page, with no templates or reused Figma libraries from a previous client, so the token system reflects the specific visual language of that brand, not a generic boilerplate.
When strategy, brand, and build sit under one roof, the feedback loop between decisions that happen in design and decisions that happen in code stays tight. That is where token systems prove their value most clearly: when the people defining the tokens and the people consuming them are working together continuously, not handing documents over a wall.
If you are building a product or brand system and want a token architecture that will hold up as the product scales, we would like to hear about it.