Refract Group2026
Glossary
Design tokens
Design tokens are named values that record a design decision, such as a brand colour, a spacing step or a type size, stored once in a format that design tools and code can both read, so every platform uses the same value.
spacing.tokens.json
{
"space-4": {
"$type": "dimension",
"$value": { "value": 16, "unit": "px" }
},
"card-padding": { "$value": "{space-4}" }
}
Design tokens in detail
- Also called
- Tokens, Design variables, Style tokens
- Topic
- Product
- Updated
What it is
A token has a name and a value. A token called space-4 might hold 16 pixels, and one called accent-base might hold a purple. Most teams keep two tiers. Base tokens name the raw palette and scale. Semantic tokens name a job, such as the padding of a card or the text of an error, and point at a base token, so a change to the brand colour is a change to one line.
The tokens live in a file, usually JSON, and a build step turns that file into what each platform reads: CSS custom properties for a website, constants for an iOS or Android app, variables in Figma. The Design Tokens Community Group at the W3C published a stable version of a shared format in October 2025. Each token has a $value and an optional $type, and a reference is another token’s name in curly braces. It is a community group report, which is a step short of a W3C standard.
Why it matters
Without tokens, a colour is typed by hand wherever it appears: the Figma file, the stylesheet, the mobile app, the email template. Each copy drifts a little, and a rebrand becomes a search through the codebase for hex codes. With tokens the decision sits in one place. Dark mode is a second set of values for the same names. A reviewer checks a screen against names, which is quicker and surer than comparing two reds by eye.
How we do it
Tokens are the first layer when we build a design system. We go through the interface you have and write down every type style, colour, spacing value and grid in use, then mark what is duplicated and agree with your designers and engineers which values stay.
Those become the tokens for type, colour, spacing and grids, set once and read by both the Figma library and the coded components. The components are built on them, with their states, in the stack your engineers already use, because we build the design system in code as well as in Figma. You get the tokens, the library and the components in your own accounts.
An example
Say a product’s error red fails contrast on its new dark background. Without tokens, someone searches the code for the hex value and finds it in forty places, three of which were meant to be a warning. With tokens, every error message uses a semantic token, text-error, which points to red-600 in the light theme and red-400 in the dark one. The fix is one line in the dark theme, and every form field and alert picks it up on the next build.
Common mistakes
- Naming tokens after their value. A token called purple-500 that every button uses becomes misleading the day the brand moves to blue, where one called action-primary only needs a new value.
- Making a token of every number. A token for a 13-pixel gap used once on one screen adds a name nobody else will reach for, because tokens are for decisions that repeat.
- Skipping the semantic tier. When components point straight at the palette, a dark theme means editing every component instead of remapping a few dozen names.
- Keeping two lists by hand. A set in Figma and a set in code that are edited separately drift apart, so one should be generated from the other or both from a shared file.
Design tokens vs CSS variables
A design token is a named design decision kept in a format any platform can read, and a CSS variable is one way a website stores and applies that value in the browser.
| Design tokens | CSS variables | |
|---|---|---|
| Lives in | A tokens file, usually JSON | A stylesheet |
| Read by | Design tools, web and app builds | The browser |
| Reference | "$value": "{space-4}" | var(--space-4) |
| Resolved | At build time, for each platform | At run time, through the cascade |
Questions
What people ask about design tokens.
Figma variables are one place to keep design tokens. Figma’s own guide says to use variables and modes to implement design tokens, with modes holding different values for contexts such as light and dark themes. The tokens are the named decisions themselves, and the same set can be exported to code for engineers.
Design tokens are usually written as JSON. The Design Tokens Community Group format, stable since its 2025.10 version, gives each token a $value and an optional $type, nests tokens in groups and writes a reference as a token name in curly braces. It recommends the .tokens or .tokens.json extension. Tools then convert the file for each platform.
Design tokens are one layer of a design system: the named values for colour, type, spacing and similar decisions. The design system also holds the components built from those values, the patterns they combine into and the rules for using them. Tokens alone keep colour and spacing consistent and leave behaviour to each screen.
Where this shows up in our work
Related terms
Working on this now?
Tell us what you’re building and where it’s stuck. We reply within 12 hours.
Most teams start with a call, then a sprint or an audit.
The people you’d work with, from the first call to launch