What are design tokens?
A design token is a named value for a visual decision — --v-accent-fill, --v-radius-md, --v-font-size-body — used everywhere instead of a hard-coded literal. The payoff is leverage: change the token once and every place that reads it updates together. In Vireya, hard-coded values are treated as bugs, which is what keeps a large product consistent.
A tier-based palette
Vireya colours are organised into four semantic tiers rather than a flat list of hues:
- background — the page surface everything sits on.
- secondary — muted surfaces, borders and subtle fills.
- primary — text and high-emphasis UI.
- accent — the brand colour, reserved for calls to action, highlights and focus rings.
Each tier expands into a set of steps — fill, foreground, hover, active, subdued, border — so components always have the right shade for the right state.
Generating a theme with createTheme()
You don't hand-author all those steps. createTheme() from @vireya/core takes a few HSL inputs and derives the full token set, including matching light and dark variants and the CSS variable maps that components consume.
Because color-scheme is derived from the background tone, native widgets — scrollbars, form controls — follow your theme automatically.
Customise components without writing CSS
Since every component in @vireya/ui reads tokens, a single token change cascades through the entire interface. Rebranding is a theme edit, not a component-by-component CSS rewrite — which is what makes Vireya scale from one theme to many across an organisation.
Switch themes at runtime
Themes are just CSS variable maps, so swapping them is instant: no rebuild, no reload. That's how light/dark toggles and multi-brand products work on top of the same components. See it live in the charts showcase, where every chart recolours from the active accent token.
Frequently asked questions
What are design tokens?
Design tokens are named values for visual decisions — colours, spacing, radii, typography, motion — used in place of hard-coded literals. Vireya exposes them as --v-* CSS variables, so changing a token updates every component that reads it.
How do I create a custom theme in Vireya?
Call createTheme() from @vireya/core with your tier inputs (background, secondary, primary, accent as HSL values). It generates the fill, foreground, hover, active, subdued and border steps for each tier plus light and dark variants, emitted as --v-* CSS variables.
Do I need to write CSS to restyle components?
No. Every component reads its colours, spacing and radii from tokens, so changing token values restyles the whole interface. You only write CSS for genuinely new layout, not to rebrand existing components.
Can I switch themes at runtime?
Yes. Because themes are CSS variable maps, switching is a matter of swapping the active variable set — no rebuild and no page reload. This is how light/dark and multi-brand setups work.