Design and content12 min read

Design system

The design system is the single source of truth for how your store looks. Instead of styling every page by hand, you set named tokens once here, and the storefront, the page builder blocks, the product cards, and the forms all read from them. Change a token and it updates everywhere that token is used.

The editor is organised into tabs down the side with a live preview beside them, so you can see each change before you save. You can keep several complete themes, switch the active one, and roll back to an earlier version at any time.

How the design system works

/admin/design-systemsaved to DesignSystem, Store.activeDesignSystemId

A design system is a set of named tokens: a colour called "primary", a text style called "h1", a button style called "primary", a shadow called "card", and so on. Nothing on the storefront hardcodes a colour or a font. Everything points at a token, so the whole store stays consistent and a single edit here ripples out to every page that uses it.

The editor groups those tokens into tabs: Colours, Typography, Buttons, Layout, Image radius, Spacing, Card styles, Form, Shadow, and Presets. The preview panel shows the effect of your changes live, and the controls at the top let you save, view history, and switch between saved themes.

1Pick the tab for what you want to change.
2Adjust the token and watch the live preview update.
3Save. The change applies to your active design system across the whole store.
4Open the storefront to confirm it looks right in context.

Note: Editing the design system is a super admin task. It changes the look of the entire store, so it sits above the day to day catalog and order permissions.

Tabs down the side, a live preview beside them, and version controls at the top.

Colours

/admin/design-system (Colours tab)

The palette is a fixed set of named colour roles plus any custom colours you add. Because buttons, cards, and other tokens can point at these names, changing one colour here updates everything that references it.

Primary and Secondary: Your main brand colours, used for buttons, links, and accents.
Background and Surface: The page background and the colour of raised surfaces such as cards and panels.
Text: body, heading, muted: The three core text colours for paragraph copy, headings, and secondary or helper text.
Link and Link hover: Link colour and the colour it changes to on hover.
Border: The default colour for dividers and outlines.
Status: success, warning, error, info: Feedback colours for messages, form validation, and alerts.
Badges: sale, new, sold out: The colours behind product badges on cards and product pages.
Custom colours: Add your own named colours to reuse as tokens anywhere a colour token is accepted.

Tip: The editor checks contrast between text and its background and flags combinations that would be hard to read, which helps keep the store accessible.

Brand, background, text, status, and badge colours, plus your own custom colours.

Typography

/admin/design-system (Typography tab)

Choose your fonts and define a reusable style for every kind of text on the store. Each style is a full set of controls, and each can shrink on smaller screens through tablet and mobile overrides.

Font families: A primary and a secondary font, chosen from the built in Google Fonts picker.
Heading styles: H1 through H6, each with its own size, weight, and spacing.
Text styles: Body, Lead, Small, and Blockquote for the different weights of copy.
Interface styles: Button, Nav, Product title, and Product price, so those specific elements read consistently.
Per style controls: Font family, size, weight, line height, letter spacing, text transform (such as uppercase), and decoration.
Responsive overrides: Optional tablet and mobile values so headings and other text scale down on smaller screens.
Custom styles: Add your own named text styles for anything the built in set does not cover.

Tip: Set Body and the headings first. Most other elements follow from those, so you get a coherent result with only a few changes.

A reusable style for every kind of text, previewed live as you edit.

Buttons

/admin/design-system (Buttons tab)

Define a handful of reusable button styles and three sizes. Blocks and forms reference a button style by name, so every call to action on the store stays on brand.

Styles: Primary, Secondary, Primary alt, Secondary alt, and Link, plus any custom styles you add.
Sizes: Small, Medium, and Large, each setting its own padding and font size.
Appearance: Background, text, border (colour, width, style), corner radius, padding, and the text style.
States: Separate colours for hover, active (pressed), and disabled.
Icons: Add a leading or trailing icon by name or image, with its own background, colour, radius, padding, and gap.
Animation presets: Optional hover animations: dot fill, sweep right, sweep up, expand from centre, or glow.

Note: Button colours accept either a hex value or a colour token name (such as "primary"). Using a token name keeps the button in sync automatically when you change the palette.

Reusable button styles (primary, secondary, and more), each with states and sizes.

Product card styles

/admin/design-system (Card styles tab)

Product cards are the most repeated component on a store, so they get their own set of presets. A card style you define here is used by the shop and collection pages and by the product blocks in the page builder.

Card kinds: Standard, Overlay, Side by side, Minimal, Editorial, Elevated, and Floating bar, each a different arrangement of image and details.
Image: Aspect ratio (such as 1:1, 4:3, 3:4, or 16:9) and padding around the image.
Spacing: The gap between the image and the details, and the gap between the stacked details.
Look: Background, border, corner radius, a shadow preset, and text alignment.
Content: The text style and colour for the product name and the price, and which button style the card uses.
Hover effect: None, image swap, zoom, or an action bar that slides over the image.
Overlay options: For the Overlay kind: a gradient scrim behind the text, a divider, and a quick action icon.

Tip: Start from the card kind closest to the look you want, then adjust the details, rather than building a card up from scratch.

Product card presets shared by the shop pages and the product blocks.

Spacing

/admin/design-system (Spacing tab)

A single spacing scale keeps gaps and padding consistent across the store. Blocks and layouts reference these steps by name instead of using arbitrary pixel values.

Scale: Six steps from xs to 2xl, from the tightest gap to the largest.
Responsive overrides: Optional tablet and mobile values so spacing tightens up on smaller screens.

A single spacing scale from xs to 2xl, with responsive overrides.

Shadows

/admin/design-system (Shadow tab)

Named shadow presets give the store a consistent sense of depth. Cards, popups, and other raised elements reference a shadow by name.

Presets: None, Soft, Medium, Strong, Inner, Card, Floating, and Dramatic, plus any custom shadows you add.
Layered: A single shadow token can stack several layers, which is how the subtle, realistic depth on cards is built.

Named shadow presets, from soft to dramatic, each a stack of layers.

Image corners

/admin/design-system (Image radius tab)

Set how rounded image corners are, per role, so product images, hero images, and avatars can each round differently while staying consistent within their type.

Global: The default corner radius for images that do not have a more specific role.
Product card, Hero, Gallery, Avatar: Per role radii for the most common image placements.

Corner radius per image role: global, product card, hero, gallery, and avatar.

Layout

/admin/design-system (Layout tab)

Page level structure tokens that control how wide content runs and how much breathing room sections get. Each value can differ across desktop, tablet, and mobile.

Content max width: How wide the main content column is allowed to grow.
Section padding and block gap: The vertical space around sections and the gap between stacked blocks.
Container padding: The horizontal breathing room at the edges of the page.
Page header: Padding and gap for page headers.
Grid: The number of columns and the gutter between them.

Content width, section spacing, container padding, and the grid, per breakpoint.

Forms

/admin/design-system (Form tab)

Default styling for form elements such as the contact form and the search form, so inputs match the rest of the store without styling each one.

Input: Background, border (default, focus, and error states), corner radius, padding, and font.
Label and placeholder: Label size, weight, and colour, and the placeholder colour.
Submit button: Which button style forms use for their submit action.
Error message: The colour and size of validation messages.

Note: These are defaults. An individual form element can still override its own styling where needed.

Default styling for inputs, labels, placeholders, and validation messages.

Preset themes

/admin/design-system (Presets tab)

Presets are complete starting point themes. Applying one fills in every tab at once, giving you a coherent look to refine rather than a blank slate.

1Open the Presets tab.
2Preview the available themes and apply the one closest to your brand.
3Move through the other tabs to adjust colours, type, and components to taste.

Complete starter themes you can apply and then refine.

Themes and version history

/admin/design-systemsaved to Store.activeDesignSystemId

You are not limited to one theme. A store can hold several complete design systems and mark one active, which is useful for seasonal looks or trying a redesign without losing the current one. Every save is versioned, so you can compare and roll back.

Active design system: The theme currently applied to the storefront. Switching it re-themes the whole store.
Version history: Earlier saved versions you can review and restore if a change did not work out.

AI Theme Assistant

/admin/design-system

With the AI Theme Assistant switched on, you can adjust the whole design system from a plain language request such as "make it feel more premium" or "warmer and more playful", and it updates the tokens for you to review and save.

Note: This needs the AI Theme Assistant feature flag enabled in Store Settings and an AI provider key configured under Integrations, AI.

A good workflow

1Start from a preset or your current active theme rather than a blank slate.
2Set colours and typography first, since most components inherit from them.
3Style the buttons and product cards, which are the most visible repeated elements.
4Use the live preview to check each change in context before saving.
5Save, then open the storefront to confirm the result on real pages.

Tip: Because everything reads from these tokens, make visual changes here rather than overriding styles page by page. One change in the design system keeps the entire store consistent.