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.
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
getChaiBuilderTailwindConfighelper and thetailwindCSSeditor prop are gone, andshadow-sm,drop-shadow-sm,blur-sm,backdrop-blur-sm, a bareringandoutline-nonenow 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
- In the builder, change
primaryand confirm buttons and links across the canvas update. - Toggle dark mode in the canvas and check text stays readable on every surface.
- Publish, then on the live page view source and confirm
<style id="theme-variables">contains your values in both the:rootand.darkblocks. - If your site ships dark mode, add the
darkclass on<html>in devtools and confirm the published page flips cleanly.
Related
- Design tokens - reusable class bundles built on these colors
- Design System for Agents - theme edits and design rules for MCP agents
- Custom fonts - registering families for the font dropdowns
- Blocks - where theme classes are applied
- Configuration - feature flags including dark mode and theme import
- API reference -
getChaiTailwindThemeand the other utilities

