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 that reads a brand utility re-colors to match. (Transactional emails are not themed: they carry their own inline colors, because a mail client has no access to your stylesheet.)

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

: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 applied (no flash, no dynamic render)

ThemeStyle renders in the root layout at src/app/[locale]/layout.tsx:

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

It emits two things, and neither depends on who is asking:

1. Every preset, as attribute-scoped CSS — :root[data-theme="crimson"] { … } for each one.
2. A pre-paint script that reads the theme cookie and sets data-theme on <html>.

So the browser has all the palettes before it paints, and one attribute picks which applies. No flash of the wrong brand color, and — because the markup is byte-identical for every visitor — no per-request work.

Emitting the CSS

presetStylesheet() (in src/lib/theme/presets.ts) walks the configured presets and serializes each into the four --brand* declarations:

export function presetStylesheet(): string {
  return Object.entries(siteConfig.theme.presets)
    .filter(([name]) => name !== DEFAULT_PRESET_NAME)
    .map(([name, preset]) => {
      const vars = presetToCssVars(preset as ThemePreset);
      const scope = `:root[data-theme="${name}"]`;
      return `${scope}, ${scope} .dark { ${vars} }`;
    })
    .join("\n");
}

Three deliberate behaviors:

• default emits nothing. It has no rule and no attribute, so the tuned per-mode --brand* values in globals.css are left completely untouched. The out-of-the-box look is unchanged when no cookie is set.
• Non-default presets recolor both modes. Each writes its scope and scope .dark, so a chosen preset cannot be silently overridden by the .dark block in globals.css. Presets carry a single palette, so both modes share the brand colors while every other token keeps its per-mode value.
• Switching is one attribute write. ThemeSwitcher sets data-theme directly instead of calling router.refresh() — every palette is already on the page, so the change is instant and needs no server round trip.

Because the emitted CSS and script only ever contain config-defined values — HSL triplets and preset names, never user input — they are 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 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.

The two scopes that already own the palette

Nothing in the app puts .dark on <html>; there is no light/dark toggle. The shipped look comes from two token scopes further down the tree, and each wins for the elements inside it — a custom property set on a nearer ancestor is simply what descendants inherit:

The admin runs on .storefront too, so the back office reads the same dark tokens as the shop it manages — its shell and stat tiles are glass, and its tables are the flat --card surface, because a frosted panel behind a dense table costs legibility and repaints on every scroll.

The consequence is worth knowing before you ship a preset: on the storefront — and therefore in the admin — a preset changes the accent (the scope deliberately leaves --brand-accent alone and lightens --brand itself for legibility). Recoloring the deep brand means editing .storefront's own --brand in globals.css, not only the preset.

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);
  applyPreset(next);
}

The component accepts an optional active?: PresetName prop (skips the first-paint cookie read when the parent already knows the answer) and a className for the trigger button, and renders a Palette icon button that opens a radio-group dropdown. The cookie is read with useSyncExternalStore rather than an effect, so the server snapshot and the client snapshot agree and hydration does not flash the default.

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%",
  },
},

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