Skip to content

Docs

Theming

DavinciUI components read your project's CSS variables, so re-theming means overriding tokens — never rewriting components. Change --primary once, and every installed component follows.

How theme values flow into components#

  • You define primitive values (oklch colors, radii) as CSS variables in your global stylesheet.
  • Tailwind CSS v4 exposes them as utilities — bg-background, text-foreground, border-border — via the theme mapping.
  • Installed components use only those utilities, so they inherit whatever values your project sets.

The practical consequence: theme at the token layer and components stay untouched. If you fork a component's classes instead, you take over its theme maintenance too.

CSS variables and semantic tokens#

Tokens live in your global stylesheet under :root, with dark overrides under .dark:

/* app/globals.css */
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --border: oklch(0.922 0 0);
  --radius: 0.625rem;
}
.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
}

Tokens are semantic — they describe a role (primary, muted, destructive) rather than a literal color — so light and dark modes can assign different values to the same role. Status tokens (--info, --success, --warning) and chart tokens (--chart-1…--chart-5) follow the same pattern. The full inventory is documented in Foundations → Colors.

Light and dark mode setup#

Dark mode is a class toggle. Define both value sets, then switch the dark class on the document element — the established way is next-themes:

import { ThemeProvider } from "next-themes"

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      {children}
    </ThemeProvider>
  )
}

Toggle with useTheme() from next-themes. Components need no theme props — they re-render from the variables automatically.

Info

Every token you override needs a .dark value too. A token with only a light value is the most common cause of unreadable dark-mode UI.

Safe customization examples#

Change a token globally — no component rewrite needed:

:root {
  --primary: oklch(0.55 0.22 264); /* your brand */
  --radius: 0.75rem;
}
.dark {
  --primary: oklch(0.75 0.18 264);
}

To add a genuinely new token (one that does not exist yet, e.g. --brand), declare the variable and map it into Tailwind so utilities like bg-brand work:

:root {
  --brand: oklch(0.55 0.22 264);
  --brand-foreground: oklch(0.98 0.01 264);
}
@theme inline {
  --color-brand: var(--brand);
  --color-brand-foreground: var(--brand-foreground);
}

Motion and contrast considerations#

  • Keep animations on transform and opacity where possible — they stay smooth regardless of theme.
  • Check every overridden token pair (--primary on --primary-foreground, muted text on page background) for readable contrast in both modes.
  • Never use muted text on a muted surface — it fails contrast at small sizes. See Typeset for the rule.
  • Honor prefers-reduced-motion: animated components already gate motion behind it (see Foundations → Motion). Custom animation wrappers should do the same.

How to avoid breaking accessibility#

  • Keep focus rings visible: do not restyle or remove --ring usage on interactive components.
  • Preserve the foreground/background pairing of every token you touch — status colors especially must stay distinguishable by more than hue alone where they convey meaning.
  • Test interactive components (dialogs, menus, tooltips) with keyboard only after re-theming; visual changes can hide focus order problems.