Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 61 ยท JavaScript, CSS and Design

CSS for Themes: Variables, Layout and Responsiveness

Style Shopify themes with CSS variables from theme settings, color schemes, grid, container queries and mobile-first rules; learn the stylesheet and style tags.

A Shopify theme has an unusual styling problem: the merchant, not you, picks the colors, fonts and spacing, and they change them any time in the theme editor. Your CSS cannot hard-code a brand color, because the next store will use another one. The solution is to write CSS in terms of variables whose values come from theme settings, and to keep the layout flexible with modern tools such as grid, container queries and a mobile-first approach.

This lesson shows how settings become CSS variables, how color schemes work, where to put CSS (an asset file, an inline {% style %} tag or a section's {% stylesheet %} tag), and how to build layouts that adapt to the space they get. It follows Global Theme Settings and pairs with JavaScript in Themes.

The Liquid that reads settings runs only on Shopify, so those theme snippets are read-only. The live parts are honest stand-ins: a JavaScript function that turns a settings object into CSS variables the same way a {% style %} block would, and an HTML preview that uses real CSS variables, grid and container queries. This lesson targets current Online Store 2.0 themes and current evergreen browsers.

Where theme CSS lives

There are four places, each with a purpose:

Place Liquid runs? Use it for
assets/base.css loaded with asset_url no shared styles for the whole theme, cached by the browser
{% style %} ... {% endstyle %} yes CSS that depends on settings (variables, per-section values)
{% stylesheet %} ... {% endstylesheet %} no static CSS that belongs to one section, snippet or block

The {% stylesheet %} tag can appear only in sections, snippets and blocks (not in layouts or templates). Shopify collects the contents of every such tag on the page and serves them together in one file, once, even if a section appears twice. Liquid is not processed inside it. The {% javascript %} tag works the same way for scripts. Both are convenient for small, component-specific code; for big shared code use files in assets/.

The {% style %} tag is rendered with Liquid, and it outputs an inline <style> element. In the theme editor Shopify adds an attribute so it can replace the styles when a setting changes, which is why you should use {% style %} rather than writing your own <style> tag with Liquid.

LIQUID
{% style %}
  .hero-{{ section.id }} {
    --hero-overlay: {{ section.settings.overlay_opacity | divided_by: 100.0 }};
    min-height: {{ section.settings.height }}vh;
  }
{% endstyle %}

Putting the section id in the selector gives each instance its own values. That also means the CSS differs per section, so it cannot be cached as a static file, which is the trade-off to keep in mind: use inline style for the few values that depend on settings, and keep the rules in cached files.

Settings become CSS variables

Global settings (colors, fonts, spacing, corner radius) are defined in config/settings_schema.json and read through settings. A theme turns them into variables once, in the layout's head, and everything else uses the variables:

LIQUID
{% style %}
  :root {
    --font-body-family: {{ settings.type_body_font.family }}, {{ settings.type_body_font.fallback_families }};
    --font-body-weight: {{ settings.type_body_font.weight }};
    --page-width: {{ settings.page_width | append: 'px' }};
    --radius: {{ settings.corner_radius }}px;
  }

  {%- for scheme in settings.color_schemes -%}
    .color-{{ scheme.id }} {
      --color-background: {{ scheme.settings.background.red }}, {{ scheme.settings.background.green }}, {{ scheme.settings.background.blue }};
      --color-foreground: {{ scheme.settings.text.red }}, {{ scheme.settings.text.green }}, {{ scheme.settings.text.blue }};
      --color-button: {{ scheme.settings.button.red }}, {{ scheme.settings.button.green }}, {{ scheme.settings.button.blue }};
    }
  {%- endfor -%}
{% endstyle %}

A color setting is a Liquid color object with red, green, blue, alpha, hue, saturation and lightness properties, and filters such as color_modify and color_darken. Storing the channels as r, g, b triples is a common trick, because CSS can then add its own transparency later: rgb(var(--color-foreground), 0.6). Font settings expose family, weight and style, and the font_face filter can emit the matching @font-face rule.

Then your component CSS never mentions a literal color:

CSS
.card {
  background: rgb(var(--color-background));
  color: rgb(var(--color-foreground));
  border: 1px solid rgb(var(--color-foreground), 0.15);
  border-radius: var(--radius);
}

Color schemes

A color scheme is a named group of colors (background, text, button, and so on). The theme defines several in settings, and each section lets the merchant choose one with a color_scheme setting. The section then gets a class such as color-scheme-2 on its wrapper, which redefines the variables for everything inside. Because CSS variables inherit, a card in a dark section turns dark without any change to the card's CSS.

LIQUID
<section class="hero color-{{ section.settings.color_scheme }}">
  ...
</section>

This is the main reason to never write color: #333 in section CSS: one light-on-dark scheme and the text would vanish. If you need an in-between color, derive it: rgb(var(--color-foreground), 0.7).

flowchart LR
  S["settings_data.json<br/>color schemes"] --> V["style tag in theme.liquid<br/>--color-* per scheme"]
  M["section.settings.color_scheme"] --> C["class on the section"]
  V --> R["CSS rules use var(--color-*)"]
  C --> R

Settings define variables once; a class on each section picks which set applies.

Layout: grid, flexible widths and container queries

Mobile-first means the base CSS describes the small screen and min-width media queries add complexity for larger ones. A product grid, for example, starts with two columns and widens:

CSS
.product-grid {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
  gap: var(--grid-gap, 1rem);
}
@media (min-width: 750px)  { .product-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); } }
@media (min-width: 990px)  { .product-grid { grid-template-columns: repeat(4, minmax(0, 1fr)); } }

Better still, let the grid decide: grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr)) makes as many columns as fit, with no breakpoints.

Media queries look at the viewport, but a theme component can be placed anywhere: full width, in a narrow sidebar, inside a two-column section. A product card should adapt to the space it was given, not the window. That is what container queries do:

CSS
.product-grid-item { container-type: inline-size; }

.card { display: grid; gap: .5rem; }
@container (min-width: 22rem) {
  .card { grid-template-columns: 8rem 1fr; align-items: center; }
}

Container queries are supported in all current evergreen browsers, so they are safe for a modern theme. Use clamp() for fluid type and spacing (font-size: clamp(1rem, 0.9rem + 0.5vw, 1.25rem)), logical properties (margin-inline, padding-block) so right-to-left languages work without extra CSS (see Translations, Markets and Localization), and prefers-reduced-motion for animation (see Accessibility in Themes).

Keeping theme CSS small and safe

  • Class names should be specific to the component (.cart-drawer__total), so apps and merchant custom CSS do not collide with yours.
  • Avoid !important and ID selectors; the merchant's own CSS in the editor needs to override you.
  • Do not use deep nesting from the page root; styles should survive moving a section elsewhere.
  • Remember that unused CSS delays rendering. Splitting component CSS into the {% stylesheet %} tags lets Shopify include only what the page uses; see Theme Performance and Core Web Vitals.

Stand-in: settings to CSS variables

This stand-in does what the {% style %} blocks above do: it turns a settings object, including color schemes, into a CSS string, splitting hex colors into channel triples. Run it to see the exact CSS that would appear in the page head.

JS Stand-in: settings object to CSS variables

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The output is the CSS a real {% style %} block would print, with #14213d becoming 20, 33, 61 and so on. Change a color in settings and rerun to see how one edit flows into every rule that uses the variable.

Live example: schemes, grid and container queries

The preview below uses real CSS. Two color schemes redefine the same three variables; the cards use only the variables; a container query switches each card to a side-by-side layout when it has enough room. Resize the preview or switch the scheme to see both behaviors.

Color schemes and container queries

The two narrow cards stay stacked while the wide card, in the same stylesheet, gets two columns. The card CSS contains no literal colors, so changing the scheme is just changing a class.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why should section CSS use var(--color-foreground) instead of #333?

    Colors come from settings and color schemes. Variables inherit, so the same rule works in every scheme and store.
  2. 2. Which tag lets you use Liquid settings inside inline CSS and works with the theme editor's live updates?

    {% style %} renders Liquid and outputs an inline style element the editor can refresh. {% stylesheet %} is static CSS collected into one file.
  3. 3. What is the advantage of container queries over media queries for a product card?

    A card may appear full width or in a narrow column. A container query adapts to the space available, not the window size.
  4. 4. Where can the {% stylesheet %} tag be used?

    It belongs to components: sections, snippets and blocks. Shopify combines all of them into one served file and processes no Liquid inside.
  5. 5. What does mobile-first CSS mean?

    You style the smallest layout first and enhance it with min-width queries, which keeps the base CSS simple.

Summary

  • Write component CSS against variables, never against literal brand colors; settings feed the variables.
  • Use {% style %} for CSS that needs Liquid, {% stylesheet %} for static component CSS, and assets/ files for shared, cacheable code.
  • Color schemes redefine the same variables per section with a class; inheritance does the rest.
  • Build layouts mobile-first with grid, clamp() and logical properties, and use container queries so components adapt to the space they get.
  • Keep selectors specific and light so merchant CSS and apps can coexist.

Next, learn how pages update without reloads in The Section Rendering API and Dynamic Updates.