The Open Standard for Generative UI
ThemeProvider
Wraps your application and injects --openui-* CSS custom properties into <head> via React 18's useInsertionEffect. These variables are consumed by cssUtils.scss SCSS variables and the typography() mixin, making every OpenUI component theme-aware with zero extra configuration.
Theme object ──► ThemeProvider ──► useInsertionEffect ──► <style> in <head>
│
cssUtils.scss ($background, $text-neutral-primary, …)
│
Component SCSS
Components render correctly without a ThemeProvider because cssUtils.scss is auto-generated at build time with fallback values from defaultLightTheme. The provider overrides those fallbacks when mounted.
Quick Start
import { ThemeProvider } from "@openuidev/react-ui";
function App() {
return (
<ThemeProvider mode="light">
<YourApp />
</ThemeProvider>
);
}
Switch to dark mode by changing the mode prop:
<ThemeProvider mode="dark">
<YourApp />
</ThemeProvider>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
mode |
"light" | "dark" |
"light" |
Active color scheme |
lightTheme |
Theme |
{} |
Partial overrides merged onto the built-in light defaults. Recommended over the deprecated theme prop. |
darkTheme |
Theme |
— | Partial overrides for dark mode. When omitted, lightTheme overrides are applied to both modes. |
theme |
Theme |
— | Deprecated. Mapped to lightTheme internally. If both are provided, lightTheme wins. |
cssSelector |
string |
"body" |
CSS selector where --openui-* variables are injected. Automatically scoped when nested (see Nested Themes). |
children |
React.ReactNode |
— | Application content |
Theme Customization
Use createTheme() to build a type-safe partial theme. In development it validates keys and offers "did you mean?" suggestions for typos via Levenshtein distance. In production the validation is stripped by bundlers.
import { ThemeProvider, createTheme } from "@openuidev/react-ui";
<ThemeProvider
mode="light"
lightTheme={createTheme({ interactiveAccentDefault: "oklch(0.6 0.2 260)" })}
>
<YourApp />
</ThemeProvider>;
When you need different overrides for light and dark modes, pass both lightTheme and darkTheme:
<ThemeProvider
mode={prefersDark ? "dark" : "light"}
lightTheme={createTheme({ interactiveAccentDefault: "oklch(0.6 0.2 260)" })}
darkTheme={createTheme({ interactiveAccentDefault: "oklch(0.7 0.15 260)" })}
>
<YourApp />
</ThemeProvider>
When darkTheme is omitted, lightTheme overrides are applied to both modes so a single set of brand customizations "just works".
Nested Themes
ThemeProvider supports nesting out of the box. When a ThemeProvider detects a parent provider above it:
- It wraps its children in a
<div style="display: contents">with a generated scoped class. - It injects CSS variables scoped to that class instead of targeting
body. - The parent's theme is not inherited — each nested provider merges its own overrides onto the built-in defaults for the active mode.
<ThemeProvider mode="light">
<MainApp />
<ThemeProvider mode="dark">
{/* Dark sidebar — CSS vars scoped, won't affect MainApp */}
<Sidebar />
</ThemeProvider>
</ThemeProvider>
The display: contents wrapper is invisible to layout (flex/grid children pass through). Portal components (Select, FloatingUIPortal, GalleryModal, etc.) automatically pick up the scoped theme via portalThemeClassName.
To bypass auto-scoping and target a specific selector, pass cssSelector explicitly:
<ThemeProvider mode="dark" cssSelector=".sidebar">
<Sidebar />
</ThemeProvider>
useTheme Hook
import { useTheme } from "@openuidev/react-ui";
function MyComponent() {
const { theme, mode, portalThemeClassName } = useTheme();
return <div style={{ color: theme.textNeutralPrimary }}>Current mode: {mode}</div>;
}
Return value:
| Field | Type | Description |
|---|---|---|
theme |
Theme |
Fully resolved theme object |
mode |
ThemeMode |
"light" or "dark" |
portalThemeClassName |
string |
CSS class name to add to portal containers so they inherit the theme variables |
Falls back to defaultLightTheme when no provider is present — components and hooks always receive a valid theme.
Portal Theming
The portalThemeClassName is for floating elements (tooltips, dropdowns, modals) rendered via React portals outside the ThemeProvider's DOM subtree. The ThemeProvider's injected <style> already targets .openui-theme-portal-{id}, so add the class to your portal wrapper:
const { portalThemeClassName } = useTheme();
return createPortal(
<div className={portalThemeClassName}>
<Tooltip />
</div>,
document.body,
);
CSS Variable Consumption
cssUtils.scss is auto-generated at build time by generate-css-utils.ts. Each SCSS variable includes a fallback value from defaultLightTheme:
// Auto-generated — do not edit manually
$background: var(--openui-background, oklch(0.97 0 89.876 / 1));
$space-m: var(--openui-space-m, 12px);
Use it in component SCSS:
@use "../../cssUtils" as cssUtils;
.my-card {
background-color: cssUtils.$foreground;
color: cssUtils.$text-neutral-primary;
border: 1px solid cssUtils.$border-default;
border-radius: cssUtils.$radius-m;
padding: cssUtils.$space-m;
box-shadow: cssUtils.$shadow-m;
@include cssUtils.typography(body, default);
}
The typography() mixin sets both font (shorthand) and letter-spacing from the compound typography tokens.
Theme Token Reference
Every token follows the naming convention:
- TypeScript key:
camelCase(e.g.interactiveAccentDefault) - CSS variable:
--openui-{kebab-case}(e.g.--openui-interactive-accent-default) - SCSS variable:
${kebab-case}(e.g.$interactive-accent-default)
Surface Colors
| TS Key | CSS Variable | Description |
|---|---|---|
background |
--openui-background |
Main page/app background |
foreground |
--openui-foreground |
Card/container background |
popoverBackground |
--openui-popover-background |
Popover/dropdown background |
sunkLight |
--openui-sunk-light |
Lightly recessed surface |
sunk |
--openui-sunk |
Recessed surface (inputs) |
sunkDeep |
--openui-sunk-deep |
Deeply recessed surface |
elevatedLight |
--openui-elevated-light |
Lightly elevated surface |
elevated |
--openui-elevated |
Elevated surface |
elevatedStrong |
--openui-elevated-strong |
Strongly elevated surface |
elevatedIntense |
--openui-elevated-intense |
Intensely elevated surface |
overlay |
--openui-overlay |
Modal/overlay backdrop |
highlightSubtle |
--openui-highlight-subtle |
Subtle hover highlight |
highlight |
--openui-highlight |
Default highlight |
highlightStrong |
--openui-highlight-strong |
Strong highlight |
highlightIntense |
--openui-highlight-intense |
Intense highlight/selection |
invertedBackground |
--openui-inverted-background |
Inverted surface |
infoBackground |
--openui-info-background |
Info status background |
successBackground |
--openui-success-background |
Success status background |
alertBackground |
--openui-alert-background |
Alert/warning background |
dangerBackground |
--openui-danger-background |
Error/danger background |
purpleBackground |
--openui-purple-background |
Purple accent background |
pinkBackground |
--openui-pink-background |
Pink accent background |
Text Colors
| TS Key | CSS Variable | Description |
|---|---|---|
textNeutralPrimary |
--openui-text-neutral-primary |
Primary body text |
textNeutralSecondary |
--openui-text-neutral-secondary |
Secondary/muted text |
textNeutralTertiary |
--openui-text-neutral-tertiary |
Disabled/hint text |
textNeutralLink |
--openui-text-neutral-link |
Hyperlink text |
textBrand |
--openui-text-brand |
Brand-colored text |
textWhite |
--openui-text-white |
Forced white text |
textBlack |
--openui-text-black |
Forced black text |
textAccentPrimary |
--openui-text-accent-primary |
Text on accent backgrounds |
textAccentSecondary |
--openui-text-accent-secondary |
Secondary text on accent backgrounds |
textAccentTertiary |
--openui-text-accent-tertiary |
Disabled text on accent backgrounds |
textSuccessPrimary |
--openui-text-success-primary |
Success message text |
textSuccessInverted |
--openui-text-success-inverted |
Text on success backgrounds |
textAlertPrimary |
--openui-text-alert-primary |
Alert/warning text |
textAlertInverted |
--openui-text-alert-inverted |
Text on alert backgrounds |
textDangerPrimary |
--openui-text-danger-primary |
Error text |
textDangerSecondary |
--openui-text-danger-secondary |
Secondary error text |
textDangerTertiary |
--openui-text-danger-tertiary |
Disabled error text |
textDangerInvertedPrimary |
--openui-text-danger-inverted-primary |
Primary text on danger backgrounds |
textDangerInvertedSecondary |
--openui-text-danger-inverted-secondary |
Secondary text on danger backgrounds |
textDangerInvertedTertiary |
--openui-text-danger-inverted-tertiary |
Disabled text on danger backgrounds |
textInfoPrimary |
--openui-text-info-primary |
Info text |
textInfoInverted |
--openui-text-info-inverted |
Text on info backgrounds |
textPinkPrimary |
--openui-text-pink-primary |
Pink accent text |
textPinkInverted |
--openui-text-pink-inverted |
Text on pink backgrounds |
textPurplePrimary |
--openui-text-purple-primary |
Purple accent text |
textPurpleInverted |
--openui-text-purple-inverted |
Text on purple backgrounds |
Interactive Colors
| TS Key | CSS Variable | Description |
|---|---|---|
interactiveAccentDefault |
--openui-interactive-accent-default |
Primary button default |
interactiveAccentHover |
--openui-interactive-accent-hover |
Primary button hover |
interactiveAccentPressed |
--openui-interactive-accent-pressed |
Primary button pressed |
interactiveAccentDisabled |
--openui-interactive-accent-disabled |
Primary button disabled |
interactiveDestructiveDefault |
--openui-interactive-destructive-default |
Destructive ghost default |
interactiveDestructiveHover |
--openui-interactive-destructive-hover |
Destructive ghost hover |
interactiveDestructivePressed |
--openui-interactive-destructive-pressed |
Destructive ghost pressed |
interactiveDestructiveDisabled |
--openui-interactive-destructive-disabled |
Destructive ghost disabled |
interactiveDestructiveAccentDefault |
--openui-interactive-destructive-accent-default |
Filled destructive default |
interactiveDestructiveAccentHover |
--openui-interactive-destructive-accent-hover |
Filled destructive hover |
interactiveDestructiveAccentPressed |
--openui-interactive-destructive-accent-pressed |
Filled destructive pressed |
interactiveDestructiveAccentDisabled |
--openui-interactive-destructive-accent-disabled |
Filled destructive disabled |
Border Colors
| TS Key | CSS Variable | Description |
|---|---|---|
borderDefault |
--openui-border-default |
Default border |
borderInteractive |
--openui-border-interactive |
Interactive element border |
borderInteractiveEmphasis |
--openui-border-interactive-emphasis |
Emphasized interactive border |
borderInteractiveSelected |
--openui-border-interactive-selected |
Selected interactive border |
borderAccent |
--openui-border-accent |
Accent/brand border |
borderAccentEmphasis |
--openui-border-accent-emphasis |
Emphasized accent border |
borderInfo |
--openui-border-info |
Info status border |
borderInfoEmphasis |
--openui-border-info-emphasis |
Emphasized info border |
borderAlert |
--openui-border-alert |
Alert border |
borderAlertEmphasis |
--openui-border-alert-emphasis |
Emphasized alert border |
borderSuccess |
--openui-border-success |
Success border |
borderSuccessEmphasis |
--openui-border-success-emphasis |
Emphasized success border |
borderDanger |
--openui-border-danger |
Danger border |
borderDangerEmphasis |
--openui-border-danger-emphasis |
Emphasized danger border |
Chat Colors
| TS Key | CSS Variable | Description |
|---|---|---|
chatUserResponseBg |
--openui-chat-user-response-bg |
User message background |
chatUserResponseText |
--openui-chat-user-response-text |
User message text |
Spacing
| TS Key | CSS Variable | Default |
|---|---|---|
space000 |
--openui-space-000 |
0 |
space3xs |
--openui-space-3xs |
2px |
space2xs |
--openui-space-2xs |
4px |
spaceXs |
--openui-space-xs |
6px |
spaceS |
--openui-space-s |
8px |
spaceSM |
--openui-space-s-m |
10px |
spaceM |
--openui-space-m |
12px |
spaceML |
--openui-space-m-l |
16px |
spaceL |
--openui-space-l |
18px |
spaceXl |
--openui-space-xl |
24px |
space2xl |
--openui-space-2xl |
36px |
space3xl |
--openui-space-3xl |
48px |
Border Radius
| TS Key | CSS Variable | Default |
|---|---|---|
radiusNone |
--openui-radius-none |
0 |
radius3xs |
--openui-radius-3xs |
1px |
radius2xs |
--openui-radius-2xs |
2px |
radiusXs |
--openui-radius-xs |
4px |
radiusS |
--openui-radius-s |
6px |
radiusM |
--openui-radius-m |
8px |
radiusL |
--openui-radius-l |
10px |
radiusXl |
--openui-radius-xl |
12px |
radius2xl |
--openui-radius-2xl |
14px |
radius3xl |
--openui-radius-3xl |
16px |
radius4xl |
--openui-radius-4xl |
20px |
radius5xl |
--openui-radius-5xl |
24px |
radius6xl |
--openui-radius-6xl |
28px |
radius7xl |
--openui-radius-7xl |
32px |
radius8xl |
--openui-radius-8xl |
40px |
radius9xl |
--openui-radius-9xl |
48px |
radiusFull |
--openui-radius-full |
9999px |
Shadows
| TS Key | CSS Variable | Usage |
|---|---|---|
shadow0 |
--openui-shadow-0 |
No shadow |
shadowS |
--openui-shadow-s |
Subtle (buttons) |
shadowM |
--openui-shadow-m |
Medium (cards) |
shadowL |
--openui-shadow-l |
Large (dropdowns) |
shadowXl |
--openui-shadow-xl |
Extra large (modals) |
shadow2xl |
--openui-shadow-2xl |
High elevation |
shadow3xl |
--openui-shadow-3xl |
Maximum elevation |
Swatch System
swatches.ts defines 20 color families (neutral, slate, gray, zinc, stone, blue, sky, cyan, teal, emerald, lime, amber, orange, green, yellow, red, purple, violet, fuchsia, pink), each with 14 shades (25-1000) in oklch format.
defaultTheme.ts uses createColorTheme() to derive all semantic tokens from two swatch selectors:
neutralSwatch-- used for backgrounds, text, and bordersbrandSwatch-- used for accent/interactive colors
Accent text colors are automatically picked for WCAG AA Large contrast via pickAccentTextFromNeutral(), which compares shade-25 and shade-1000 of the neutral swatch against the brand solid color and selects the one that passes the 3:1 contrast ratio threshold.