How do you map design tokens to CSS custom properties?
Connect shared design decisions to named web-style values and check their actual use.
CSS is the styling language that controls web colours, sizes, and layout. CSS custom properties, also called CSS variables, are reusable named values in styles and can implement some design tokens.
Keep these basics in mind
- A token records a decision and its purpose. A CSS variable is one browser implementation method; the concepts are not identical.
- Scope is the area a value can affect, such as a whole page or one section.
- Inheritance passes values from an outer element to inner elements. A fallback value is a backup when the referenced value is unavailable.
- Record names, units, and theme mappings, then check whether the website actually uses them.
See MDN’s custom-properties guide for implementation rules.
From decision to browser
Illustrative mappings
These names and values are examples.
px
means CSS pixels used in web layout.
| Decision | Example variable | Example value | Usage |
|---|---|---|---|
| Body text colour | --text-primary |
#222222 |
Body text |
| Regular content gap | --content-gap |
16px |
Between groups |
| Card corners | --card-radius |
8px |
Card edges |
Walk through an example
After agreeing on regular content spacing, a developer sets
--content-gap
to
16px
and references it on a profile page. One section does not change because it still uses a
directly entered distance. After correcting the reference, the developer checks narrow
windows and long content before releasing.
Limits and common misunderstandings
Changing a variable affects only places that reference it within the relevant scope. Fallbacks do not repair every invalid style. Readers only need to understand the mapping; implementation staff should verify code and units.