Themes

Four themes ship with the store:

Starter   admin
Starter   storefront
Amelia    storefront
Brutal    storefront

Each one defines a full set of colours, fonts and text sizes, spacing, corner radii and border widths, shadows, and transition timings. Those are compiled into CSS variables that every component reads.

The consequence is that a theme is not a skin painted over a fixed design. Changing the theme changes the values the components were built to read, which is why the three storefront themes look genuinely different rather than differently coloured.

Settings → Appearance activates one storefront theme and one admin theme.

Two separate choices

The storefront theme and the admin theme are stored as two settings and picked independently.

A theme declares which of the two it belongs to, and is rejected if applied to the other. An admin theme is not a storefront theme with the wrong colours — the two surfaces need different token sets, so the check refuses the mismatch rather than rendering something broken.

A new store starts on:

storefront   Amelia
admin        Starter

A market record can also pin its own storefront theme, though the Markets form has no field for it.

What a theme defines

The token groups are:

• Core and semantic colours, including success, warning, danger and info
• Heading, body and monospace fonts, with their sizes, weights, line heights and letter spacing
• Page, section, card and grid spacing
• Radius and border widths
• Shadows
• Transition durations and easings

Three of those are fixed scales rather than free values:

7   radius steps
3   border widths
6   shadow levels

Scales rather than free numbers is what keeps a store looking like one store. A page cannot end up with nine slightly different corner radii, because there are only seven to choose from.

Storefront themes add their own surface tokens on top of that set, and can carry custom CSS.

Block colour palettes

On Storefront → Settings, the active storefront theme appears as a read-only palette.

The palette is read-only on purpose: editing the theme's own colours would move every block on every page, which is almost never what you want when you are trying to make one section stand out.

The move instead is:

1. Duplicate the palette to get an editable copy
2. Adjust its colours
3. Assign it to a single block

That block then renders in those colours, while the rest of the page keeps the theme's.

No dark mode

Each theme defines one palette. No dark variant is generated from it.

A generated dark palette would be a guess at the contrast decisions somebody made deliberately in the light one, and it would break the moment a theme used colour to mean something rather than to look a certain way.

Beyond the tokens

The storefront and the admin are React components in your own repository.

So anything the tokens do not cover is not a limitation of the theming system — it is code a developer can change. There is no separate template language to learn, and no ceiling where customisation stops and you have to wait for the platform to add a setting.

Where the themes live

For a developer who needs to edit one:

config/theme.ts
config/themes/

Choosing and customising

Open Settings → Appearance and activate a storefront theme and an admin theme. They are independent, so the admin does not have to match the shop.

On Storefront → Settings, duplicate the theme's palette, edit the copy, and assign it to any block that needs different colours. Do this instead of editing the theme when the change is meant for one section.

For anything the tokens do not cover, ask a developer to edit the theme file or the components themselves.

The order to work in is the one that keeps the store coherent:

Reach for the theme when the whole store should change, a block palette when one section should, and the components only when neither can express what you want.

Related