LiquidTheme Tokens

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.

Inherit vs hardcode
Playground
Loading editor…

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.

liquid
<section style="background: var(--color-surface); padding: var(--section-spacing) 0;">
<h2 style="font-family: var(--font-heading); color: var(--color-text);">{{ section.settings.heading }}</h2>
<a style="background: var(--color-primary); color: var(--color-on-primary);
border-radius: var(--button-radius); font-weight: var(--button-weight);">{{ section.settings.cta }}</a>
</section>

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.

liquid
{% if settings.button_style == 'outline' %}
<a class="btn-outline">{{ section.settings.cta }}</a>
{% else %}
<a class="btn-solid">{{ section.settings.cta }}</a>
{% endif %}
<svg width="16" height="16"><circle fill="{{ settings.color_accent }}" cx="8" cy="8" r="8" /></svg>
<div style="background: {{ settings.color_primary | color_modify: 'alpha', 0.1 }};">A soft tint</div>

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.

json
{ "id": "background", "type": "color", "label": "Background", "default": "@color.surface" }
{ "id": "button_color", "type": "color", "label": "Button", "default": "@color.primary" }

All tokens

CSS variableLiquidSchema default
--color-primarysettings.color_primary@color.primary
--color-on-primarysettings.color_on_primary@color.onPrimary
--color-secondarysettings.color_secondary@color.secondary
--color-on-secondarysettings.color_on_secondary@color.onSecondary
--color-accentsettings.color_accent@color.accent
--color-on-accentsettings.color_on_accent@color.onAccent
--color-backgroundsettings.color_background@color.background
--color-surfacesettings.color_surface@color.surface
--color-textsettings.color_text@color.text
--color-text-mutedsettings.color_text_muted@color.textMuted
--color-bordersettings.color_border@color.border
--color-success · warning · dangersettings.color_success · color_warning · color_danger (+ on_*)@color.success · …
--font-headingsettings.font_heading—
--font-bodysettings.font_body—
--font-size-basesettings.font_size_base—
--font-size-h1 … h6——
--font-weight-heading · --font-weight-bodysettings.font_weight_heading · font_weight_body—
--line-height-basesettings.line_height_base—
--letter-spacing-headingsettings.letter_spacing_heading—
--radiussettings.radius@shape.radius
--border-widthsettings.border_width—
--shadowsettings.shadow—
--layout-max-widthsettings.layout_max_width—
--section-spacingsettings.section_spacing—
--guttersettings.gutter—
--button-radiussettings.button_radius—
--button-weightsettings.button_weight—
--button-transformsettings.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

A deliberately off-palette accent is a design decision, and hardcoding a hex is allowed. The theme review only flags a hardcoded colour when it is the same colour the theme would have given you anyway, because then the merchant loses the ability to recolour it for nothing.

Pair every background with its on- colour

Text on --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.

Still stuck? Our team reads every message.

Need help?