Theming

Theme the whole system through tokens

Cooud UI treats theme as a design-system object: color ramps, brand accents, chart colors, typography, and radius move together.

Build a preset

Prefer to play? Try the live Theme Builder

Drag the sliders, pick colors, and watch the whole page re-theme in real time — then copy the CSS overrides.

Open Theme Builder

Theme layers

Semantic tokens

Components consume surface, foreground, border, ring, primary, and chart tokens.

Preset bundles

A preset combines mode, base color, brand color, chart palette, fonts, and radius.

Runtime overrides

Apps can override tokens at runtime without recompiling Tailwind or changing component code.

Provider

Import tokens once, then wrap the app in the provider at the framework root.

tsx

import "@cooud-ui/tokens/styles.css";
import { CooudUIProvider } from "@cooud-ui/theme";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <CooudUIProvider asRoot defaultThemeName="aurora" defaultModeName="dark">
          {children}
        </CooudUIProvider>
      </body>
    </html>
  );
}

Avoiding a flash of the wrong theme

The provider restores a saved theme from localStorage after first paint, so a returning visitor can briefly see the default theme. Render CooudThemeScript in the document head to apply the saved theme before paint.

tsx

import { CooudThemeScript, CooudUIProvider } from "@cooud-ui/theme";

export default function RootLayout({ children }) {
  return (
    // suppressHydrationWarning: the script mutates <html> before hydration.
    <html lang="en" suppressHydrationWarning>
      <head>
        <CooudThemeScript
          storageKey="cooud-ui-theme"
          defaultThemeName="aurora"
          defaultModeName="dark"
        />
      </head>
      <body>
        <CooudUIProvider asRoot storageKey="cooud-ui-theme">
          {children}
        </CooudUIProvider>
      </body>
    </html>
  );
}

Pass the same storageKey to both

The script and CooudUIProvider must share the same storageKey. Add suppressHydrationWarning to <html> because the script changes its attributes before hydration. Under a strict CSP, forward a nonce to CooudThemeScript.

Runtime overrides

Use runtime overrides for brand portals, per-tenant styling, previews, or Create-generated presets.

tsx

import { useTheme } from "@cooud-ui/theme";

export function BrandThemeControls() {
  const { setOverrides } = useTheme();

  return (
    <button
      type="button"
      onClick={() =>
        setOverrides({
          radius: "16px",
          primary: "oklch(0.685 0.169 237.3)",
          chart1: "oklch(0.685 0.169 237.3)",
          fontDisplay: "Inter, sans-serif"
        })
      }
    >
      Apply brand theme
    </button>
  );
}

The Create studio exports the same values as preset JSON and CSS variables, so teams can store a design system and reapply it later.

Preset catalog

These are the cohesive looks available in Create today.

Nova

dark / 14px

A modern dark workspace — clean neutral surfaces lit by a luminous sky-blue brand.

neutral sky brand

Aurora

dark / 16px

Premium and atmospheric — cool slate depths with a vivid violet glow.

slate violet vivid

Minimal

light / 8px

Light, quiet, and precise — neutral paper surfaces with a calm blue accent.

neutral blue neutral

Brutalist

light / 0px

Raw and high-contrast — hard zinc edges, monospace type, and a bold orange punch.

zinc orange vivid

Editorial

light / 12px

Warm and literary — stone paper, serif headlines, and a refined rose highlight.

stone rose warm

Terminal

dark / 4px

A focused command-line aesthetic — deep neutral black with phosphor-emerald accents.

neutral emerald neutral