From design tool variables to CSS custom properties
This page is for theme designers who keep colors, sizes and spacing as variables in a design tool and want them to arrive unchanged in the theme. Most current design tools support variables with modes (for example a light and a dark mode). An Exponential theme expresses the same thing as CSS custom properties in a token stylesheet, with a light value set and a dark value set. The rules for tokens are in Design tokens; this page is the bridge.
Contents
- The mapping
- One naming scheme on both sides
- Modes become selectors
- The export table
- Writing tokens.css
- Loading it
- Keeping both sides in step
The mapping
| Design tool | Exponential theme |
|---|---|
| Collection of primitive colors (ramps) | not in CSS, or a commented reference block (Color palettes and ramps) |
| Semantic color variable (text, surface, accent) | --site-* color token |
| Light mode / dark mode | :root values / dark values (Modes become selectors) |
| Number variables for spacing | --site-space-* tokens |
| Number variables for font sizes | --site-text-* tokens |
| Corner radius variable | the one --site-radius token |
| Text styles | classes in the components stylesheet, built from tokens |
| Brand modes (several brands) | a brand stylesheet per brand design (Designing for several brands in multisite) |
One naming scheme on both sides
Name the design tool variable exactly as the token, minus the prefix and dashes the tool does not like:
| Design tool | CSS |
|---|---|
color/ink | --site-ink |
color/accent | --site-accent |
space/3 | --site-space-3 |
text/l | --site-text-l |
Use your theme's own prefix instead of site if you prefer, but one prefix for the whole design (the admin uses
--a4-). Never name a semantic variable after its value (blue), because its dark value will not be blue.
Modes become selectors
A design tool switches a frame between modes; CSS switches the values by selector. The pattern the designer help uses for a public design follows the system setting, and also honors an explicit choice once a switch exists (Dark mode with prefers-color-scheme):
:root { /* light values */ }
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) { color-scheme: dark; /* dark values */ }
}
:root[data-theme="dark"] { color-scheme: dark; /* dark values */ }Only color tokens change between modes. Spacing, sizes, radius and fonts are defined once in :root.
The export table
Most tools can export variables as JSON or list them. Whatever the export format, turn it into a table the developer can check line by line, and keep it in the theme's repository:
| Token | Light | Dark | Notes |
|---|---|---|---|
--site-ink | #1f2430 | #e8ebf0 | body text |
--site-surface | #ffffff | #171c25 | page background |
--site-accent | #0b5cad | #7fb3f0 | links, primary buttons |
--site-space-3 | 1rem | same in both | |
--site-radius | 0.5rem | same in both |
These example values are the starter set from Design tokens;
use your own. Convert pixel numbers to rem (divide by 16) for spacing and type.
Writing tokens.css
The token file is a plain stylesheet in the design: design/mytheme/stylesheets/tokens.css. Write it from the export
table, in the same order, with the light values in :root and the dark values in the two dark selectors. If your team
uses a build step to generate it from the export, commit the generated file, because the packer reads stylesheets
from the design folder at run time; it has no build step of its own.
Never put a token value in a template, a <style> block or a style="" attribute
(No inline CSS).
Loading it
The token stylesheet loads first, before components, through the stylesheet list of the design and the packer
(Loading stylesheets). A change reaches browsers through the packed
file, whose name carries the modification time; never add a ?v= query to the link
(No version queries on asset links).
Keeping both sides in step
- The export table is the source of truth; the design tool and
tokens.cssboth follow it. - A new token gets its dark value in the same change.
- Review once per release: tokens in CSS that no stylesheet uses, and variables in the design tool that have no token, are both drift. The style guide page shows the coded values.
Related pages
- Design tokens
- Color palettes and ramps
- Dark mode and design tokens in themes
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.