Theme system

The user-defined site theme — palette, styleGuide, fonts, modifiers — lives on ROOT.props (the Background node). The SDK reads it at runtime to generate CSS variables, scope them to the page container, and pair with the FOUC pipeline so the first paint matches the design system.

Where theme data lives

Field	Notes
`ROOT.props.pallet`	Array of `{ name, color }`. Drives palette CSS vars.
`ROOT.props.styleGuide`	Style tokens — radius, depth, font families, link/input colors. Built-in keys are catalogued in `STYLE_TOKEN_REGISTRY`; unknown keys are user-created (custom) tokens.
`ROOT.props.theme.styleGuideMeta`	Sparse sidecar `Record<string, { appliesTo?, custom? }>`. Marks user-created keys as `custom: true` so the picker shows Delete; optional `appliesTo` overrides the value-heuristic category for relevance filtering.
`ROOT.props.theme`	The effective theme (palette + styleGuide merged). Read via `resolveTheme()`.
`ROOT.props.theme.typography`	Array of typography presets — see text-styles for the picker / editor + storage shape.
`ROOT.props.modifiers`	Site-wide modifier classes applied at root.

End-user CRUD — every token (palette + typography + built-in styleGuide + custom) is created / edited / deleted via the unified VarPicker. The deprecated per-row dropdowns in StylesTab were removed; StylesTab now hosts only the global Density slider, the "Manage Tokens →" entry button, Breakpoints, and Editor preferences.

Key files

packages/sdk/src/utils/design/resolveTheme.ts — single read entry point for theme data
packages/sdk/src/utils/design/designSystemVars.ts — generateDesignSystemCSSVariables, injectDesignSystemVars, toCSSVarName, toPaletteCSSVarName, toStyleCSSVarName
packages/sdk/src/utils/design/palette.ts — palette helpers (paletteToCSSVar)
packages/sdk/src/utils/design/colorSystem.ts, contentColor.ts — auto content-color derivation
packages/sdk/src/utils/design/PaletteContext.tsx, RuntimeVarsContext.tsx — React contexts
packages/sdk/src/core/theme.ts — injectTheme for SDK consumers (init-time CSS var injection)
packages/sdk/src/theme.css — canonical default theme, exported as @pagehub/sdk/theme.css
packages/sdk/src/chrome/toolbar/inputs/universal-input/styleTokenRegistry.ts — STYLE_TOKEN_REGISTRY: built-in styleGuide key catalogue (label / category / type / quickPicks). Single source of truth for the picker UI.
packages/sdk/src/chrome/toolbar/inputs/universal-input/hooks/useDesignVars.ts — read entry point that emits the unified DesignVar[] (palette + typography + every styleGuide key + custom) consumed by VarPicker.
packages/sdk/src/chrome/toolbar/inputs/universal-input/hooks/useTokenUsage.ts — counts var(--name) references across the tree; powers the rename / delete in-use guard.
packages/sdk/src/chrome/toolbar/inputs/universal-input/VarPicker/ — the FloatingPanel UI (index.tsx orchestrator + VarList + VarEditor).

Var naming

toCSSVarName() converts camelCase to hyphenated CSS var names:

pallet[].name: "BrandAccent" → --brand-accent
styleGuide.radiusBox → --radius-box

Heading + Body fonts live in theme.typography[] as Heading and Body tokens. The orchestrator (generateDesignSystemCSSVariables) derives --heading-font-family, --heading-font-weight, --body-font-family, --body-font-weight from those tokens. Tailwind tokens font-heading / font-body reference the family vars directly. Any other *FontFamily key in styleGuide (e.g. accentFontFamily) auto-generates a CSS var and is recognized by extractGoogleFontsUrl for weight pairing.

Scoping

CSS vars are scoped to:

Surface	Selector
Editor canvas	`#viewport`
Viewer (`/view/`, custom domains, static)	`#ph-site-preview`

Both surfaces also have fallback CSS vars in styles/editor.css matching the SDK default theme — these are safety nets so the canvas never flashes if SSR vars are absent. Values must match packages/sdk/src/theme.css.

Pipeline (SSR / FOUC)

generatePageFOUCData() in utils/generatePageFOUCData.ts extracts palette/styleGuide from CraftJS JSON, generates CSS vars, compiles the Tailwind classes used on the page, and returns Google Fonts URLs. <FOUCPreventionHead> renders the result into <Head>. Full pipeline in .claude/rules/css-architecture.md.

Init-time injection (SDK consumers)

External SDK consumers call init({ theme: {...} }). The injectTheme helper writes a <style id="pagehub-sdk-theme"> with CSS vars (--primary, --secondary, --accent, plus cssVariables) into the host container. This is for non-PageHub consumers — PageHub itself uses the FOUC pipeline.

Outline CTAs gotcha

If Primary and Base Content are both very dark neutrals (similar OKLCH lightness), btn btn-outline plus text-base-content reads as dark-on-dark — DaisyUI drives outline button foreground/border from --btn-color (often resolving to primary). Fix in theme data: separate lightness so primary is darker for fills and base-content is lighter for body. See .claude/rules/templates.md (Palette vs outline CTAs).

text-styles — typography preset picker / editor (Framer-style chip + FloatingPanel)
rendering, animations
.claude/rules/css-architecture.md — single source of truth
packages/daisyui-spatial/src/index.css — spatial tokens layered on top