Theming

Custom themes

One compatible theme CSS sheet — Studio export, agent-built, or base plus overrides.

A custom brand uses the same contract as a built-in preset: one theme CSS file that keeps the semantic variable names and swaps in your values. You do not need @viraui/foundation.

Load your sheet, then the fonts named in --font-family-*, then preflight. Keep light and dark in that same file with light-dark() on scheme-sensitive tokens. Light and dark covers the pairing pattern and how data-mode resolves it.

App Studio (ViraUI Pro)

Hand-editing a full theme means forking a large CSS dump, keeping every semantic name stable, balancing light/dark pairs, and checking that components still look right.

App Studio in ViraUI Pro is the preferred path for a new brand: tune colors, type, space, and effects on a live ViraUI canvas, share the theme with the team, export CSS that is already compatible, then drop it into the app.

Typical Studio path:

  1. Shape the brand on the canvas
  2. Export theme.css (ZIP or paste) into the app (for example src/vira-theme.css)
  3. Install @fontsource-variable/* for the families in --font-family-*, and strip temporary Studio CDN @font-face blocks once npm fonts are wired
  4. Import theme → fonts → preflight
  5. Do not also install @viraui/foundation
App Studio theme canvas in ViraUI Pro

Ask your agent

When Studio is not an option, the agent can wire a ViraUI-compatible brand the same way as any other custom theme (theme → fonts → preflight at the app root). Light and dark should both work from light-dark() pairs on scheme-sensitive tokens.

Two alternatives — pick one:

  1. One complete sheet — copy a built-in preset (for example vira.css) into the app, change the token values in that file, and import it as the theme. Same shape if the agent builds a fresh full sheet from scratch. No second override file.
  2. Base + overrides — keep importing the preset (or any full theme), then add a small CSS file that only redefines the keys you change.

One complete sheet

Import the forked (or agent-built) file as the theme — same order as any other brand:

Full theme sheet
import './vira-theme.css'; // forked preset or fresh full sheet
import '@fontsource-variable/geist/wght.css'; // match families in your theme
import '@viraui/react/preflight.css';
vira-theme.css — pair scheme-sensitive tokens
:root {
  --global-background: light-dark(oklch(98% 0.01 250), oklch(18% 0.02 250));
  --global-foreground: light-dark(oklch(22% 0.02 250), oklch(96% 0.01 250));
  --global-primary: light-dark(oklch(55% 0.14 250), oklch(72% 0.12 250));
  /* space, radius, type scale… can stay unpaired */
}

Base + overrides

Only after a complete theme is already loaded, layer a few semantic overrides:

Base theme + partial overrides
import '@viraui/foundation/vira.css'; // or your full custom sheet
import './brand-overrides.css'; // only the tokens you change
import '@fontsource-variable/geist/wght.css';
import '@viraui/react/preflight.css';
brand-overrides.css — never alone
:root {
  /* Prefer light-dark() so data-mode flips keep working */
  --global-primary: light-dark(oklch(55% 0.14 250), oklch(72% 0.12 250));
  --space-m: 0.875rem;
}

Scoped wrappers work the same way when only a subtree should rebrand. Full brand swaps replace the complete theme CSS import, not data-mode.

Load a complete theme

Components expect every semantic token from the theme contract, not a handful of overrides alone. Ship a full theme CSS (Studio export, forked preset, or agent-built sheet), or import a base theme first and only then layer partial :root overrides. A partial sheet with no base theme leaves missing variables and broken UI.

Last updated on

On this page