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 Create Studio

Pick a preset, tune colors and type, and watch the preview re-theme in real time — then copy the CSS overrides.

Open Create Studio

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

Design tool handoff

The token source also compiles to design-tool formats — generated and drift-checked alongside tokens.json, and shipped with @cooud-ui/tokens.

W3C DTCG tokens

tokens.dtcg.json

Every theme and mode in the Design Tokens Community Group format, grouped cooud.{theme}.{mode}.{token}, for pipelines like Style Dictionary or Tokens Studio. Colors stay as the source oklch() strings; shadows are structured shadow objects; font stacks are family arrays.

@cooud-ui/tokens/tokens.dtcg.json

Figma Variables

figma-variables.json

One Cooud UI collection with ten {theme}-{mode} modes for Figma Variables plugins or the REST API. Colors are converted to sRGB hex (gamut-clamped, self-checked at build time); radius is a px FLOAT; fonts and shadows are STRING values.

@cooud-ui/tokens/figma-variables.json

Gradients are intentionally not in either file — the bg-gradient-* utilities derive from primary/accent at runtime, so they re-theme on their own.