Design Tokens: A Practical Guide to Naming, Tiers, and the Figma-to-Code Workflow

Somewhere in your product right now, the same brand blue exists as a Figma style, three slightly different hex values in CSS, a Tailwind class, and an iOS asset — and at least one of them doesn't match. Design tokens exist to make that state impossible. They're the least glamorous part of a design system and the part everything else depends on.

Here's what this guide covers:

1. What design tokens actually are — and why they're not just variables
2. The three-tier architecture: reference, semantic, component
3. Naming rules that survive rebrands, themes, and new platforms
4. The 2026 toolchain: Figma Variables, Tokens Studio, Style Dictionary, and the W3C format
5. The seven mistakes that kill token adoption — and when tokens are overkill

What Design Tokens Actually Are

A design token is a single design decision — a color, a spacing step, a type size, a corner radius, a shadow — stored as named data instead of hardcoded into a design file or a stylesheet. color.action.primary: #2563EB is a token. The hex value pasted into forty components is the absence of one.

The distinction that trips people up is tokens versus variables. A CSS variable, a Sass variable, a Figma variable — each is one implementation of a token on one platform. The token itself lives upstream: a named decision in a data file that gets transformed into whatever each platform needs. That's the whole idea, and it's why the term was coined where it was — at Salesforce, where Jina Anne and the Lightning Design System team needed the same design decisions to reach web, iOS, Android, and partner platforms without anyone re-typing hex values. Their open-source tool Theo was the first token build system, and every modern pipeline is downstream of it.

"This was a way to store our visual information as data." — Jina Anne, who coined the term at Salesforce, on the Smashing Podcast

Store decisions as data and three expensive problems collapse into cheap ones. A rebrand becomes a value change in one file instead of a quarter-long hunt through two codebases. Dark mode becomes a second set of values instead of a parallel stylesheet. And design–code drift — the slow divergence where production stops matching Figma — loses its mechanism, because both sides read from the same source.

The Three-Tier Token Architecture

Token sets that survive growth are structured in tiers: reference tokens hold raw values, semantic tokens give them meaning, component tokens scope them to specific UI. Skipping the middle tier is the most common structural mistake; building the third tier too early is the second.

Reference tokens are your raw palette with no opinions attached: blue.600: #2563EB, gray.100: #F3F4F6, space.4: 16px. They answer "what values exist," never "where values go." This is the only tier where a name may describe a value.

Semantic tokens are where the system earns its keep. color.action.primary: {blue.600} — the token references a reference token and carries the meaning: this is the color of primary actions, wherever they appear. Theming happens entirely at this tier: dark mode is a second set of semantic values pointing at different references, and no component knows the difference. When your danger color changes from red to orange, color.text.danger doesn't change its name — only its target.

Component tokens scope decisions to a single component: button.primary.background: {color.action.primary}. They exist so that at scale, a team can restyle one component without touching the global vocabulary. Material Design 3 runs this exact cascade in public — md.ref palette tokens feed md.sys system tokens feed md.comp component tokens — and it's the most complete worked example you can study for free.

How Material, Atlassian, and the other major public systems run tiers at ecosystem scale is a story we've already told in our breakdown of twelve design system examples. The practical takeaway for a product team is simpler: you need the first two tiers from day one, and you almost certainly don't need the third until multiple teams ship against the same components. Two tiers is a system; one tier is a palette; three tiers before Series C is usually ceremony.

How to Name Design Tokens

Name tokens by purpose, never by value. This is the one rule that decides whether your token set is an asset or a renaming project waiting to happen — a token called red-600 is a fact about today; a token called color.text.danger is a decision that survives every future.

Beyond the one rule, four conventions keep a growing set coherent:

Follow a consistent anatomy. Most mature systems converge on something like category.concept.property.state: color.background.danger, color.border.focused, space.inset.lg. The exact segments matter less than never improvising them — a token vocabulary where every name parses the same way is one your team can guess correctly without opening the docs, and that guessability is what adoption actually feels like.

Put states last. color.action.primary.hovered, .pressed, .disabled. When states live at the end, tooling can group a token with its variants, and designers scanning an alphabetized list see families instead of fragments.

Keep value words out of the semantic tier entirely. The moment blue appears in a semantic token name, you've created a lie waiting to happen — the classic failure is a gray-blue-2 that renders green after a rebrand. Value words belong in the reference tier and nowhere else.

Keep names portable. In the W3C token format, dots express hierarchy and curly braces express references, so keep individual name segments to plain lowercase words and pick one case convention for the whole set. Renaming tokens later is possible — Atlassian famously migrated thousands of values to semantic names with codemods — but it's a project. Naming them right is a meeting.

The 2026 Toolchain: Figma Variables, Style Dictionary, and the W3C Format

The token toolchain has consolidated into three layers: Figma Variables where designers work, a version-controlled token file as the source of record, and Style Dictionary as the build step that turns one source into every platform's format. Five years ago this was a zoo of custom scripts; today it's close to a standard stack.

Figma Variables are the design-side implementation of tokens: reusable values in four types (color, number, string, boolean), organized into collections, with aliasing so a semantic variable can reference a palette variable — your tier structure, native in the design tool. Modes are the theming mechanism: one variable, multiple definitions, so a frame flips from light to dark without duplicating a single screen. Two practical notes: publishing variables to team libraries requires a paid plan, and adoption is no longer the question it was — Supernova's State of Design Tokens report found 69.8% of design teams already working with Figma Variables.

Tokens Studio is the Figma plugin that closes the gap Variables still leave: it manages tokens inside Figma while syncing them to a Git repository — GitHub, GitLab, Bitbucket, or Azure DevOps — and exporting through Style Dictionary. If your source of truth lives in the repo (it should — more below), Tokens Studio is the bridge that lets designers edit it without leaving Figma.

Style Dictionary is the build step: it takes one token source and exports it to "any platform" in its own words — CSS custom properties, a Tailwind theme, JavaScript constants, iOS and Android resources, documentation. Version 4 is forward-compatible with the W3C community format, which makes it the default answer to "how do tokens become code."

The Design Tokens Community Group format is the piece that makes the rest interchangeable: a W3C community specification for token files — .tokens.json, with $value and $type properties and {group.token} alias syntax. It's still a draft (latest published June 2026), so treat it as a converging standard rather than a finished one — but the direction is set, tools are aligning on it, and writing your tokens in it today is the cheapest insurance against ever being locked into one vendor's format.

The Figma-to-Code Workflow That Holds

Before choosing tools, make the one decision that determines whether the pipeline survives: where a token's value is allowed to change. One place per token; everything downstream is generated, never edited. Every token workflow that rotted — and we've audited plenty — rotted because a value could be changed in two places and nobody could say which one was true.

Our recommendation for product teams: the token file lives in the repository, and changes ship as pull requests. Git gives you review, history, versioning, and rollback for free — infrastructure a design tool can't replicate — and Tokens Studio's sync means designers still edit tokens from inside Figma. The pipeline ends up looking like this:

1. A designer changes color.action.primary in Figma — via Tokens Studio or a Variables export — which opens a pull request with a readable diff.
2. The team reviews the diff. This is the quiet superpower of the whole approach: design review becomes code review, and "why did the primary blue change" has a commit message.
3. CI runs Style Dictionary and regenerates every output — CSS variables, the Tailwind theme, native resources — so no platform can lag behind.
4. The change ships under a version number with a changelog entry. Tokens are a public contract with every surface of your product; breaking changes deserve the same ceremony as an API.

There's a 2026-specific reason to get this right that didn't exist three years ago: AI-assisted development. Cursor, Claude, v0 and their siblings generate UI from patterns, and without a token file they guess — plausible colors, almost-right spacing, a product that slowly stops looking like itself. With defined tokens in the codebase, the token file functions as a constraint set the AI works within. We've made the full argument in our design system decision guide; the short version is that a token file is now AI scaffolding, not just design infrastructure.

Seven Design Token Mistakes That Kill Adoption

Failed token projects fail the same seven ways — every one cheaper to prevent than to unwind.

1. Naming tokens after values

blue-500 as a semantic token means the first rebrand renames everything that references it. Value names belong in the reference tier only; if a name would become false when a value changes, it's the wrong name. This mistake is listed first because it's the one you can't lint your way out of later.

2. Tokenizing everything on day one

Teams discover tokens and mint four hundred of them in a week — five surface colors, twelve grays, tokens for decisions no one has made yet. Nobody adopts a vocabulary that large, so hardcoded values creep back and the set becomes fiction. Start with the 30–50 semantic tokens your actual UI needs; add the rest when a real component asks for them.

3. Letting Figma and code drift apart

If designers maintain Variables and engineers maintain a theme file and nothing connects them, you have two design systems that happen to agree today. Drift isn't a discipline problem, it's an architecture problem — it ends when one side is generated from the other, and not before.

4. Adding component tokens before component pain

button.primary.background earns its existence when multiple teams need to restyle components independently. Before that, it's indirection: three files to open where one semantic token would do. Let the component tier be pulled into existence by real needs, never pushed by completionism.

5. Changing tokens without rules

A token set with no change process becomes a token set nobody trusts. The fix is lightweight, not bureaucratic: changes go through review, breaking changes bump a version, deletions get a deprecation window. If that sounds like software release discipline, that's the point — tokens are a dependency of every surface you ship.

6. Letting raw values leak back in

The day one engineer ships #2563eb instead of the token, the file stops being the source of truth — entropy only runs one direction. Mature teams make the token path the easy path and lint the escape hatch shut: a stylelint or ESLint rule that flags raw hex values and magic numbers costs an afternoon and preserves the whole investment.

7. Treating dark mode as a redesign

If dark mode requires touching components, the token architecture failed — it's supposed to be a second set of semantic values, full stop. Teams that build dark mode as a parallel stylesheet pay for every future screen twice. Build the semantic tier first and themes become configuration; skip it and every theme is a fork.

When Design Tokens Are Overkill

A single-surface product with one theme and two people shipping it doesn't need a token pipeline — and pretending otherwise is how design systems get their reputation for ceremony. Jina Anne herself is on record that a straightforward editorial site may need nothing more than CSS variables. The person who coined the term gets to define its limits.

The honest heuristic parallels the rule of three we use for design system investment generally: a well-named Tailwind theme or CSS variable set is your token layer at small scale, and it's enough — until a specific trigger fires. Four triggers, in the order they usually arrive: a second surface (native app, marketing site, partner portal), a theming requirement (dark mode, white-label), the first time production visibly disagrees with Figma, and the adoption of AI codegen anywhere in your UI workflow. Each one converts tokens from ceremony into infrastructure. Until one fires, keep your values purpose-named and in one file — that habit is 80% of the migration, pre-paid.

Rolling Tokens Into an Existing Product

Almost nobody gets to start from a blank palette — the real project is retrofitting tokens into a product that's been shipping for years, and it follows the same arc every time. Inventory first: dump every color, spacing, and radius value in the codebase, and brace yourself — a typical Series A–B product carries a few hundred unique color values doing the work of about thirty decisions. Collapse those into a reference palette, define the semantic tier against your five most-used screens rather than in the abstract, then migrate leaf-first — newest components convert first, the lint rule from mistake #6 stops the bleeding, and the long tail converts opportunistically. No big bang, no freeze.

We've run this arc across 40+ B2B SaaS products, and the pattern holds from single-dashboard fintech products to multi-product platforms: the token layer is the highest-leverage week a design-engineering pair can spend, if it's sized to the stage. That sizing is what our Design System Readiness framework — Signal, Scope, Stack, Stewardship — exists to do, so a Series A team gets a token file and a pipeline, not an IBM-scale governance process.

If you know what you need and want to talk scope:

Talk to us about your design system →

Related: 12 Design System Examples Worth Studying · Do You Actually Need a Design System? · The Complete Guide to SaaS UI/UX Design · AI Product Design in 2026