Design Tokens vs. CSS Variables: An Enterprise Implementation Guide

A design token is a named design decision, such as a color or spacing value, stored in a platform-neutral format like JSON. A CSS variable is a browser feature that applies a value at runtime. Design tokens act as the source of truth, and CSS variables are one of several outputs a token pipeline produces.


Design tokens and CSS variables look alike on the surface. Both give a name to a value, and both stop teams from typing the same hex code a hundred times. But they solve different problems. Enterprise teams that treat them as one thing hit a wall the first time a second platform or a second brand arrives.

Here is the short version. A design token is a design decision stored in a neutral file. A CSS variable is one way a browser applies that decision. Tokens sit upstream. CSS variables sit downstream. A healthy design system uses both.

This guide compares the two on scope, multi-brand scalability, naming, and governance. Then it walks through eight steps for building a pipeline from Figma to production code.

The short answer

Use design tokens as the source of truth. Export them to CSS variables for the web, and to other formats for iOS, Android, and documentation.

If you ship one web product with one brand, CSS variables alone can carry you a long way. If you ship across platforms, brands, or design tools, you need tokens behind them. The rest of this guide shows why.

What a design token is

The Salesforce design system team created the idea and gave it a name. Today the Design Tokens Community Group, a W3C Community Group, stewards a shared file format.

On October 28, 2025, the group announced the first stable version of its specification, numbered 2025.10. Co-chair Kaelig Deloumeau-Prigent said the specification "unlocks interoperability across design tools and code." The group's own status note adds a limit worth knowing. The spec is not a W3C Standard and is not on the W3C Standards Track. The group calls it stable and intended for implementation.

A token file is plain JSON. Each token carries a name, a value, and a type. It can carry a description, a deprecation flag, and tool-specific extensions. Tokens can point to other tokens, which the spec calls aliases and writes as {color.blue.500}. The format covers color, dimension, font family, font weight, duration, cubic Bézier, and number. It adds composite types such as shadow, border, typography, transition, and gradient.

The group's release announcement names the problem it set out to fix. Teams that run multi-brand systems often juggle dozens or even hundreds of token files by hand, and that leads to drift and errors. The stable spec adds standard support for theming, modern color spaces, and cross-tool interoperability.

One detail shows why tokens need a translation step. The spec's dimension type uses only px and rem. It says px maps to dp on Android and pt on iOS. Some platforms have no rem, so tools may convert it to a fixed pixel size. A token holds the decision. A tool turns it into the right unit for each platform.

What a CSS variable is

CSS calls these custom properties. You declare one with a double dash, such as --color-brand, and read it with var(). Custom properties are ordinary properties. The browser resolves them with the normal cascade and passes them down to child elements.

That behavior is the strength. Set a variable on a parent element and every child picks it up. Change it with a script, or inside a media query, and the page updates live. Sass variables disappear at build time. CSS variables stay alive in the browser.

The limits matter just as much. CSS variables exist only on the web. They carry no type, no description, and no deprecation flag. MDN notes that variables do not work inside media query or container query conditions. Names are case-sensitive, so --Brand and --brand are two different properties, as the W3C custom properties spec states.

Design tokens vs. CSS variables: head-to-head comparison

Attribute Design tokens CSS variables
What it is A named design decision stored in a platform-neutral file A browser feature that stores a value under a name
Where it lives JSON file in version control Stylesheet loaded in the browser
Platforms Web, iOS, Android, design tools, documentation Web only
Format DTCG JSON, specification 2025.10 CSS custom properties declared with a double dash
Type and metadata Type, description, deprecation flag, extensions Name and value only
Aliasing References such as {color.blue.500} var(--other-name)
Theming Modes or token sets, resolved at build time Scoped overrides, resolved by the cascade at runtime
Changes in the browser No, a rebuild produces new output Yes, values change live
Governance Pull requests, validation, deprecation flags Teams add linting and review rules on top
Best use Source of truth across platforms and brands Delivery layer for the web

Scope: one decision, many platforms

A token file is one source with many outputs. Change a color in the file and the web app, the iOS app, the Android app, and the documentation site all pick it up on the next build. CSS variables reach only the browser. If your company ships a native app next year, CSS variables give that team nothing to start from.

Translation tools do the work in the middle. The spec names Style Dictionary and Terrazzo as examples. They read token JSON and write platform code, such as Sass variables or CSS custom properties.

Multi-brand and multi-platform scalability

Scale shows up as multiplication. Ten brands with light and dark modes make 20 theme combinations. Add two density settings and the count reaches 40. Nobody can hand-edit 40 stylesheets and keep them in sync.

Tokens handle this with modes. In Figma, a variable holds one value per mode. A brand or a light and dark theme becomes a mode, and switching the mode on a frame restyles every component that reads from it. In code, the same idea lands as scoped overrides.

Layering matters here. Red Hat's design system guidance for Figma tells designers to skip primitive variables in components. Primitives cut the link to theming and meaning. Components should read semantic tokens, and the semantic layer should point at primitives. Then a brand swap changes the pointers and leaves every component alone.

Adoption data shows where the industry has gone. The Supernova State of Design Tokens 2024 report found that 69.8% of respondents had moved to Figma Variables for token management. [EDITORIAL FLAG: This figure came from a Medium guide that cites the Supernova report. Verify it in the primary Supernova publication before publishing.]

The business case has outside support too. Forrester's Total Economic Impact study of Figma, which Figma commissioned, reported a 231% return on investment over three years, a 60% gain in design productivity, and a 30% gain for developers. The study measures the platform as a whole and not tokens alone, so treat it as context. [EDITORIAL FLAG: This study is vendor-commissioned. The figures came from Figma's German-language Forrester TEI page. Confirm them in the full Forrester report and swap in the English page link if you prefer.]

Semantic naming conventions

The spec sorts tokens into three categories, and the sort makes a good naming model.

  • Base tokens hold raw values, such as color.blue.500.

  • Alias tokens describe purpose, such as color.action.primary.

  • Component tokens begin with the component name, such as button.background.

The spec adds four naming tips. Number scales in steps of 100 instead of 1, 2, 3, so you can insert a new shade later. Spell words out, so write background and skip bg. Start alias tokens with the category and then the property, as in color.background.error. Start component tokens with the component they serve.

One more rule comes from experience. Name by purpose, not by value. color.action.primary survives a rebrand. color.blue.button does not.

Here is how three tiers look in a DTCG token file. The color values use the object format that the stable spec requires.

{
  "color": {
    "blue": {
      "$type": "color",
      "500": {
        "$value": { "colorSpace": "srgb", "components": [0, 0.38, 1], "hex": "#0061ff" }
      },
      "700": {
        "$value": { "colorSpace": "srgb", "components": [0, 0.25, 0.7], "hex": "#0040b3" }
      }
    },
    "action": {
      "primary": { "$value": "{color.blue.500}" }
    }
  },
  "space": {
    "$type": "dimension",
    "md": { "$value": { "value": 16, "unit": "px" } }
  }
}

A translation tool turns that file into CSS variables. A second brand overrides only the semantic layer.

:root {
  --color-blue-500: #0061ff;
  --color-blue-700: #0040b3;
  --color-action-primary: var(--color-blue-500);
  --space-md: 16px;
}

[data-brand="brand-b"] {
  --color-action-primary: var(--color-blue-700);
}

.button {
  background: var(--color-action-primary);
  padding: var(--space-md);
}

The button never mentions a hex code or a brand. Set data-brand="brand-b" on the root element and the button changes color through inheritance alone.

Governance across Figma-to-code pipelines

Governance answers three questions: who can change a token, how a change gets reviewed, and how old tokens retire.

Tokens support all three. The file lives in version control, so every change is a pull request with a history. Each token can carry a description and a deprecation flag, and the flag can hold a plain-language reason such as which token to use instead. The spec requires tools to detect circular references and report them as errors.

CSS variables have none of that on their own. A team has to add linting and review rules around them, for example a check that flags raw hex values in component code.

This table shows one workable ownership model.

Token tier Example Owner Change process
Base color.blue.500 Design system core team Formal review and an announced release
Alias color.action.primary Core team with product design reps Pull request with a visual diff and a contrast check
Component button.background Component owner Pull request reviewed by the core team
Brand override brand-b mode Brand design lead Pull request, contrast check, brand sign-off

Base tokens change rarely and ripple everywhere, so they get the heaviest review. Component tokens change often and stay local, so they get a lighter touch.

Step-by-step implementation guide

Step 1: Audit what you have

Count every unique color, font size, and spacing value in your code and your Figma files. Teams often find near-duplicates, such as several grays that differ by one digit. The audit gives you a baseline and a consolidation target.

Step 2: Set the architecture and naming rules

Pick your tiers, your naming pattern, and your list of modes. Write the rules on one page. Decide which brands and themes exist today and which ones the system must support next.

Step 3: Build the variables in Figma

Create separate collections for primitives, semantic tokens, and components. Add one mode per brand or theme to the semantic collection. Point semantic variables at primitives. Scope each variable to the properties it serves, so designers see only fitting options. Check your Figma plan for mode limits before you design the structure.

Step 4: Export to DTCG JSON and commit it

Export the variables to token JSON in the 2025.10 format and commit the file to a repository. The spec recommends the .tokens or .tokens.json file extension and the media type application/design-tokens+json. From this point the repository, and not the Figma file, is the source of truth for code.

Step 5: Transform tokens into platform code

Run a translation tool such as Style Dictionary or Terrazzo on every merge. Produce a CSS file for the web and the matching constants for iOS and Android. Let the tool convert px to dp and pt. Publish the output as a versioned package so product teams can install it.

Step 6: Wire up themes in code

Declare base and alias variables on the root element. Put each brand's overrides under a data attribute. Require components to read only alias and component variables. This one rule keeps brand swaps cheap.

Step 7: Add guardrails

Run checks in your build pipeline. Validate the token file against the spec. Fail the build on circular references and on tokens with no type. Flag raw hex codes in component code. Run contrast checks on every alias that pairs text with a background.

Version the package with semantic versioning, so removals count as major releases. Mark old tokens with the deprecation flag and a replacement note. Keep them for a set window, such as two release cycles, and then remove them.

Step 8: Measure adoption

Track the share of components and screens that use tokens. Track how many hard-coded values remain. Track how long it takes to launch a new brand theme. Put the numbers on a dashboard that leadership can read. A falling count of raw values is the clearest proof that the system works.

Common mistakes

  • Treating CSS variables as the source of truth. Native apps and design tools then keep their own copies, and the copies drift.

  • Letting components read primitives. A brand swap then forces edits in every component.

  • Naming by value. A token called blue-button breaks the day the button turns green.

  • Skipping deprecation. Old tokens pile up and nobody knows which ones are safe to remove.

  • Expecting var() to work in media queries. It does not, so keep breakpoints as plain values or as build-time output.

  • Exporting once and walking away. Without a pipeline that runs on every merge, the token file goes stale within weeks.

How Demir Digital helps

Demir Digital started inside top agencies, then moved in-house to lead digital work for Nike's Global Brand Defining Studio. There we built tools, designed systems, and improved processes for global teams. We now bring that experience to organizations everywhere.

On token and design system projects, our team maps your needs and gaps, audits the system you have, and builds or refines the component library and tooling. We write the playbooks, run workshops and training, and embed with your team so the pipeline keeps running after we leave. We build dashboards that show whether adoption is working.

FAQ

Related Reading

Next
Next

Reinventing Marketing Ops: A Step-by-Step Guide for Enterprise Brands