Build a theme for Impulse Cart.

01What a theme is

The Impulse Cart storefront is server-rendered HTML with stable, well-named CSS classes. Its engine stylesheet (store.css) owns all the structure: the grid, the nav, where everything sits. Every colour, size and effect in it is a placeholder, for example background: var(--bg) or border-radius: var(--radius).

A theme is nothing more than a block that fills those placeholders in. You set the variables, the browser substitutes them everywhere, and the shop is reskinned. Because a theme cannot change structure, a bad theme can only ever look wrong, never break a store, and every theme survives platform updates.

02The two files

A theme is two files, dropped into theme/css/themes/:

theme/css/themes/
  sunrise.css     the skin: sets the variables in :root
  sunrise.json    the manifest: name, author, preview, licence

sunrise is a lowercase slug and must match both file names; it becomes the theme's id. Drop the two files in and the theme appears in the shop's Admin → Appearance automatically. No code change anywhere.

03How to read this reference

Every variable you can set is in the tables below, grouped by what it affects. Each row gives you everything in place:

• What it sets, and where in the shop it lands.
• Values: the actual values you can use. For anything with a fixed set (like a hover effect) every option is listed right in the row; the default is marked.

You only set the variables you want to change; every other one keeps its default. Set them all inside your theme's :root. Anything not listed here is engine internal (see What not to set).

04Colour

Twelve role-based colours. Each accepts any CSS colour: #hex, rgb(), or rgba() (use the alpha channel for translucent "glass" surfaces). The table says exactly what each one paints.

05Type

Two typefaces (body and headings), a body size and leading, a size for every heading level, and heading weight and tracking. Load the fonts yourself; the engine loads none for you. Heading sizes are optional ceilings: leave one unset and that heading keeps the shop's built-in responsive size; set it to cap the desktop size (the value shown is the built-in ceiling).

06Shape, depth and spacing

How round things are, how much they lift off the page, and how tightly the shop is packed.

07Motion and focus

08Buttons

A button is shape + size + hover effect. Its colours come from the accent pair you already set (fill --accent, label --on-accent).

Shape and size

Hover effect: --btn-hover

Set --btn-hover to one of these. Every option is here; the default is shine.

Fine-tune the shine effect: --shine-color (any colour, default rgba(255,255,255,.35)) and --shine-speed (a time, default .9s).

09Cards and images

Cards and product images take their shape from --radius / --card-radius and their depth from --shadow. Each also has one hover effect, picked from its own list right here.

Card hover: --card-hover

Set --card-hover to one of these. Default is lift.

Image hover: --thumb-hover

Set --thumb-hover to one of these. Default is zoom.

10Contrast rules

A theme is only valid if the text is readable. Hit these before you ship:

11What not to set

12The manifest

The .json file names the theme and describes its preview swatches. Minimum keys are id, name and licence.

{
  "id": "sunrise",
  "name": "Sunrise",
  "author": "Your Studio",
  "description": "A warm, bright light theme.",
  "version": "1.0.0",
  "licence": "domain",
  "preview": {
    "bg": "#FFFDFB", "nav": "#FFF3EC", "surf": "#FFFFFF",
    "border": "rgba(0,0,0,.12)", "thumb": "#F1E4DB",
    "text": "#241C17", "sub": "#7A6E64",
    "accent": "#C2410C", "on": "#FFFFFF"
  }
}

13A complete example

A full, valid theme. It only sets what it wants to change; every other variable keeps its default.

sunrise.css

/* Sunrise: a warm light theme for Impulse Cart. Skin only. */
:root {
  /* colour */
  --bg:            #FFFDFB;
  --text:          #241C17;
  --text-muted:    #7A6E64;
  --accent:        #C2410C;   /* dark enough to read as text */
  --accent-hover:  #9A3412;
  --on-accent:     #FFFFFF;
  --card:          #FFFFFF;
  --border:        rgba(0,0,0,.12);
  --nav:           #FFF3EC;

  /* type */
  --font:          "Inter", system-ui, sans-serif;
  --heading-font:  "Fraunces", Georgia, serif;
  --h1:            3rem;
  --heading-tracking: -0.03em;

  /* shape + depth */
  --radius:        12px;
  --density:       1.1;      /* a little airy */

  /* effects: pick one per area */
  --btn-hover:     glow;
  --card-hover:    lift;
  --thumb-hover:   zoom;
}

14Selling your theme

Every marketplace theme is sold, not given away. Set the manifest's licence to "domain"; the theme then needs a licence key tied to the buyer's shop domain, using the same signing scheme as the store licence, so there is almost no new plumbing.

How a sale works: the buyer purchases the theme from the marketplace and gives their shop domain. A key bound to that theme and domain is issued with the sale, and the buyer pastes it into Admin → Appearance. You never handle keys: you build the theme, submit it, and keep 70% of every sale.

15Ship checklist

• <id>.css sets your variables in :root; <id>.json has at least id, name, licence.
• id matches both file names and is a lowercase slug.
• Each --*-hover is set to one keyword from its list.
• All five contrast rules pass.
• You set none of the --z-* variables and changed no structure.
• Checked on both mobile and desktop.
• "licence": "domain" is set in the manifest.