Design tokens are named values that represent reusable design decisions, such as colors, spacing, typography, and motion. They give designers and developers a shared way to describe and apply those decisions across components, themes, and platforms.
For example, a component can use a token named color.text.link instead of choosing a color independently. The name describes the intended use; its value can change with the theme.
What are primitive, semantic, and component tokens?
Many design systems organize tokens into these layers. The naming and number of layers vary by system.
| Layer | Illustrative name | Role |
|---|---|---|
| Primitive | color.blue.600 |
Stores a base palette value. |
| Semantic | color.text.link |
Assigns a value to a purpose. |
| Component | button.primary.background |
Applies a decision to a specific component. |
A semantic token can reference a primitive through an alias. For example, color.text.link might reference color.blue.600 in a light theme and a lighter blue in a dark theme. Components continue to use the semantic name. Check the resulting contrast in each context.
A simple design token example
This example uses the DTCG 2025.10 format to define a spacing value and a token for card padding:
{
"space": {
"200": {
"$type": "dimension",
"$value": { "value": 8, "unit": "px" }
}
},
"card": {
"padding": {
"$type": "dimension",
"$value": "{space.200}"
}
}
}
card.padding resolves to 8 pixels through its reference to space.200. To increase only card padding, point card.padding to a different spacing token. Changing space.200 itself affects every token that references it. The names and values are illustrative.
How do tokens get from design to code?
A team maintains token definitions in an agreed source, reviews changes, and uses tooling to produce the formats each platform needs. A tool such as Style Dictionary can transform token data into CSS, JavaScript, or native platform resources.
CSS custom properties and Figma variables can represent tokens in their respective environments. A shared naming scheme, compatible tooling, and an explicit release process connect them. Tokens themselves do not automatically synchronize design files and production code.
Do design tokens have to use JSON?
Tokens are a design-system concept; the DTCG specification defines a JSON format for exchanging them between tools. The stable 2025.10 Format Module specifies types, values, groups, and references. It is a Community Group specification, not a W3C Standard.
Start with decisions that repeat across the interface. Document intended usage and check affected components before releasing changes. Add layers when they solve a concrete reuse or maintenance problem.