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
.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 (
--primaryon--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
--ringusage 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.

