What is a theme
How ViraUI theme CSS, tokens, and data-mode turn one stylesheet into your app’s look.
A theme is one stylesheet of --* design tokens. Swap the import and the same @viraui/react components pick up a different brand: a built-in preset from @viraui/foundation, or a custom sheet.
How that sheet lands in the app (import order, fonts, preflight) is covered in Setup. What the tokens mean by name is in Foundation.
Light and dark
Light and dark are not separate themes. They are two modes of the same theme.
Built-in presets pair both in one sheet with CSS light-dark(). For example, a background token holds both sides of the pair. Preflight maps data-mode on the document root to color-scheme, so flipping the attribute resolves every paired token without swapping stylesheets.
data-mode accepts light, dark, or inverted:
- Use
lightordarkon the root for the active scheme - Use
invertedon a nested island when that subtree should flip against its parent
Preflight ignores system and auto, so the app (or a theme library) must always write light or dark into the attribute. Brand is which theme stylesheet you imported. Mode is which side of that sheet’s light-dark() pairs resolves.
<html lang="en" data-mode="light">Custom themes
A custom theme only needs light-dark() when it must support both modes. If the brand is single-mode, assign a normal CSS value to each token and skip the pairing.
When both modes matter, put light-dark() on tokens that change with scheme. Mode-invariant tokens (space, radius, type scale, motion) can stay plain. Other pairing strategies work if every semantic token still resolves; do not treat a second dark stylesheet as the brand swap.
How to author and wire a custom sheet is on Custom themes.
Wire mode in your app
Point any theme manager at data-mode with theme names light / dark. Paste the prompt for your stack:
Add light and dark mode to this Next.js App Router app with next-themes.
The document root should use data-mode="light" or data-mode="dark" — not system or auto as the attribute value. System preference can drive the choice, but the DOM must settle on light or dark. Do not swap theme CSS when the mode changes; the same stylesheet should work for both. Add a simple light/dark/system toggle. Report what you changed.Last updated on