Theme Tokens
Every store sets its own colours, fonts and shapes in its design settings. A section that reads them looks at home on whichever store installs it; one that hardcodes colours looks like your shop on someone else's. There are three ways to read them.
See the difference
Switch the theme in the toolbar between Default, Midnight and Terracotta. The left card follows the store; the right one never changes.
Runs in your browser on sample data: the same engine and filters as the storefront. Widgets such as add to cart are simulated: clicking one shows what would happen on a store.
1. CSS variables, for styling
Available everywhere: in the editor, in the playground and on the live store. Nothing to declare. This is the one you want most of the time.
2. The settings object, for logic
The same values as data, for when you need to branch on one or put it somewhere CSS cannot reach, like an SVG fill or a colour filter.
3. Schema defaults that inherit
A colour setting can default to a theme token instead of a fixed hex. The merchant still gets a picker and can override it; they just start from a colour that matches their store.
All tokens
| CSS variable | Liquid | Schema default |
|---|---|---|
| --color-primary | settings.color_primary | @color.primary |
| --color-on-primary | settings.color_on_primary | @color.onPrimary |
| --color-secondary | settings.color_secondary | @color.secondary |
| --color-on-secondary | settings.color_on_secondary | @color.onSecondary |
| --color-accent | settings.color_accent | @color.accent |
| --color-on-accent | settings.color_on_accent | @color.onAccent |
| --color-background | settings.color_background | @color.background |
| --color-surface | settings.color_surface | @color.surface |
| --color-text | settings.color_text | @color.text |
| --color-text-muted | settings.color_text_muted | @color.textMuted |
| --color-border | settings.color_border | @color.border |
| --color-success · warning · danger | settings.color_success · color_warning · color_danger (+ on_*) | @color.success · … |
| --font-heading | settings.font_heading | — |
| --font-body | settings.font_body | — |
| --font-size-base | settings.font_size_base | — |
| --font-size-h1 … h6 | — | — |
| --font-weight-heading · --font-weight-body | settings.font_weight_heading · font_weight_body | — |
| --line-height-base | settings.line_height_base | — |
| --letter-spacing-heading | settings.letter_spacing_heading | — |
| --radius | settings.radius | @shape.radius |
| --border-width | settings.border_width | — |
| --shadow | settings.shadow | — |
| --layout-max-width | settings.layout_max_width | — |
| --section-spacing | settings.section_spacing | — |
| --gutter | settings.gutter | — |
| --button-radius | settings.button_radius | — |
| --button-weight | settings.button_weight | — |
| --button-transform | settings.button_style · settings.button_uppercase | — |
Sizes come with their unit in CSS (--radius: 12px) and as plain numbers in Liquid (settings.radius is 12), so add px yourself when you build CSS from the Liquid value.
Not everything has to inherit
Pair every background with its on- colour
--color-primary should be --color-on-primary, not --color-text. The on- colours are worked out per store to stay readable, so a dark primary gets white text and a pale one gets black.Related guides