Skip to content
html liquid text Background —
Text —
Border —
Outline —
Button —
Colors
src/css/utilities/colors.css
Use color utility classes instead of hardcoding hex values or raw color / background-color declarations.
Scheme-aware variants (color-bg__scheme-bg, color-tx__scheme-fg, etc.) automatically reflect the color scheme set on the nearest parent section or block — prefer these over body-level utilities inside themed sections.
How it works
Colors are never written as raw hex values. Everything flows through CSS custom properties so that merchant-configurable theme settings propagate automatically to every component.
There are two layers:
- Global CSS variables — set on
:rootinsnippets/theme__styles.liquid. These cover the body background, body foreground, auto-calculated shades, overlays, dividers, and input states. - Color scheme classes — merchant-defined palettes (e.g.
color__primary,color__secondary). Applying one to a container exposes a set of--scheme__*variables that any descendant can use.
Key files:
snippets/theme__styles.liquid— all CSS variable definitionssrc/css/utilities/colors.css— all utility class definitionsconfig/settings_schema.json— color scheme configuration
Global CSS variables
These are always available on :root regardless of scheme context.
Body colors:
| Variable | Description |
|---|---|
--color__background-body | Page background |
--color__foreground-body | Default text |
--color__text-default | Same as foreground-body |
--color__text-link | Link color |
Auto-calculated colors — derived from body background brightness, adapts on light and dark backgrounds:
| Group | Variables | Use |
|---|---|---|
| Overlays | --color__background-overlay-1/2/3 | Semi-transparent backgrounds, lightest → darkest |
| Shades | --color__background-shade-1/2/3 | Darken on light, lighten on dark — subtle → strong |
| Unshades | --color__background-unshade-1/2/3 | Inverse of shades — subtle → strong |
| Borders | --color__border-divider-1/2/3 | Divider lines, increasing opacity |
| Selected | --color__border-selected-1/2 | Selected / active states |
Input states:
| Variable | Use |
|---|---|
--input__default-background / --input__default-border | Default state |
--input__hover-background / --input__hover-border | Hover state |
--input__focus-background / --input__focus-border | Focus state |
Color schemes
Merchants configure color schemes in the theme editor. Each scheme exposes six variables when its class is applied to a container:
| Variable | Description |
|---|---|
--scheme__background | Scheme background |
--scheme__foreground | Scheme text |
--scheme__border | Scheme border |
--scheme__background-hover | Hover background |
--scheme__foreground-hover | Hover text |
--scheme__border-hover | Hover border |
Applying a scheme:
Add the scheme class to a container. All color-bg__scheme-*, color-tx__scheme-*, and color-br__scheme-* utilities inside will then resolve correctly.
<div class="color__primary">
<div class="color-bg__scheme-bg color-tx__scheme-fg color-br__scheme-br border">
Styled with the primary scheme
</div>
</div>
Color schemes can be applied with section or block settings letting merchants select any color scheme to be used.
<section class="color__{{ section.settings.color_scheme }} color-bg__scheme-bg color-tx__scheme-fg">
...
</section>
Color utility class reference
All classes follow this pattern:
color-[property]__[source]-[aspect]
Background — color-bg__*
| Class | Sets background to |
|---|---|
color-bg__body-bg | Body background |
color-bg__body-fg | Body foreground (inverted panel) |
color-bg__text-default | Default text color |
color-bg__scheme-bg | Scheme background (requires parent scheme class) |
color-bg__scheme-fg | Scheme foreground (requires parent scheme class) |
color-bg__overlay-1/2/3 | Semi-transparent overlays |
color-bg__shade-1/2/3 | Shade tints |
color-bg__unshade-1/2/3 | Unshade tints |
color-bg__blur-1/2/3 | Shade tint + backdrop-blur-sm |
color-bg__unblur-1/2/3 | Unshade tint + backdrop-blur-sm |
color-bg__error | Error state |
color-bg__success | Success state |
color-bg__input | Input default background |
color-bg__input--hover | Input hover background |
color-bg__input--focus | Input focus background |
Text — color-tx__*
| Class | Sets text color to |
|---|---|
color-tx__text-default | Default text (also styles ::placeholder at 75% opacity) |
color-tx__text-link | Link color |
color-tx__body-bg | Body background (text on dark surfaces) |
color-tx__body-fg | Body foreground |
color-tx__scheme-bg | Scheme background (requires parent scheme class) |
color-tx__scheme-fg | Scheme foreground (requires parent scheme class) |
color-tx__shade-1/2/3 | Shade colors (muted text) |
color-tx__error | Error text |
color-tx__success | Success text |
Border — color-br__*
| Class | Sets border color to |
|---|---|
color-br__body-bg | Body background |
color-br__body-fg | Body foreground |
color-br__text-default | Default text color |
color-br__divider-1/2/3 | Divider lines |
color-br__selected-1/2 | Selected / active state |
color-br__scheme-bg | Scheme background (requires parent scheme class) |
color-br__scheme-fg | Scheme foreground (requires parent scheme class) |
color-br__scheme-br | Scheme border (requires parent scheme class) |
color-br__scheme-bghv | Scheme background hover (requires parent scheme class) |
color-br__scheme-fghv | Scheme foreground hover (requires parent scheme class) |
color-br__scheme-brhv | Scheme border hover (requires parent scheme class) |
color-br__input | Input default border |
color-br__input--hover | Input hover border |
color-br__input--focus | Input focus border |
Outline — color-ol__*
Primarily used for focus rings.
| Class | Sets outline color to |
|---|---|
color-ol__divider-1 | Divider color |
color-ol__selected-1 | Selected state |
color-ol__transparent | Transparent (hides ring) |
color-ol__input | Input border color |
Button — color-bt__*
Button utilities set background, border, and text color together with :hover states in a single class. They also cascade color to non-.reset children.
| Class | Style |
|---|---|
color-bt__scheme | Scheme colors with hover states (requires parent scheme class) |
color-bt__main | Body-foreground fill, body-background text — high contrast "primary" |
color-bt__plain | Neutral fill, body foreground text |
color-bt__transparent | Transparent fill, shade hover |
color-bt__shade | Shade-2 fill, shade-3 hover |
color-bt__unshade | Unshade-2 fill, unshade-3 hover |