A Simple Introduction to Design Tokens

If you’ve ever updated a brand color and spent the next hour hunting down every hardcoded #3B82F6 scattered across your stylesheet, you already understand the problem design tokens solve. This article explains what design tokens are, how they differ from plain CSS variables, and how to start using them in your frontend styling workflow.

What Are Design Tokens?

Design tokens are named, reusable values that represent your design decisions — things like colors, spacing, typography, border radii, and shadows. Instead of writing padding: 16px directly in a component, you reference a token like space-4 that holds that value.

At their core, every design token is just a name paired with a value. But as a methodology, they go further than that. The Design Tokens Community Group (DTCG), a W3C Community Group working toward a shared specification, describes them as a way of expressing design decisions in a platform-agnostic format so they can be shared across different disciplines, tools, and technologies.

That platform-agnostic part matters. The same token definitions can be transformed into CSS custom properties for the web, Swift constants for iOS, or XML values for Android — all from a single source of truth.

Common Design Token Categories

Most design systems organize tokens into these categories:

• Color — brand palette, text colors, backgrounds, borders
• Spacing — padding, margin, gap values
• Typography — font family, size, weight, line height
• Border radius — corner rounding for components
• Shadow — elevation and depth effects

Primitive Tokens vs. Semantic Tokens

This distinction is one of the most useful concepts in working with design system tokens.

Primitive tokens (also called base or global tokens) are raw values with no implied usage:

{
  "color-blue-500": { "$value": "#3B82F6", "$type": "color" },
  "space-4": { "$value": "16px", "$type": "dimension" }
}

Semantic tokens reference primitives and add intent. They tell you where to use a value, not just what it is:

{
  "color-action-primary": { "$value": "{color-blue-500}", "$type": "color" },
  "spacing-component-padding": { "$value": "{space-4}", "$type": "dimension" }
}

When you change color-blue-500, every semantic token pointing to it updates automatically. That’s the real power of the system.

Design Tokens vs. CSS Variables

CSS variables and design tokens are related but not the same thing.

Design tokens are the source. CSS variables are often the output. A tool like Style Dictionary takes your token definitions and transforms them into whatever format each platform needs.

A Simple Practical Example

Here’s a small set of tokens defined using DTCG-style syntax:

{
  "color-blue-500": { "$value": "#3B82F6", "$type": "color" },
  "color-text-primary": { "$value": "{color-blue-500}", "$type": "color" },
  "space-4": { "$value": "16px", "$type": "dimension" }
}

After running them through Style Dictionary, your CSS output looks like this:

:root {
  --color-blue-500: #3B82F6;
  --color-text-primary: var(--color-blue-500);
  --space-4: 16px;
}

Now your components use var(--color-text-primary) instead of a hardcoded hex value. Change the token once, update everywhere.

On the design side, Figma variables follow the same primitive-to-semantic pattern, making it easier to keep design and code aligned.

Start Small, Scale Intentionally

You don’t need a complete token system on day one. Start with color and spacing primitives, add a semantic layer as patterns emerge, and introduce tooling when the manual process becomes a bottleneck.

Conclusion

Design tokens aren’t just a way to organize CSS — they’re a shared language between designers and developers. Once that language is in place, consistency across your product stops being something you enforce manually and starts being something your system handles for you.

FAQs

Truly understand users experience

See every user interaction, feel every frustration and track all hesitations with OpenReplay — the open-source digital experience platform. It can be self-hosted in minutes, giving you complete control over your customer data. . Check our GitHub repo and join the thousands of developers in our community..