05-styling/02-theme-tokens.md

Theme tokens

Vroq apps should use theme tokens and CSS variables before introducing custom hard-coded colors, spacing, or radius values.

Theme tokens make apps visually consistent and make global theme changes possible without rewriting many files.

Preferred source of styling values

Prefer these sources in order:

1. existing Vroq component defaults 2. theme tokens from ui.css 3. small local overrides when clearly needed 4. hard-coded values only when justified

Common theme variables

Vroq styling is built around CSS variables such as:

--v-bg
--v-surface
--v-text
--v-muted
--v-border
--v-accent
--v-danger
--v-success
--v-space-*
--v-radius-*

Use these instead of inventing a separate design language per app.

Rules

prefer token-driven styling over hard-coded colors
prefer spacing tokens over arbitrary spacing values
prefer radius tokens over one-off border radius choices
use setTheme(...) and related helpers when changing the theme systemically

Why this matters

Using tokens makes it easier to:

keep apps consistent
switch presets or palettes
maintain accessibility and contrast defaults
avoid style drift across features

Final rule

Use the Vroq theme vocabulary first. Add custom visual values only when they solve a real problem that tokens do not already cover.