Theme

Theme is where modes live. It is the surface layer every component consumes, and the only layer that swaps values when the mode switches.

Theme tokens describe roles: --background, --card, --primary, --destructive. They resolve to palette values based on the active mode. No component reaches past theme to grab a palette value directly. Change --primary at the theme layer, and every primary surface in the product follows.

Theme follows shadcn/ui's background-foreground pattern, with a few departures noted at the bottom of this page.

Base

Base tokens cover the bedrock surfaces and the text that sits on them.

.card {
  background: var(--card);
  color: var(--card-foreground);
  border: 1px solid var(--border);
  border-radius: var(--radius-card);
}

Overlay

Overlay tokens cover dimming, fading, and the muted text that goes with them.

Overlays swap their underlying primitive between modes: --muted uses shade-* in light and tint-* in dark; --faded does the opposite. The semantic stays constant. Muted is always darker than the surface, faded is always lighter, even though the underlying token shifts.

.section-divider {
  background: var(--muted);
  color: var(--muted-foreground);
}

Brand

Brand tokens map the active mode to a step on each corporate scale.

Brand colors step lighter in dark mode (600 → 500, 500 → 400) so they stay readable against the darker background. Tertiary takes a slightly lighter step than primary and secondary. Most tertiary brand colors carry more chroma per step, so a lighter base reads cleaner.

Re-target the scale steps at the theme layer to rebrand without touching components. See Corporate for the full scales.

Status

Status tokens cover info, success, warning, and destructive.

Status colors step darker in dark mode (lightness drops by roughly 0.08–0.11), opposite to brand. The reasoning: a status color is a signal, not an identity. Lightening a destructive red in dark mode makes errors the brightest thing on the page. Darkening keeps the signal present without overshouting the rest of the UI.

Status values are written in raw OKLCH so they sit in the same color space as every other Zazz token. Lightness, chroma, and hue can be tuned independently to hit a contrast target in either mode.

How modes work

Zazz responds to both system preference and an explicit class.

:root {
  /* light by default */
}

@media (prefers-color-scheme: dark) {
  :root {
    /* dark when the OS asks for it */
  }
}

:is(.dark, .dark *) {
  /* dark whenever .dark is on an ancestor */
}

Force a mode by adding .dark (or any class you wire up) anywhere up the tree: for an in-page theme switcher, a preview panel, or a section that overrides the system default.

To add a new mode (high-contrast, brand-takeover, holiday), repeat the pattern: a new selector that re-points the same theme variables. Components never branch on mode; they consume theme tokens and trust them.

Beyond Tailwind and shadcn

The theme layer is compatible with Tailwind and shadcn and borrows the parts that work: background-foreground naming, color-scale conventions, the .dark ancestor pattern. Where Zazz makes different choices, the framework is geared more toward marketing and ecommerce sites than toward web apps. Both work; the defaults are tuned for the former.

The choices worth knowing:

• A text-on-border role exists. --border-foreground colors text that sits on a border (outlined buttons, ghost inputs, bordered tags) without reaching into a palette directly.
• Overlays split into muted and faded. Muted dims, faded fades. The split matters when stacking on product photography, building hero overlays, or designing dark-mode surfaces that need a different scrim than the light equivalent.
• Tertiary brand is a first-class role. Marketing and ecommerce clients often have three identity colors: a primary, an accent, and a "callout" hue used on sale tags, badges, or seasonal moments.
• Four status roles ship out of the box. Info, success, warning, and destructive in a consistent foreground-paired shape, so checkout flows and form validation work without bespoke wiring.
• Status darkens in dark mode. Opposite of brand. Alerts should not be the loudest thing on a marketing surface that's already loud with imagery.

Where to next