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
-
A design token is a named design decision stored in a platform-neutral file, usually JSON. A CSS variable is a browser feature that stores a value under a name. Tokens work across web, iOS, Android, and design tools. CSS variables work only in the browser. Most teams generate CSS variables from tokens.
-
Not always. A single web product with one brand can run on CSS variables alone. Tokens pay off when you add a second platform, a second brand, or a design tool that must stay in sync with code. At that point a shared token file stops values from drifting between teams.
-
Not yet. The Design Tokens Community Group, a W3C Community Group, published the first stable version of the specification, numbered 2025.10, on October 28, 2025. The spec states that it is not a W3C Standard and not on the W3C Standards Track. The group calls it stable and intended for implementation.
-
A Figma variable is a named value inside Figma. A design token is the same idea in a file that any tool can read. Teams export Figma variables to token JSON, commit the file to a repository, and run a translation tool to produce CSS variables and native platform code.
-
Translation tools read token JSON and write platform code. The Design Tokens specification names Style Dictionary and Terrazzo as examples. Run the tool on every merge so the CSS file always matches the token source.
-
Use three tiers. 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. Number scales in steps of 100, spell words out, and name by purpose instead of value, so a rebrand does not force renames.
-
Yes, on the web. Put each brand's overrides under a data attribute on the root element, and child elements inherit the new values. This does not cover native apps or design tools, and CSS variables carry no type or deprecation data. Tokens add those layers.

