smaple.tr
Product & Process

Design Tokens: What They Are and How to Set Them Up

Mehmet Kurtipek
March 18, 2026
14 min read
Product & Process
Design tokens
Design systems
Style Dictionary
Figma

Design tokens are named values for the small, repeated decisions in an interface: colors, spacing, font sizes, corner radii, shadows, animation durations. Each decision is stored once, under a name like color.action.primary, in a platform-neutral file (usually JSON), and a build tool turns that file into CSS custom properties, Swift constants, Android resources or whatever else your apps read. Change the value in one place, rebuild, and the website and the mobile apps built from that file all get the new color.

Since October 2025 there is also a stable, vendor-neutral file format for them: the Design Tokens Community Group's Format Module 2025.10, which Figma, Tokens Studio and Style Dictionary all read. The term itself is older: Jina Anne coined it with Jon Levine while she was at Salesforce.

What a token looks like

A token is a name, a type and a value. In the DTCG format the properties start with a dollar sign, so tools can tell them apart from group names:

{
  "color": {
    "$type": "color",
    "blue": {
      "600": {
        "$value": { "colorSpace": "srgb", "components": [0.1451, 0.3882, 0.9216], "hex": "#2563eb" },
        "$description": "Brand blue"
      }
    }
  },
  "space": {
    "$type": "dimension",
    "4": { "$value": { "value": 1, "unit": "rem" } }
  }
}

Nested objects are groups, so this file defines color.blue.600 and space.4. A $type set on a group applies to every token inside it.

Two details catch out anyone who learned tokens from older tutorials. In the stable format a color is an object with a color space and its components, and the hex string is only an optional fallback; that is how the format can describe Display P3 or OKLCH colors as well as plain sRGB. A dimension is also an object, a number plus a unit, and the only units allowed are px and rem. Files that write a color as a plain string ("$value": "#2563eb"), or use Style Dictionary's older value key without the dollar sign, still build in Style Dictionary, which stays backwards compatible, but that is the pre-standard style. Besides colors and dimensions, the format defines font families, font weights, durations, cubic Bézier curves and numbers, plus composite types for typography, shadows, borders, stroke styles, transitions and gradients.

A token can also point at another token: "$value": "{color.blue.600}" makes an alias, which has no value of its own and follows whatever color.blue.600 holds. The layers and themes in the next sections are built from nothing else.

Tokens and CSS variables

A CSS custom property such as --color-action-primary is one output of a token, for one platform. The token is the source: it has a type, it can be converted to Swift or Kotlin, and a design tool can read it. If you ship a single web app, a tidy set of CSS custom properties already gives you most of the benefit, and Tailwind CSS v4 is built on the same idea: you declare design tokens as theme variables with @theme, and they compile to ordinary CSS variables.

A separate token file starts to matter when a second platform or a design tool has to read the same values. Even then, if every platform is JavaScript (a Next.js site and a React Native app, say), a shared TypeScript module of constants can be enough. The build step pays for itself once Swift, Kotlin, Dart or Figma needs the values too.

Three layers: primitive, semantic, component

Token sets that last tend to have three layers.

Primitive tokens are the raw palette and scale: color.blue.600, color.slate.900, space.4. They say what a value is and nothing about where it goes.

Semantic tokens name a role and point at a primitive: color.text.default, color.surface.default, color.action.primary. Components use these. A dark theme is the same set of semantic names pointing at different primitives, which is why this layer matters most.

Component tokens narrow a role to one component, for example button.primary.background pointing at color.action.primary. Material Design uses the same three tiers under the names reference, system and component; on the web they appear as custom properties like --md-sys-color-primary and --md-filled-button-container-color.

On a small team, build the first two layers and add component tokens only when a component really has to differ from the role it uses. Created up front, the component layer adds a token for every property of every component, and most of them only repeat the semantic token underneath.

Whatever you build, component code should never reference a primitive. If a button uses color.blue.600 directly, no theme can reach it.

Name tokens for what they do

Names that describe appearance age badly once you add a second theme. Trendyol's open-source Baklava design system shows the effect. Its neutral scale has steps from --bl-color-neutral-darkest to --bl-color-neutral-lightest, and in the dark theme the whole scale is inverted, so neutral-darkest holds #f1f2f7, a near-white. Because the inversion is consistent, the system works, but everyone reading a stylesheet has to know that "darkest" there means "strongest contrast with the background". Role names such as text.default, surface.raised or border.subtle survive a theme switch without that footnote.

A few habits that help with naming:

  • Go from general to specific: category, role, variant, state (color.action.primary.hover).
  • Pick one word per idea and use it everywhere: default or base, never both.
  • Keep platforms and raw values out of semantic names. blue-button-ios and padding-16 both stop being true eventually.
  • Keep names in plain ASCII. Style Dictionary lowercases names with JavaScript's rules, so a token named with a Turkish İ comes out in CSS as i followed by an invisible combining dot (U+0307), and nobody typing the variable name by hand will match it.

When tokens are worth the setup

Tokens pay off when the same visual decisions have to reach places that share no styling code:

  • two or more platforms, such as a web app plus native mobile apps, or several micro frontends owned by different teams;
  • more than one theme: dark mode, white-label versions for customers, several brands on one product;
  • designers and developers who both edit values and need them to match.

My3PL is a client project of the first kind. We built its website, web app and mobile app, with React, Angular, Vue.js and Flutter between them. The three web stacks can all read one CSS file of custom properties. The Flutter app can't read CSS at all, so without a shared token source its colors get typed again in Dart, and every retyped value is one that can drift from the web.

They are not worth a pipeline when you have one web app, one theme and a small team. Then a single CSS file of custom properties, or Tailwind's theme variables, is your token layer, and adding a JSON source plus a build step mostly adds a place for things to go out of sync. Start there. If your CSS variables already follow the primitive and semantic split, moving them into a token file later is mostly copying.

Where the source of truth lives

There are three common setups, and the decision that matters is which direction values flow.

Figma Variables. Figma's native variables hold colors, numbers, strings and booleans, and modes give one collection several sets of values, such as light and dark. Figma can import DTCG files: imported into a new collection, each JSON file becomes a mode; colors must be sRGB or HSL, and dimensions must be in px, which arrive as plain numbers (Figma Help Center). Reading variables through Figma's REST API, which a server-side sync needs, is limited to the Enterprise plan, and so are extended collections, Figma's feature for multi-brand systems.

Tokens Studio. A Figma plugin that keeps tokens as JSON and syncs them with GitHub, GitLab, Bitbucket or Azure DevOps. It supports the DTCG format as an option and handles composite tokens such as typography, borders and shadows, which Figma Variables don't have as variable types. The free plan syncs a single file; syncing a folder of several files is a paid (Pro) feature.

The repository. Token files sit in the code repo next to the build script and change through pull requests like everything else. Designers import them into Figma or edit them through Tokens Studio.

For anything that ships, the repository is the safest of the three to treat as the source: Figma reads the tokens from it, and design changes come back as pull requests. Trouble starts with two-way sync, where both Figma and the repo can be edited and a plugin or script reconciles them later. Pick one direction and treat the other side as read-only. (How design and engineering hand work over in general is in our post on the product design process.)

A working build for web, iOS and Android

Style Dictionary, the open-source build tool that started at Amazon, is on version 5 (5.7.0 was released on 16 October 2026). It reads DTCG files, and support for the 2025.10 structured values arrived in steps: color objects in 5.3, dimension objects in 5.4 and durations in 5.7, according to its changelog. Its documentation still calls full 2025.10 support a work in progress, so test anything beyond colors and sizes before you rely on it. If you want an alternative, Terrazzo is listed by the DTCG as a reference implementation alongside Style Dictionary and Tokens Studio.

The example has a primitives file and two themes. It was run on Style Dictionary 5.7.0 and Node 26, and the output below is copied from that run. tokens/primitives.tokens.json:

{
  "color": {
    "$type": "color",
    "blue": {
      "300": { "$value": { "colorSpace": "srgb", "components": [0.5765, 0.7725, 0.9922], "hex": "#93c5fd" } },
      "600": { "$value": { "colorSpace": "srgb", "components": [0.1451, 0.3882, 0.9216], "hex": "#2563eb" } }
    },
    "slate": {
      "900": { "$value": { "colorSpace": "srgb", "components": [0.0588, 0.0902, 0.1647], "hex": "#0f172a" } }
    },
    "white": { "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" } }
  },
  "space": {
    "$type": "dimension",
    "2": { "$value": { "value": 0.5, "unit": "rem" } },
    "4": { "$value": { "value": 1, "unit": "rem" } }
  }
}

tokens/light.tokens.json maps the roles:

{
  "color": {
    "$type": "color",
    "text":    { "default": { "$value": "{color.slate.900}" } },
    "surface": { "default": { "$value": "{color.white}" } },
    "action":  { "primary": { "$value": "{color.blue.600}" } }
  },
  "space": {
    "$type": "dimension",
    "inset": { "md": { "$value": "{space.4}" } }
  }
}

tokens/dark.tokens.json uses the same color names with different targets:

{
  "color": {
    "$type": "color",
    "text":    { "default": { "$value": "{color.white}" } },
    "surface": { "default": { "$value": "{color.slate.900}" } },
    "action":  { "primary": { "$value": "{color.blue.300}" } }
  }
}

The build script runs once per theme. Primitives are passed as include so the aliases resolve, and the filter keeps them out of the output, which means application code can only reach semantic tokens:

// build-tokens.mjs  (Node 22+; npm install -D style-dictionary@5, then: node build-tokens.mjs)
import StyleDictionary from 'style-dictionary';

const themes = {
  light: { selector: ':root', androidDir: 'values', swiftEnum: 'TokensLight' },
  dark: { selector: '[data-theme="dark"]', androidDir: 'values-night', swiftEnum: 'TokensDark' },
};

const onlySemantic = (token) => token.isSource;

for (const [theme, { selector, androidDir, swiftEnum }] of Object.entries(themes)) {
  const sd = new StyleDictionary({
    include: ['tokens/primitives.tokens.json'],
    source: [`tokens/${theme}.tokens.json`],
    platforms: {
      css: {
        transformGroup: 'css',
        buildPath: 'build/css/',
        files: [{ destination: `${theme}.css`, format: 'css/variables', filter: onlySemantic, options: { selector } }],
      },
      android: {
        transformGroup: 'android',
        buildPath: `build/android/${androidDir}/`,
        files: [{ destination: 'tokens.xml', format: 'android/resources', filter: onlySemantic }],
      },
      ios: {
        transformGroup: 'ios-swift',
        buildPath: 'build/ios/',
        files: [{
          destination: `${swiftEnum}.swift`,
          format: 'ios-swift/enum.swift',
          filter: onlySemantic,
          options: { className: swiftEnum },
        }],
      },
    },
  });
  await sd.buildAllPlatforms();
}

The CSS output, from build/css/light.css and build/css/dark.css:

:root {
  --color-text-default: #0f172a;
  --color-surface-default: #ffffff;
  --color-action-primary: #2563eb;
  --space-inset-md: 1rem;
}

[data-theme="dark"] {
  --color-text-default: #ffffff;
  --color-surface-default: #0f172a;
  --color-action-primary: #93c5fd;
}

On the web nothing switches by itself. The dark values apply once your app sets data-theme="dark" on the <html> element, from a theme toggle or from matchMedia('(prefers-color-scheme: dark)').

Android does switch by itself. The dark file lands in values-night/, and the system picks those resources when the device is in dark mode, so color_action_primary changes from #ff2563eb to #ff93c5fd without any code, as long as the app follows the system theme. Android falls back to values/ for anything missing from values-night/, never the other way round, so every name in the dark file must also exist in the light one.

iOS gets two enums, TokensLight and TokensDark, with constants such as UIColor(red: 0.145, green: 0.388, blue: 0.922, alpha: 1). Style Dictionary has no built-in format for colors that follow the system appearance, so you join each pair yourself, by hand or in a small custom format that writes lines like these:

import UIKit

extension UIColor {
    static let actionPrimary = UIColor { traits in
        traits.userInterfaceStyle == .dark ? TokensDark.colorActionPrimary : TokensLight.colorActionPrimary
    }
}

The other route is a custom format that writes color sets into an Xcode asset catalog. Built-in formats also exist for Jetpack Compose, Flutter and plain JavaScript modules.

The unit trap

If you author spacing in px, the iOS and Android output comes out 16 times too large: an 8px token becomes CGFloat(128.00) and 128.00dp. The built-in mobile transform groups treat every dimension as rem and multiply it by the platform's basePxFontSize (16 by default) without checking the unit. Author all dimensions in one unit. rem works with the defaults. If you need px because the tokens also go into Figma, which only imports px, set basePxFontSize: 1 on the iOS and Android platforms, and the same token comes out as CGFloat(8.00) and 8.00dp.

Moving an existing app to tokens

Most teams don't start from zero. This order works:

  1. Count what you have. grep -rhoE '#[0-9a-fA-F]{6}\b' src | tr 'A-F' 'a-f' | sort | uniq -c | sort -rn lists every six-digit hex color in src by how often it appears. It misses three-digit hex, rgb() values and colors set in Swift or Kotlin code, so treat it as a first pass. Expect near-duplicates: three blues a few shades apart are usually one blue that was copied by eye.
  2. Merge the near-duplicates into primitives, with a designer in the room. This is where the actual design decisions get made.
  3. Define semantic tokens for the roles you found: text, surfaces, borders, actions, success and error colors.
  4. Move one component family at a time, starting with whatever appears on most screens (usually buttons and form fields), and compare screenshots before and after each step.
  5. Stop new hard-coded values coming in. Stylelint's built-in color-no-hex rule fails on hex colors in CSS; switch it off only for the generated token files.

Then put the token build in CI so it runs on every pull request that touches the token folder (our GitHub Actions guide covers the setup), and treat a renamed or removed token as a breaking change for every app that uses it. The DTCG format has a $deprecated property for marking a token before you delete it.

Semantic tokens also make contrast checks mechanical, because colors come in known pairs: text on surface, link on surface, label on button. A short script in the same CI job can compute every pair in every theme. In the example above, #2563eb on white is 5.17:1 and #93c5fd on #0f172a is 9.9:1, both above the 4.5:1 that WCAG 2.2 asks for normal text; large text needs 3:1.

Frequently asked questions

Are Figma variables design tokens?

They are Figma's native way of storing them. A variable has one value per mode and can alias another variable, which is the same model as a token file. What they don't do on their own is reach your code: you export them as JSON, read them through the REST API on an Enterprise plan, or keep the source in the repository and import it into Figma.

What is the W3C design tokens format?

It is the Format Module published by the Design Tokens Community Group, a W3C community group, as version 2025.10 on 28 October 2025. The group calls it stable, but it is not a W3C Standard and is not on the standards track, as the report itself states. The suggested file extensions are .tokens and .tokens.json.

What is the difference between design tokens and a design system?

A design system is the whole kit: components, usage guidelines, documentation and the design files behind them. Tokens are its lowest layer, the values those components are styled with. You can have tokens without a design system, for example one brand's colors and spacing in a file that two apps share. A design system that serves several platforms usually ends up needing tokens, because each platform rebuilds the components in its own code and they all have to agree on the values.

If you're planning a product that has to look the same on web and mobile, our web development page explains how we work.

Related Articles

May 17, 2026

WMS vs TMS: What Each Does and Which One You Need First

A WMS runs what happens inside the warehouse; a TMS runs what happens after the truck leaves. Where they meet, which to buy first, and when you need neither.

Read More: WMS vs TMS: What Each Does and Which One You Need First
April 3, 2026

SaaS Pricing Models: How to Choose One and Bill for It

The main SaaS pricing models, when each one fits, and the decision to make first: your value metric. Plus what your pricing asks of the billing code.

Read More: SaaS Pricing Models: How to Choose One and Bill for It
April 2, 2026

SaaS Metrics: What to Track, How to Calculate It, What Good Looks Like

The core SaaS metrics with formulas and worked examples, what recent benchmarks say is normal, and the definition mistakes that quietly distort MRR, NRR and LTV.

Read More: SaaS Metrics: What to Track, How to Calculate It, What Good Looks Like