Branding & Theming

The storefront's color identity flows from four CSS custom properties — the --brand* tokens. Change them in one place and every button, heading, badge, and highlight across the store, admin, and emails re-colors to match. You can edit the tokens directly, swap in one of the shipped presets, or let shoppers/admins pick a preset at runtime with a cookie-backed switcher.

This page explains how the token system works, the presets that ship out of the box, how the active preset is injected server-side (with no flash of the wrong color), how dark mode fits in, and how to add your own preset.

The --brand* tokens

Four tokens define the entire brand palette. They live in src/app/globals.css and are declared as space-separated HSL triplets (H S% L%) so they can be dropped straight into hsl(var(--brand)) without conversion.

:root {
  /* Brand theming tokens (space-separated HSL). Recolor the whole store
     by editing these four values, or by applying a preset's triplets from
     siteConfig.theme.presets to the --brand* variables. */
  --brand: 226 57% 21%;
  --brand-foreground: 210 40% 98%;
  --brand-accent: 24.6 95% 53.1%;
  --brand-accent-foreground: 0 0% 100%;
}

These tokens are wired into Tailwind as two color families in tailwind.config.ts, so you use them as ordinary utility classes:

brand: {
  DEFAULT: "hsl(var(--brand))",
  foreground: "hsl(var(--brand-foreground))",
},
"brand-accent": {
  DEFAULT: "hsl(var(--brand-accent))",
  foreground: "hsl(var(--brand-accent-foreground))",
},

That means classes like bg-brand, text-brand-foreground, bg-brand-accent, and text-brand-accent-foreground all resolve back to the tokens above. Recolor the tokens and every one of those utilities updates.

Recoloring the store

There are three ways to change the brand palette, from simplest to most dynamic.

:root {
  --brand: 340 82% 30%;
  --brand-foreground: 0 0% 100%;
  --brand-accent: 340 82% 52%;
  --brand-accent-foreground: 0 0% 100%;
}

Because dark mode reads the same tokens, restyling is a one-place change — you never have to hunt through components.

Theme presets

The boilerplate ships three ready-made palettes in siteConfig.theme in src/config/site.ts. Each preset is a ThemePreset whose four fields map 1:1 onto the --brand* tokens.

theme: {
  /** Active preset name — informational; the source of truth is globals.css. */
  active: "default",
  presets: {
    /** Ships out of the box: deep navy brand + vivid orange accent. */
    default: {
      brand: "226 57% 21%",
      brandForeground: "210 40% 98%",
      brandAccent: "24.6 95% 53.1%",
      brandAccentForeground: "0 0% 100%",
    },
    /** Green-forward alternative. */
    emerald: {
      brand: "160 84% 20%",
      brandForeground: "150 40% 98%",
      brandAccent: "160 84% 39%",
      brandAccentForeground: "0 0% 100%",
    },
    /** Purple-forward alternative. */
    violet: {
      brand: "263 60% 26%",
      brandForeground: "270 40% 98%",
      brandAccent: "262 83% 58%",
      brandAccentForeground: "0 0% 100%",
    },
  } satisfies Record<string, ThemePreset>,
},

The ThemePreset fields map onto tokens as follows:

How the active preset is injected (no flash)

The active preset is applied server-side by the ThemeStyle Server Component, which renders in the root layout at src/app/[locale]/layout.tsx:

{/* Injects the active brand preset's --brand* CSS variables. */}
<ThemeStyle />

Because the <style> is emitted during server rendering — before any HTML reaches the browser — there is no flash of the wrong brand color on first paint.

Resolving the active preset

On each request, getActivePresetName() (server-only, in src/lib/theme/server.ts) reads the theme cookie, validates it against the configured presets, and falls back to siteConfig.theme.active when the cookie is missing or invalid:

export function getActivePresetName(): PresetName {
  const cookieValue = cookies().get(THEME_COOKIE)?.value;
  if (cookieValue != null) {
    return resolvePresetName(cookieValue);
  }
  return resolvePresetName(siteConfig.theme.active);
}

resolvePresetName() (in src/lib/theme/presets.ts) guards against unknown/untrusted names, returning DEFAULT_PRESET_NAME ("default") for anything not registered in siteConfig.theme.presets.

Emitting the CSS variables

ThemeStyle then serializes the resolved preset into the four --brand* declarations via presetToCssVars() and inlines them:

export function ThemeStyle() {
  const active = getActivePresetName();

  // Default preset => defer entirely to globals.css (per-mode brand tokens).
  if (active === DEFAULT_PRESET_NAME) {
    return null;
  }

  const vars = presetToCssVars(siteConfig.theme.presets[active]);
  const css = `:root { ${vars} } .dark { ${vars} }`;

  return (
    <style
      dangerouslySetInnerHTML={{ __html: css }}
      data-theme-preset={active}
    />
  );
}

Two deliberate behaviors:

• default injects nothing. When the active preset is default, ThemeStyle returns null, leaving the carefully tuned per-mode --brand* values in globals.css completely untouched. The out-of-the-box look is unchanged when no cookie is set.
• Non-default presets recolor both modes. The preset's triplets are written to both :root and .dark, so a chosen preset can't be silently overridden by the .dark block in globals.css. Presets carry a single palette (no separate dark variant), so both modes share the same brand colors while every other token keeps its per-mode value.

Because the injected CSS only ever contains static, config-defined HSL triplets (never user input), it is safe to inline via dangerouslySetInnerHTML.

Dark mode

Dark mode is class-based. Tailwind is configured with:

darkMode: ["class"],

so dark styles apply whenever an ancestor (typically <html>) carries the .dark class. The dark palette is defined alongside the light one in globals.css, including brand tokens tuned for a dark background:

.dark {
  /* Brand tokens for dark mode: the deep-blue brand lightens so headings
     and dark surfaces stay legible on a dark background; the accent keeps
     its vivid hue. */
  --brand: 210 40% 90%;
  --brand-foreground: 222.2 47.4% 11.2%;
  --brand-accent: 24.6 95% 53.1%;
  --brand-accent-foreground: 0 0% 100%;
}

Note how the default dark palette lightens --brand (from 226 57% 21% to 210 40% 90%) so headings and dark surfaces stay legible, while --brand-accent keeps its vivid hue. This per-mode tuning only applies for the default preset — as noted above, a non-default preset intentionally writes the same brand colors to both :root and .dark.

Runtime theme switcher

ThemeSwitcher (in src/components/theme/ThemeSwitcher.tsx) is a client component that lets a shopper or admin pick a preset from a dropdown. The choice is persisted in the theme cookie and applied live.

Its flow:

function handleSelect(value: string): void {
  const next = resolvePresetName(value);
  writeThemeCookie(next);
  setCurrent(next);
  // Re-render the server tree so <ThemeStyle/> emits the new preset.
  router.refresh();
}

The component accepts an optional active?: PresetName prop (to avoid a cookie read on first paint when the parent already knows the active preset via getActivePresetName()), plus a className for the trigger button. It renders a Palette icon button that opens a radio-group dropdown.

Related helpers

These live in src/lib/theme/presets.ts and are safe to import from both server and client code:

Adding a new preset

presets: {
  // ...existing presets
  crimson: {
    brand: "347 77% 30%",
    brandForeground: "0 0% 100%",
    brandAccent: "347 89% 54%",
    brandAccentForeground: "0 0% 100%",
  },
},

theme: {
  active: "crimson",
  // ...
}

That's the whole change — no component edits. presetNames, PresetName, resolvePresetName, and the switcher UI all derive from siteConfig.theme.presets, so a new preset is picked up everywhere automatically.

Related