Theme authoring

Build a storefront theme from tokens, sections and templates, then export it as a versioned, installable bundle.

Version v1 · updated 2026-02-01

A theme is three things: a token set (colour, type, radius, spacing), a set of sections a merchant can arrange, and templates that decide which sections a page starts with. Nothing else — a theme never ships business logic.

Tokens#

{
  "tokens": {
    "color.primary": "#0f7d74",
    "color.background": "#fffdf8",
    "radius.md": "0.625rem",
    "font.display": "Hind Siliguri",
    "font.body": "Inter"
  }
}

Sections read tokens, never raw hex. That is what makes a theme themeable at all: a merchant changing `color.primary` must not have to find fourteen hardcoded buttons.

A section schema#

export const schema = {
  type: "hero.split",
  label: { en: "Split hero", bn: "স্প্লিট হিরো" },
  // Hydration mode is part of the contract, not an afterthought: a static
  // section costs zero client JS and still renders on a dead network.
  hydration: "static",
  settings: [
    { id: "heading", type: "text", localized: true, max: 90, required: true },
    { id: "image", type: "image", alt: "required" },
    { id: "cta", type: "link" },
  ],
} as const;

• Every text setting is localizable — Bangla is a first-class locale, not a fallback.
• Every image setting requires alt text; the publish gate refuses a theme that can render an image without one.
• A section that throws is contained by the widget boundary: the page keeps rendering, the studio shows why.

Export and versioning#

Exporting produces a signed bundle with a semver version and a schema fingerprint. Installing a bundle whose fingerprint does not match the store's runtime is refused rather than half-applied.