Tokens & Tailwind classes ​

The merchant's brand identity — their primary color, surface color, button radius, heading font — lives in tokens. Tokens are stored on the theme document at config.tokens, emitted as CSS variables on :root, and bound to a curated set of Tailwind classes.

As a section author, you use the Tailwind classes. The merchant's edits flow through automatically.

How it works ​

1. Storage. theme.config.tokens is a flat object: { primary: "#222", accent: "#d4af37", fontHeading: "Playfair Display", radiusLg: "16px", ... }.
2. Emit. plugins/theme-vars.client.ts watches that object and writes a <style> block on :root like:
   css

   :root {
     --token-primary: #222;
     --token-accent: #d4af37;
     --token-fontHeading: "Playfair Display", system-ui, sans-serif;
     --token-radiusLg: 16px;
     /* ... */
   }

3. Bind. tailwind.config.js maps utility classes to those vars with a hard-coded fallback:
   js

   colors: {
     accent: 'var(--token-accent, #d4af37)',
   }

4. Use. Your section writes class="bg-accent". When the merchant changes their accent color, every bg-accent element on the storefront re-paints.

You don't need to read tokens directly. Use the Tailwind classes — the indirection is transparent.

Color tokens ​

Rule of thumb: never use Tailwind's stock color classes (text-gray-700, bg-zinc-100, ...) unless you genuinely don't want merchant control. Stock colors won't re-paint when the merchant changes their brand.

Border-radius tokens ​

rounded (Tailwind default 0.25rem) and rounded-full (9999px) are not token-driven on purpose — they're for chips and circular icons where merchant control would be confusing.

Font tokens ​

The theme exposes two font tokens. These are bound directly via CSS, not Tailwind class shortcuts:

In practice you rarely need to set the heading font explicitly — <h1>–<h6> already inherit --token-fontHeading via the global stylesheet in assets/main.css. Just use semantic heading tags and the merchant's font flows through.

If you do need to force a specific token:

<p :style="{ fontFamily: 'var(--token-fontHeading)' }">Stylized line</p>

But this is an escape hatch — the global rules cover 95% of cases.

Size + spacing tokens ​

Putting it together ​

A typical section root:

<section class="bg-surface text-ink">
  <div class="container mx-auto px-4">
    <h2 class="font-semibold text-2xl md:text-3xl">{{ title }}</h2>
    <p class="text-muted mt-2">{{ subtitle }}</p>
    <button class="bg-primary text-surface rounded-token-button px-6 py-3 hover:bg-accent">
      {{ ctaLabel }}
    </button>
  </div>
</section>

Every color, radius, and the container width respond to the merchant's token edits. Heading font is inherited via <h2>. No useStyles needed for the basics — those are reserved for named element scopes the merchant can override per-section.

When tokens aren't enough ​

Sometimes the merchant wants per-section control: "this banner only, change the title to gold." That's what styleKeys + useStyles are for (see Writing the component and Composables reference). The hierarchy:

1. Tokens = whole-storefront defaults. Edited in the theme Settings.
2. useStyles slots = per-section overrides. Edited in the inspector's Style panel.

Tokens render first; section-level styles override them. The merchant has both knobs.

Common mistakes ​

1. Using Tailwind stock colors (text-gray-700, bg-zinc-100). Won't re-paint on token change. Replace with text-ink, text-muted, bg-surface, bg-secondary.
2. Hard-coding hex colors (style="color: #222"). Same problem. Use a token class.
3. Using rounded-xl or rounded-2xl — Tailwind's stock radii. Use rounded-lg (which we redefined to --token-radiusLg) instead.
4. Setting font-family inline. Trust the global stylesheet; semantic tags already use the right token.

Reference: the full token list ​

Pulled from theme-vars.client.ts. Anything in config.tokens lands as --token-<key> on :root.

--token-primary
--token-secondary
--token-accent
--token-third
--token-surface
--token-text
--token-muted
--token-fontHeading
--token-fontBody
--token-fontSizeBase
--token-radiusSm
--token-radiusMd
--token-radiusLg
--token-radiusButton
--token-containerWidth
--token-sectionSpacing

If a merchant sets a custom token (config.tokens.brandShadow: "0 8px 30px rgba(...)"), it lands as --token-brandShadow automatically. You can read it via inline style or by extending tailwind.config.js.