How to start a design token system with confidence

Louis Chenais
Written by Louis Chenais
Jun 11, 2026

Learn how to start a design token system with confidence as a design system team, while ensuring your consumers trust both your team and the system itself.

Design tokens help product teams manage and use a brand at scale. They live at the core of your design system. I won't explain why you should use design tokens, but here are a few reasons they work for you:

  • They make your design system scalable.
  • They speed up development.
  • They create tighter design-developer collaboration.

A design token system defines which design tokens you use, which platforms you target, their relationship, and how you should create and use them at scale.

This article will focus on helping a design system team, composed of at least one designer and one developer, create its first design token system for web application UIs. Together.

We'll go through best practices for creating, documenting, versioning, and syncing design tokens.

I'll refer to design tokens as design decisions that follow the DTCG format. Figma variables or CSS variables are not design tokens, since design tokens are platform-agnostic.

General tips

Design tokens are a team effort

Create your design token system as a team (with at least one designer and one developer). Design tokens must be created by the same people using them. You need them to make your UIs responsive, performant, and accessible. That's why I strongly encourage you to create them as a team, not just as designers.

You must be able to understand and explain every decision about how your design tokens are used. That includes their names, types, values, units, relationships, and how they are synced, converted, documented, and versioned.

Keep it simple

I must admit, design tokens can feel overwhelming. This is exactly why you must keep it really simple when creating the system:

  • Don't try to cover everything at once. Only create design tokens at a scale you can control. Expand later.
  • Work on a single context: one brand, one theme, one platform (the most important ones for the business).
  • There are lots of details to cover, so start small, build confidence, and stay motivated.
  • Organize yourself so your system creates value from day one.
  • The simpler your system, the faster people will adopt and trust it.

Finally, creating a design token naming convention deserves its own article. But the most important rule is this: Name your tokens, so they stay agnostic to their context of use. Names must not contain anything related to what could change, like a value or a theme.

    • Don't: heading1-bold
    • Do: heading1
    • Don’t: color-bg-dark
    • Do: color-bg-strong

Start with the design token types that matter most

You can start with the design tokens you might already have. Project Wallace can help you identify values in your existing website.

Or you can start from scratch with the design tokens that bring the most value for your organization.

For example:

  • If your product is mostly about content, text styles may be the most important tokens to define before color.
  • If your organization is working on a rebrand, get in touch with the people in charge of that work, so you can focus on colors first.

More generally, start with the tokens that actually make a UI: text, color, spacing.

Without them, your UIs are not usable and definitely not as intriguing as Kazimir Malevich's White on White painting.

Start small with what you're sure you need. Expand when necessary. Build trust and momentum over time.

Most teams try to cover everything at once and often get lost along the way. No finger-pointing, though. It's not easy to get started. Design tokens can feel vague and complex.

Don’t create component tokens. Limit your design token system to two layers: core and semantic. Name your semantic tokens so they describe an intention, not the value.

Text styles

Cover the basics: 6 headings, 3 body styles, and 2 caption styles. Create the minimum amount of text styles, allowing you to create both a blog post and a login page.

Name them so they make sense for your team, whatever the platform, usage context, or values.

You also don't control the background color behind your text. That's why you should not include color in a text style.

Colors

Use a small number of color ramps (like red, blue, green, orange, and white to black), with 10 values max in each ramp.

Your app content has different intents:

  • neutral (black/white)
  • information (blue)
  • warning (orange)
  • errors (red)
  • validation/success (green)

Define 10 values for each color ramp to give you the flexibility to iterate on your color system and improve text-background combinations color contrast.

Define core and semantic tiers (remember, no component design tokens).

Use a systemic color format like OKLCH. This great article will help you get started.

Understand the different layers that make up a UI (Open Source Color System will help you set up a simple system):

  • background
  • foreground (text/icon)
  • border
  • brand colors
Conceptual illustration of how a product could leverage Intuit semantic colors to style their application. Notice how color tokens are categorized into the aforementioned layers (Source).

Work with a single theme in mind. Iterate on it until it's "good enough". And only then, add more themes, like dark theme or high contrast.

Spacing

Define a single dimension scale you'll use for spacing and sizing dimension tokens.

Start with a base unit of 4px and generate 20 values from it. That’s enough to get you started.

Example spacing scale (linear): space-1: 4px, space-2: 8px, ..., space-20: 80px.

Example dimension scale showing how all values are made from the previous one.

Take into consideration how to make those values responsive (Utopia can help with this). Using the CSS clamp function can be helpful to make your spacing or font sizes responsive. But it might be overkill when you're just starting out. I'd suggest you keep that aside for later.

The process matters as much as the output, if not more

Create your design decisions in the tool of your choice, whether it's a design tool like Figma or Penpot, or directly in the browser. I'd lean toward the latter because first, I'm a huge fan of the "Hot Potato Process", and secondly, because making decisions on the same platform as our end users is beneficial in the long run.

Shopify’s Polaris design system used to provide a playground to let consumers see changes on a fake UI when updating design token values. I advise you to spin a playground like this from your existing components if you can. It will help you iterate on your tokens in the browser directly.

Document every decision you make along the way by creating Architectural Decision Records. You must be able to explain how you ended up with one naming convention over another, or why you decided to keep using hexadecimal color values instead of OKLCH. 

Also, feel comfortable sharing this changelog publicly. Transparency is key. Your job as a design system team is to iterate on the system so it brings value to its consumers. Make it easy for others to give feedback, and embrace it as much as possible.

Your design tokens must exist in a JSON file that complies with the DTCG specification. You can generate this file automatically using various tools and plugins. For instance, you could use Terrazzo to generate design tokens from your Figma variables and styles. 

The most important part is to save your design tokens in this aforementioned format and version them in a code repository. That way, your design tokens are centralized, versioned and usable by any tools or APIs your team needs.

What you need to remember

Creating a design token system is a design system effort that requires planning. Focus on the design tokens that bring the most value from day one, and iterate over time. You'll mostly work on text styles and colors first, which is already enough to get your team started and your consumers eager to get more from you. 

Make your design tokens agnostic by saving them in JSON files that follow the DTCG specification in a git repository. Document your work along the way so you're sure your consumers benefit from the system as much as possible. 

Do this, and I assure you, everything will be fine.

Louis Chenais
Louis Chenais
Louis Chenais is a front-end developer and design systems specialist. He's an editor at the Design Tokens Community Group and currently a design system consultant. He previously helped many design systems teams implement design tokens as part of his founding role at Specify, a now sunset design API SaaS. He is dedicated to building web experiences that feel good to use for everyone. When he's not coding, he's usually digging deep-house, ambient, or techno music.
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post