The Open Standard for Generative UI
ThemeProvider — Agent Guide
File Map
| File | Purpose |
|---|---|
ThemeProvider.tsx |
React component, ThemeContext, InternalContext (nesting detection), useTheme hook. Injects --openui-* vars into <head> via useInsertionEffect. |
types.ts |
TypeScript interfaces: Theme, ColorTheme, LayoutTheme, TypographyTheme, EffectTheme, ChartColorPalette. |
defaultTheme.ts |
Builds defaultLightTheme / defaultDarkTheme (frozen) from the swatch system. Contains createColorTheme() and all layout/typography/shadow defaults. |
swatches.ts |
18 oklch color families x 14 shades. Exports swatch(), withAlpha(), swatchToken(), swatchTokens. |
utils.ts |
Exports camelToKebab, themeToCssVars, createTheme (dev-mode typo detection with Levenshtein distance suggestions), and KNOWN_THEME_KEYS (shared validator allow-list). |
index.ts |
Barrel re-exports from all the above files. |
Architecture
ThemeProvider mounts
│
├── Resolves active theme: { ...defaults[mode], ...userLightTheme } or { ...defaults[mode], ...userDarkTheme }
│
├── themeToCssVars(theme) → "--openui-background: oklch(...);\n--openui-foreground: ..."
│
├── useInsertionEffect → creates <style data-openui-theme={id}> in <head>
│ └── Targets body (root) or .openui-theme-{id} (nested, auto-scoped)
│ └── Also targets .openui-theme-portal-{id} for portaled components
│
└── Provides ThemeContext + InternalContext to children
Key internals:
cssSafeId(useId())— strips CSS-unsafe characters (colons from React 18's:r0:format) for use in class names and selectors.InternalContextwith aSymbolsentinel detects whether this provider is nested inside another. Nested providers auto-scope via a<div style="display: contents">wrapper instead of targetingbody.cssUtils.scssis auto-generated at build time bysrc/scripts/generate-css-utils.tsfromdefaultLightTheme, including fallback values.
Key Patterns
Adding a New Token
Only 2 files need editing — the runtime walker (themeToCssVars) and the build script (generate-css-utils.ts) pick up new keys automatically:
types.ts— add the optionalstringfield to the appropriate interface (ColorTheme,LayoutTheme, etc.).defaultTheme.ts— set the default value insidecreateColorTheme()(orlayoutTheme,typographyTheme, etc.).
Run pnpm build (or pnpm generate:css-utils) to regenerate cssUtils.scss with the new token and its fallback.
Exception — chart palette keys (string[], no defaults): the validator allow-list is Object.keys(defaultLightTheme) + CHART_PALETTE_KEYS. The single source is the CHART_PALETTE_KEYS as const array in types.ts — the ChartColorPalette type is derived from it, so a new palette is added in exactly one place and type/runtime drift is impossible by construction. Do not give palettes defaults in defaultTheme.ts: a default would take precedence over the per-chart theme prop fallback in useChartPalette.
Naming Convention
TS field: camelCase e.g. interactiveAccentDefault
CSS variable: --openui-{kebab} e.g. --openui-interactive-accent-default
SCSS variable: ${kebab} e.g. $interactive-accent-default
The camelToKebab() utility in utils.ts handles the conversion, including digits (space3xs → space-3xs) and consecutive uppercase letters.
Color Format
All color values must use oklch() with explicit alpha: oklch(L C H / alpha).
Props
lightTheme/darkTheme— the current API for theme overrides.theme— deprecated alias forlightTheme. Emits a dev-mode warning.cssSelector— defaults to"body". When set explicitly on a nested provider, bypasses auto-scoping.
Changing the Brand Color
Edit LIGHT_SWATCHES.brandSwatch and/or DARK_SWATCHES.brandSwatch in defaultTheme.ts. Choose from BrandSwatchName (any swatch family except green, yellow, red).
Adding a New Swatch Family
- Add the shade map to
BASE_SWATCHESinswatches.ts(14 shades, 25-1000, oklch values). - Add the family name to the
SwatchNameunion (it's inferred fromBASE_SWATCHESkeys). - If it should be usable as a brand color, the
BrandSwatchNameexclusion list may need updating.
Do NOT Change
- Swatch oklch values without design-system coordination — they are copied from
design-system/color-swatches.css. - CSS variable prefix
--openui-— it is hardcoded inThemeProvider.tsx,utils.ts,generate-css-utils.ts,cssUtils.scss, and the Tailwind plugin. - Component SCSS: never hardcode colors in component
.scssfiles. Always referencecssUtilsvariables. - Internal helpers (
parseOklch,clamp01,relativeLuminanceFromOklch,contrastRatio,pickAccentTextFromNeutral) — these implement WCAG contrast logic and should only change if the accessibility algorithm needs updating. Object.freezeon default themes — prevents accidental mutation of the shared singletons.cssSafeIdinThemeProvider.tsx— required because React 18'suseId()returns colon-containing IDs (:r0:) that are invalid in CSS selectors.