Design tokens: the complete technical guide

What design tokens actually are

This article is part of our complete guide to Design Systems. Start there for the big picture.

According to the 2024 State of Design Systems report by Specify, 74% of mature design systems now use tokens as their primary method for distributing design decisions to code (Specify, 2024). Design tokens are named variables that store design decisions. Colors, spacing, typography, shadows, border radii, motion. They replace the hard-coded values scattered across your codebase with a single, centralized vocabulary.

Here’s the simplest way to think about it. Instead of a developer typing #2563EB in fourteen files, they reference a token called color-action-primary. When the brand color changes, you update one value in one file. Every screen reflects the change immediately.

“But that’s just CSS variables.” I hear this constantly. CSS custom properties solve the variable problem for the web. Design tokens solve it for everything: web, iOS, Android, email templates, documentation sites, even print assets. A token is platform-agnostic by definition. You write it once in JSON (or YAML, or a Figma plugin), and tooling transforms it into whatever each platform needs.

I remember the project that converted me. We had a React web app and a native iOS app sharing a brand. Every time the design team updated a color, two separate engineering teams made the change independently. One team would finish first. The other would lag by a sprint or two. For weeks, the apps looked like they belonged to different companies. Tokens eliminated that problem entirely. One source file, two automated outputs, zero drift.

Why tokens exist

The problem isn’t that developers forget values. The problem is that design decisions live in too many places at once. A Figma file says the primary button is #2563EB. A CSS file says it’s var(--blue-500). A Swift file says it’s UIColor(named: "brandBlue"). Three representations of the same decision, maintained by three people who may never talk to each other.

Tokens create a single source of truth for that decision. The token is the decision. Everything else is a derived output.

How does the three-tier token architecture work?

The W3C Design Tokens Community Group has been formalizing the token specification since 2019, and nearly every mature system that’s adopted it uses some form of tiered architecture (W3C DTCG, 2024). Three tiers is the most common structure: primitive, semantic, and component. Each layer adds context on top of the one below it.

Primitive tokens

These are raw values. No meaning, no context. Just the value itself.

{
  "color": {
    "blue-500": { "value": "#2563EB" },
    "blue-600": { "value": "#1D4ED8" },
    "gray-100": { "value": "#F3F4F6" },
    "gray-900": { "value": "#111827" }
  },
  "space": {
    "4": { "value": "16px" },
    "8": { "value": "32px" }
  }
}

Think of primitives as your palette. blue-500 doesn’t tell you what it’s for. It tells you what it looks like.

Semantic tokens

This is where intent enters the picture. Semantic tokens map meaning onto primitives.

{
  "color-action-primary": { "value": "{color.blue-500}" },
  "color-action-primary-hover": { "value": "{color.blue-600}" },
  "color-text-primary": { "value": "{color.gray-900}" },
  "color-bg-surface": { "value": "{color.gray-100}" },
  "spacing-component-gap": { "value": "{space.4}" }
}

Now the system knows that color-action-primary is for interactive elements. It doesn’t care that the underlying value is blue. It cares about the role.

Component tokens

The final layer scopes decisions to specific UI elements.

{
  "button-bg-primary": { "value": "{color-action-primary}" },
  "button-bg-primary-hover": { "value": "{color-action-primary-hover}" },
  "button-padding-x": { "value": "{space.4}" },
  "card-bg": { "value": "{color-bg-surface}" }
}

Component tokens make each component self-documenting. A developer reading button-bg-primary immediately knows what the token controls and where it applies.

Why the semantic layer matters most

Most token architectures fail at the semantic layer, not the primitive or component layers. Teams get the primitives right because primitives are just a list of values. They get component tokens right because those map directly to code. But semantic tokens require you to articulate the why behind every decision. That’s harder. And when teams skip it, they end up with component tokens pointing directly at primitives. The result? Every theme change touches hundreds of tokens instead of a handful.

I’ve seen teams rebrand a 200-screen product in under a week because their semantic layer was solid. I’ve also seen teams spend three months on a rebrand because they skipped it. The semantic layer is the difference.

What naming conventions should you use for design tokens?

A 2023 study by Knapsack found that teams with consistent token naming conventions resolved design-to-code handoff issues 38% faster than teams without naming standards (Knapsack, 2023). Naming is the single most underestimated part of a token system. A bad name creates ambiguity. Ambiguity creates inconsistency. And inconsistency is the exact problem tokens are supposed to solve.

The pattern that works

Most mature systems use kebab-case with a category-property-variant structure. Here are some examples:

• color-action-primary
• color-text-secondary
• spacing-component-gap
• font-size-heading-lg
• border-radius-sm
• shadow-elevation-low

The pattern reads left to right, from broad to specific. A developer scanning a list of tokens can group and filter by category without reading documentation.

Names that describe purpose, not appearance

This is where teams go wrong most often. Naming a token blue-button-bg locks you into a visual implementation. What happens when the brand color changes to green? Do you rename the token and break every file that references it? Or do you leave the name and confuse everyone because blue-button-bg now resolves to green?

Neither option is good. Name tokens by purpose instead. color-action-primary doesn’t care what color it is. It describes the role. The value can change; the name stays correct.

Naming for scale

When your system grows past a hundred tokens, naming discipline prevents chaos. Some practical rules:

Be predictable. If one color token is color-text-primary, don’t name another text-color-secondary. Keep the order consistent.

Use t-shirt sizes for relative values. spacing-xs, spacing-sm, spacing-md, spacing-lg. Don’t use numbers like spacing-1 unless you’re confident you won’t need something between spacing-1 and spacing-2.

Avoid abbreviations that aren’t universal. bg for background is fine. clr for color is not. When in doubt, spell it out.

How do design tokens enable theming and dark mode?

According to the Material Design 3 documentation, Google’s design system uses semantic token remapping to support light mode, dark mode, and dynamic color themes without modifying component logic (Material Design, 2024). Theming is the payoff for getting your token architecture right. If the semantic layer works, theming becomes a token swap.

How semantic swapping works

In light mode, your semantic tokens point to one set of primitives:

color-text-primary     -> gray-900
color-bg-surface       -> white
color-action-primary   -> blue-500

In dark mode, the same semantic tokens point to different primitives:

color-text-primary     -> gray-100
color-bg-surface       -> gray-900
color-action-primary   -> blue-400

Components never change. A button references color-action-primary. Whether that resolves to blue-500 or blue-400 depends on which theme is active. The component doesn’t know or care.

Multi-brand theming

The same principle scales to multi-brand scenarios. Say you’re building a white-label SaaS product. Brand A uses blue, Brand B uses purple, Brand C uses green. Each brand gets its own set of primitive tokens. The semantic layer stays identical. Components stay identical. You ship one codebase with multiple token sets.

On a project in 2024, we built a product platform serving four brands. The component library was 100% shared. Each brand’s identity came from a single JSON file containing about 60 primitive tokens. Adding a fifth brand took two hours, most of that spent picking the right shades. Zero component changes.

Beyond color: density and contrast modes

Theming isn’t limited to color. You can define spacing themes for compact versus comfortable density. High-contrast accessibility modes can remap both color and typography tokens. The architecture is the same: swap the semantic layer, keep everything else intact.

What tools do you need for design tokens?

The 2024 Design Tools Survey by UXTools reported that 61% of design teams using tokens rely on either Style Dictionary or Tokens Studio as their primary transformation pipeline (UXTools, 2024). Tooling is what turns token files from a nice idea into an automated pipeline.

Style Dictionary

Built by Amazon, Style Dictionary is the most established token transformation tool. You define tokens in JSON. Style Dictionary transforms them into platform-specific outputs: CSS custom properties, Sass variables, Swift asset catalogs, Android XML resources, and more.

The configuration is straightforward. You specify your source files, define output platforms, and run a build command. Style Dictionary handles all the format conversions.

Figma → JSON → Style Dictionary → CSS variables
                                 → iOS Swift constants
                                 → Android XML resources

Style Dictionary’s real strength is extensibility. You can write custom transforms for any output format. Need tokens as Tailwind config values? Write a formatter. Need them as Flutter constants? Same approach.

Tokens Studio

Tokens Studio (formerly Figma Tokens) works from the other direction. It’s a Figma plugin that lets designers create and manage tokens directly inside Figma, then sync them to a Git repository as JSON. Developers pull the JSON and run it through Style Dictionary or a similar tool.

This is the closest the industry has come to a true round-trip workflow between design and code. Designers work in their tool. Developers work in theirs. Tokens are the shared contract in the middle.

When to build custom tooling

Almost never, at least not at the start. Style Dictionary covers 90% of use cases out of the box. Tokens Studio covers the Figma-to-code pipeline. Build custom tooling only when you hit limitations that the existing tools can’t handle with configuration or plugins.

The exception is validation. You might want a custom linting step in CI that checks for naming violations, missing semantic tokens, or orphaned primitives. That kind of lightweight tooling pays for itself quickly.

How do tokens flow from Figma to production?

Salesforce, which coined the term “design tokens” in 2014, maintains over 3,000 tokens across its Lightning Design System and automates their distribution through a CI/CD pipeline (Salesforce, 2024). The workflow isn’t complicated, but it does require discipline from both designers and developers.

The design workflow

In Figma, designers apply tokens to components using Tokens Studio. A button’s fill color isn’t #2563EB. It’s color-action-primary. Every design element references a token, not a raw value.

When a designer changes a token value, Tokens Studio pushes the updated JSON to a Git branch. A pull request opens automatically. The development team reviews it, and the CI pipeline runs Style Dictionary to generate updated platform outputs.

The developer workflow

Developers consume tokens as CSS custom properties, Sass variables, or platform-native constants. A React component might look like this:

.button-primary {
  background-color: var(--button-bg-primary);
  padding: var(--spacing-component-gap);
  border-radius: var(--border-radius-sm);
}

No hex codes. No magic numbers. If a token changes upstream, the component automatically reflects the update after the next build.

What happens when design and code drift apart

They will drift. Someone will hard-code a value because they’re in a hurry. A designer will apply a raw color in Figma because the token doesn’t exist yet. A one-off override will sneak into a feature branch and never get refactored.

The fix is process, not tools. Run a token coverage audit quarterly. Lint for hard-coded values in CI. Make token creation part of the design review checklist. And accept that some drift is normal. Perfection isn’t the goal. Keeping drift manageable is.

On every team I’ve worked with, the drift conversation happens around month three. The system is live, people are using it, and then someone spots a screen where half the values are hard-coded. Don’t panic. Treat it like tech debt: log it, prioritize it, fix it incrementally. The system doesn’t need to be perfect on day one.

What are the most common design token mistakes?

A 2023 analysis by Supernova found that 42% of design system teams reported “token bloat” as their top maintenance challenge, with the average enterprise system containing over 2,000 tokens (Supernova, 2023). Knowing what not to do matters as much as knowing the process. Here are the mistakes I see most often.

Skipping the semantic layer

I’ve already said this, but it’s worth repeating because it’s the most common and most expensive mistake. Without semantic tokens, you lose the ability to theme, rebrand, or support dark mode without touching every component. Don’t skip it.

Token bloat

More tokens isn’t better. Every token is a decision you have to maintain, document, and communicate. If your system has 4,000 tokens and half of them aren’t referenced anywhere, you have a maintenance burden with no benefit.

Start with fewer tokens than you think you need. Add tokens when a concrete use case demands one. Delete tokens that nobody references. Run dead-token audits just like you’d run dead-code analysis.

Naming tokens after appearance

red-error-text seems descriptive until your brand uses orange for errors. Name tokens after their role: color-feedback-error. The value can be red, orange, or magenta. The name stays accurate regardless.

Not documenting intent

A token named spacing-component-gap is clear. But what’s the intended use? Is it the gap between sibling components in a layout? The internal padding of a component? Both? Document the intent alongside the value. A one-line description per token saves hours of guesswork.

One-off overrides

“Just this once, I’ll hard-code the padding.” Famous last words. One-off overrides bypass the system and create exactly the kind of inconsistency tokens were built to prevent. If a component needs a value that doesn’t exist as a token, create the token. If the value is truly unique, question whether the design itself needs adjusting.

Putting it all together

Design tokens aren’t a trend. They’re infrastructure. They solve the real problem of keeping design decisions consistent across platforms, teams, and time.

The practical takeaways: structure tokens in three tiers and invest the most effort in the semantic layer. Use purpose-based naming, not appearance-based naming. Pick established tools before building custom ones. Automate the pipeline from Figma to production. And run regular audits to catch drift before it compounds.

If you’re building a design system from scratch, start with the tokens. They’re the foundation everything else sits on. Get them right and the components, themes, and multi-platform support follow naturally. Get them wrong and you’ll feel the pain on every project that comes after.

For the full picture on building and maintaining a design system, head to the complete Design Systems guide. For step-by-step implementation details, see Design System 101.