Theming

The theme is the site's design foundation: one palette, two fonts, one corner radius, shared by every page. It is edited from the Theme panel in the builder, stored with the site, and emitted as CSS variables that both the builder canvas and the published page read.

Changing the theme recolors everything at once. That is the point - blocks are styled with semantic classes like bg-primary and text-muted-foreground rather than bg-blue-600, so the theme stays the single place a brand change happens.

What the theme contains

Three groups, plus an optional site layout:

Group What it holds
Fonts A heading family and a body family, picked from registered fonts
Border radius One radius value in pixels, from which large/medium/small are derived
Colors 19 semantic colors, each with a light value and a dark value
Site layout Optional. How wide page content runs: fluid, container or narrow. See Site layout

There is no spacing scale, shadow scale, or type scale in the theme. Those stay in the utility classes on each block, or in a design token if you want them reusable.

Colors

Every color is a pair - a light-mode value and a dark-mode value - stored as 6-digit hex. The panel groups them the way you tend to change them:

Panel group Keys
Body background, foreground
Primary primary, primary-foreground
Secondary secondary, secondary-foreground
Border, Input & Ring border, input, ring
Card card, card-foreground
Popover popover, popover-foreground
Muted muted, muted-foreground
Accent accent, accent-foreground
Destructive destructive, destructive-foreground

The -foreground half of a pair is what sits on top of the other half. primary is the button fill, primary-foreground is the label on it. Keeping that relationship correct is what makes a theme swap safe: change primary to a dark navy and primary-foreground to white and every button, badge, and link that uses the pair stays readable.

background/foreground are the page defaults, muted is for secondary surfaces and disabled states, accent is the hover/highlight surface, border/input/ring cover outlines and focus rings.

Which half of each pair you are editing follows the dark-mode toggle in the Colors header. Toggle to dark, edit a swatch, and you have changed the dark value only.

Border radius

One number, in pixels, between 0 and 50. From it the system derives three steps:

Class Value
rounded-lg the radius you set
rounded-md radius − 2px
rounded-sm radius − 4px

Set 0 for a hard-edged brand, 6 for the default, 16 for something soft. Values under 4px make the derived small step compute below zero, which browsers clamp to square - fine in practice, but it means 0, 1, 2, and 3 look nearly identical on small elements.

Fonts

The theme stores two family names, heading and body. The dropdowns list every font registered in the project, and the choice drives --font-heading and --font-body, the font-heading and font-body classes, and the base rules that give h1-h6 the heading family and body the body family.

Adding a family to those dropdowns is a code change. See Custom fonts.

Site layout

With the siteLayout feature flag on, the Theme panel shows a Site layout select. It sets how wide content runs across the whole site:

Layout Content width
Fluid Full width
Container Centred, at most 1280px
Narrow Centred, at most 768px

The choice is emitted as the --site-content-width CSS variable in the page head, on the live page and in the builder canvas. Blocks opt in by using the Site-Content-Width design token (dt#site-content-width), which centres them at that width and falls back to 1280px when no layout is set. Blocks that do not use the token are not capped, so full-bleed sections stay full-bleed. The flag is off by default. See Section layout tokens for the gutter and layout tokens that go with it.

Presets

The Presets dropdown ships five complete themes:

Shadcn default, Twitter theme, Solarized theme, Claude theme, Supabase theme

Select one and click Apply. It replaces colors, fonts, and radius together. A toast appears with an Undo action for 15 seconds - use it immediately if the preset was a mistake, because it is the only one-click way back to the previous theme.

Presets are a good starting point rather than a destination. Apply the one closest to your brand, then adjust primary and the fonts.

A project can ship its own preset list in code instead, through the themePresets builder prop. Supplying presets replaces the built-in five rather than adding to them, which is what you want for a locked-down brand.

Importing a theme from CSS

If you already have a shadcn-style stylesheet - a :root block and a .dark block of CSS variables - you can paste it in rather than clicking through 19 swatches. The importer reads the color variables, --radius, and the font variable, and maps them onto the theme.

Two things to check after an import:

  • Fonts collapse to one. The importer reads a single font variable and assigns it to both heading and body. Set them separately afterwards if they differ.
  • Missing variables stay at their current value. Only four colors are strictly validated, so a partial stylesheet imports without complaint and leaves gaps. Scan the swatches once before publishing.

Alpha channels are dropped - an 8-digit hex is truncated to its 6-digit RGB. Use opacity modifiers in classes (bg-primary/90) instead of baking transparency into the theme.

Generating a theme with AI

When the AI features are enabled, the Theme panel gets a generator. Describe the look you want - "warm editorial, cream background, deep green accents" - and it produces a full theme: all 19 colors in both modes, a radius, and fonts chosen from your registered families only.

The result lands in the panel like a preset, with the same 15-second Undo. It draws on the site's brand look and tone if those are set. Nothing is published until you publish.

See AI overview and AI setup.

Changing the theme through an agent

When the MCP server runs with the design system turned on, an AI agent in Claude, Cursor or VS Code can change the theme too: fonts, radius and any colors, as [light, dark] pairs. It works on the same draft as the Theme panel, with a few guards the panel does not have:

  • Only fonts registered on the site are accepted.
  • A change that leaves a surface and foreground pair under 3:1 is refused. One under 4.5:1 is saved but reported.
  • The agent publishes the theme only after you have seen a preview and approved it. You can also publish from the builder as usual.

See Design System for Agents.

Dark mode

The theme always carries dark values, but showing them on the live site is your decision.

In the builder, a dark-mode switch in the canvas top bar and in the Colors header previews the dark palette and tells the color pickers which half of each pair to edit. It is a local preview toggle - it is not a site setting, and it is not published. The switch is behind the darkMode feature flag, which is off by default.

On the published site, ChaiBuilder emits the dark palette but never activates it. Dark mode turns on when the dark class is present on the <html> element, and your application owns that - whether from a user toggle, a stored preference, or prefers-color-scheme. A site that never adds the class simply always renders light, with the dark values sitting unused.

What reaches the page

The theme is emitted as a <style id="theme-variables"> block containing a :root rule with the light values and a .dark rule with the dark values:

:root {
  --font-heading: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-body: "Inter", ui-sans-serif, system-ui, sans-serif;
  --radius: 6px;
  --background: 0 0% 100%;
  --foreground: 0 0% 9%;
  --primary: 220 90% 53%;
  /* ...one line per color key */
}
.dark {
  --background: 0 0% 14%;
  /* ...the dark half of each pair */
}

Colors are stored as bare HSL triplets, not hsl(...) strings, so utilities can wrap them as hsl(var(--primary)) and still support opacity modifiers like bg-primary/90.

The classes this gives block authors:

Kind Classes
Backgrounds bg-background, bg-card, bg-popover, bg-muted, bg-accent, bg-primary, bg-secondary, bg-destructive
Text text-foreground, text-muted-foreground, text-card-foreground, text-primary-foreground, text-secondary-foreground, text-accent-foreground, text-destructive-foreground
Borders and rings border-border, border-input, ring-ring
Radius rounded-lg, rounded-md, rounded-sm
Fonts font-heading, font-body

Every theme color also works with the other color-consuming prefixes - from-, via-, to-, divide-, outline-, shadow- - and the class autocomplete in the styling panel offers all of them.

Alongside the theme variables, the page emits <style id="fonts-styles"> for the @font-face rules and <style id="page-styles"> for the compiled page CSS. Layout routes emit the same CSS through hoisted styles instead of ids.

Tailwind setup

ChaiBuilder is Tailwind CSS v4 only. The theme is bridged with a generated @theme static block that maps each variable into Tailwind's namespace - --color-primary: hsl(var(--primary)), --radius-lg: var(--radius), and so on. No JS config is involved, and container queries, typography and forms work without extra plugins.

Your own app's components resolve the same classes as builder blocks once your CSS entry imports Tailwind v4 and your project has the PostCSS plugin installed:

pnpm add -D @tailwindcss/postcss

getChaiTailwindTheme() is exported from chaipro/utils if you need the theme mapping as an object.

Coming from Tailwind v3? Support for v3 was removed in v0.5.2: the getChaiBuilderTailwindConfig helper and the tailwindCSS editor prop are gone, and shadow-sm, drop-shadow-sm, blur-sm, backdrop-blur-sm, a bare ring and outline-none now render with Tailwind v4's values. Check pages that use those classes after upgrading.

Storage and publishing

The theme is stored as a single JSON object on the site record - one theme per site, not per page.

Theme edits are saved explicitly. Changes in the panel, including a preset, a CSS import or an AI theme, preview on the canvas straight away but stay unsaved until you click Save. Discard rolls them back, and closing the panel with unsaved edits asks first.

A saved theme is a draft change. The builder and draft preview show it; the live site keeps the previously published theme until you publish it, from the panel header or the publish menu. The theme and design tokens publish separately, so publishing one leaves the other's live version as it is. See Preview and Publish.

With the revisions plugin registered, every theme save is kept in a theme history, next to a separate design token history, and you can restore an earlier version from the panel. See Revisions.

Editing the theme is permission gated. A role without theme edit access sees the panel replaced with a message rather than the controls.

Gotchas

Six-digit hex only. The color picker accepts #1155FF, not #15F, not hsl(...), not oklch(...). Shorthand hex from a brand guide needs expanding first.

The palette keys are fixed. You cannot add a brand-tertiary color through the Theme panel. If a project needs colors beyond the 19, put them in utility classes or a design token rather than expecting a new swatch.

A few color names exist in the class list but have no theme value by default. bg-surface, bg-success, bg-warning, bg-info and similar compile to an unresolved variable and render as nothing. The Theme panel cannot set them. success, warning, info, purple, orange and aqua (and their -foreground pairs) start working once a value is set, which an agent with the design system tools can do. surface has no theme key at all. Otherwise, stick to the keys the Theme panel shows.

Unsaved edits are lost on reload. A preset, an import or a color change is only kept once you click Save. After that, the theme history (with the revisions plugin) is the way back.

Radius is silently clamped. Anything outside 0-50, or non-numeric, becomes 0 with no message.

Dark values are easy to forget. Editing swatches with the dark toggle off changes only the light half. If your site ships dark mode, walk the palette a second time with the toggle on before publishing.

Verify

  1. In the builder, change primary and confirm buttons and links across the canvas update.
  2. Toggle dark mode in the canvas and check text stays readable on every surface.
  3. Publish, then on the live page view source and confirm <style id="theme-variables"> contains your values in both the :root and .dark blocks.
  4. If your site ships dark mode, add the dark class on <html> in devtools and confirm the published page flips cleanly.

© ChaiBuilder. All rights reserved.

ChaiBuilderMade withChaiBuilder