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:
- Shape the brand on the canvas
- Export
theme.css(ZIP or paste) into the app (for examplesrc/vira-theme.css) - Install
@fontsource-variable/*for the families in--font-family-*, and strip temporary Studio CDN@font-faceblocks once npm fonts are wired - Import theme → fonts → preflight
- Do not also install
@viraui/foundation
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:
- 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. - 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:
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';: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:
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';: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