Tokens and theming
Theme the zgui component library with ThemeProvider, light and dark schemes, themes written as CSS, presets and run-time switching, plus a reference of all 141 design tokens.
zgui-ui-tokens holds the design tokens the component library is styled with, and
ThemeProvider, which installs them in a window. Every token is a CSS custom property starting with
--zui-. Component sheets read tokens with var() and never name a concrete colour, so you
re-theme the whole library by changing token values.
[dependencies]
zgui-ui-tokens = "0.1"use zgui_ui_tokens::prelude::*;The crate depends only on zgui, so you can also use it without zgui-ui: the tokens plus your
own css! sheets make a complete design system.
Apply a theme
Wrap your interface in a ThemeProvider. It installs the tokens as a style sheet and renders a
single display: contents element.
view! {
ThemeProvider(scheme = ColorScheme::System) {
App()
}
}| Prop | Type | Default |
|---|---|---|
light | Signal<Theme, LocalStorage>, into | Theme::light() |
dark | Signal<Theme, LocalStorage>, into | Theme::dark() |
scheme | Signal<ColorScheme, LocalStorage>, into | ColorScheme::System |
children | Children | required |
light and dark are two independent slots: the theme used when the scheme is light, and the one
used when it is dark. Pass a signal to make a slot switchable. scheme decides which slots are
written to the sheet:
ColorScheme | Sheet contents |
|---|---|
Light | the light theme only |
Dark | the dark theme only |
System | the light theme, then the dark theme inside @media (prefers-color-scheme: dark) |
With System, nothing is resolved in Rust. The media query follows the window's light or dark
preference: the desktop's, or the one set with app().with_theme(…) or WindowHandle::set_theme(…)
(see Theming).
zgui-ui never installs tokens itself. Without a provider, or custom properties you declare
yourself, every component's var(--zui-…) resolves to nothing and the components render unstyled.
Where the tokens are declared
| Provider | Declares on | Sheet name |
|---|---|---|
| the first in a window | :root | zgui-ui-theme (THEME_SHEET) |
| a nested one, number N | .zui-theme-N | zgui-ui-theme-N |
- The outermost provider declares on
:root, so menus, dialogs and toasts are themed even though they are portalled onto overlay bands outside the provider's subtree. - A nested provider themes only its own subtree. Portalled surfaces opened from inside it still use the root tokens.
- The tokens are a style sheet at the author origin, not inline styles, so your own rules can override them.
- Unmounting a provider removes its sheet.
Write a theme
A theme is a set of CSS values, so the easiest way to write one is in CSS. Theme::with_css applies
custom property declarations on top of a base theme:
let mocha = Theme::dark().with_css(
"--zui-color-background: #1e1e2e;
--zui-color-primary: #cba6f7;
--zui-radius-base: 8px;
--zui-space-base: 3.5px;
--zui-shadow-sm: none;
--zui-type-family-sans: 'Readex Pro';",
);
view! {
ThemeProvider(dark = mocha, scheme = ColorScheme::Dark) {
App()
}
}- Unknown property names are ignored, as in a style sheet. Comments are skipped, a wrapping
:root { … }is accepted, and the trailing semicolon is optional. apply_css(&mut self, text)does the same in place and returns how many declarations matched a token.set(property, value)sets one token and reports whether it exists.- The set of tokens is fixed: you cannot add a ninth group. Declare tokens of your own as ordinary custom properties in your own sheet (see Add your own tokens).
Declarations::pushrefuses a value containing;,{,}or/*(a debug assertion; in release builds the token is dropped), so a value supplied at run time cannot break the sheet.
Start from a preset
Preset lists the themes the library ships, each built with with_css:
| Preset | Character |
|---|---|
Base (default) | the default tokens: neutral, near-monochrome, soft corners |
Ocean | blue, wider corners, slower and softer motion |
Ember | warm orange, tight corners, the fastest motion |
Terminal | green, square corners, no motion (all durations zero) |
Midnight | violet, very round corners, long and gentle motion |
ThemeProvider(light = Preset::Ocean.light(), dark = Preset::Midnight.dark()) {
App()
}To build a theme picker, use Preset::ALL, name(), label() and from_name().
Switch themes at run time
| To change | Do this | What changes |
|---|---|---|
| the scheme | write the scheme signal | which slot is written to the sheet |
| a whole slot | write the light or dark signal | that slot's theme |
| some tokens | use_theme()?.themes().patch(…) | only the token groups that differ |
| one context | a rule in your own sheet | your rule, if it wins the cascade |
Each of the first three replaces the theme sheet once, keeping its place in the cascade. A patch that changes no token does not touch the document.
#[component]
fn Page() -> impl IntoView {
let scheme = RwSignal::new_local(ColorScheme::Light);
let dark_theme = RwSignal::new_local(Preset::Base.dark());
view! {
ThemeProvider(scheme = scheme, dark = dark_theme) {
Switch(
default_checked = false,
on_change = UnsyncCallback::new(move |on: bool| {
scheme.set(if on { ColorScheme::Dark } else { ColorScheme::Light })
}),
a11y:label = "Dark mode"
)
Button(on:click = move |_| dark_theme.set(Preset::Midnight.dark())) {"Midnight"}
}
}
}To patch tokens from anywhere below a provider:
use zgui::reactive::Patch;
let theme = use_theme().expect("inside a ThemeProvider");
let mut next = Themes::defaults();
next.light.color.primary = "oklch(0.55 0.22 264)".to_owned();
theme.themes().patch(next);Code that reads one token group is not notified when another group changes.
A theme switch restyles the whole document, and changing spacing or type tokens also re-runs layout and text shaping. Treat it as an occasional event. For changes on every frame, toggle a class or set a custom property on one element instead. See Theming and the cost model.
Override tokens in CSS
Re-tinting the library takes five declarations:
:root {
--zui-color-primary: oklch(0.55 0.22 264);
--zui-color-primary-foreground: oklch(0.985 0 0);
--zui-color-accent: oklch(0.95 0.03 264);
--zui-color-accent-foreground: oklch(0.4 0.16 264);
--zui-color-ring: oklch(0.55 0.22 264);
}Your override must win the cascade against the theme sheet. Both are author sheets, and the
theme sheet is installed when the provider mounts, after app().with_stylesheet(…) sheets. A rule
of yours on :root ties on specificity and loses on order. Either pass the values to
ThemeProvider as a theme (with_css), or use a more specific selector. Declaring the override on
your own container also works through inheritance, but portalled surfaces are not inside that
container.
Add your own tokens
Declare them in your own sheet. Define them in terms of the library's tokens where it makes sense; they then follow both schemes automatically.
:root {
--app-sidebar-width: 260px;
--app-code-background: var(--zui-scale-neutral-3);
}
.sidebar { width: var(--app-sidebar-width); background-color: var(--zui-color-card); }The library also reads a few properties that neither the theme nor the provider declares. Set them yourself; there is no theme rule to override.
| Property | Read by | When undeclared |
|---|---|---|
--zui-icon-sm, -md, -lg, -xl | the icon sheet, per size; set on a container to size the icons under it | 12px, 16px, 20px, 24px |
--zui-icon-size | one icon's width and height; each icon declares it, so set it on the icon | the size token for its size |
--zui-overlay-depth | overlay z-index | written by the overlay components |
--zui-surface-place | overlay surface transform; a dialog writes it to centre itself | no offset |
--zui-surface-enter-*, --zui-surface-exit-* (-x, -y, -scale, -opacity, -duration, -ease) | overlay surface entrance and exit; set them on .zui-surface | 0px, 0px, 0.95, 0, --zui-motion-duration-normal, ease; an anchored surface slides 8px towards its trigger |
--zui-popper-available-width, -height | the maximum size of menus, select lists, popovers and date pickers | written by Popper: the room between the anchor and the window's edge |
For example, :root { --zui-icon-md: 18px } makes every default-size icon larger. See
Icons.
Read tokens in Rust
You rarely need to, because components work entirely in CSS. When you need a value in Rust (a chart
colour, a duration), use_theme() returns the nearest ThemeContext, or None outside a provider.
ThemeContext method | Returns |
|---|---|
themes() | Store<Themes>: the light and dark themes, readable group by group |
scheme() | the scheme signal (a System scheme is reported as System) |
selector() | ":root" or ".zui-theme-N" |
Token reference
Each group is a Rust struct of String fields (a token is a CSS value) with light() and dark()
defaults. A Theme holds one of each group.
| Group | Theme field | Prefix | Tokens |
|---|---|---|---|
ScaleTokens | scale | --zui-scale- | 24 |
ColorTokens | color | --zui-color- | 43 |
ControlTokens | control | --zui-color-control- | 11 |
SpacingTokens | space | --zui-space- | 8 |
RadiusTokens | radius | --zui-radius- | 10 |
TypeTokens | typography | --zui-type- | 26 |
ShadowTokens | shadow | --zui-shadow- | 9 |
MotionTokens | motion | --zui-motion- | 10 |
Every group has PROPERTIES (its custom property names, in field order), light(), dark(),
declare(), pairs() and set(property, value). Theme::properties() lists all 141 names.
Spacing, radii, type, shadows and motion are the same in both schemes; only colours differ.
Semantic colours
These are the tokens components use. All names start with --zui-color-, and values are written
in oklch().
| Token | Light | Dark |
|---|---|---|
background | oklch(1 0 0) | oklch(0.145 0 0) |
foreground | oklch(0.145 0 0) | oklch(0.985 0 0) |
card, popover | oklch(1 0 0) | oklch(0.205 0 0) |
card-foreground, popover-foreground | oklch(0.145 0 0) | oklch(0.985 0 0) |
tooltip | var(--zui-color-foreground) | same |
tooltip-foreground | var(--zui-color-background) | same |
tooltip-border | var(--zui-color-tooltip) | same |
primary | oklch(0.205 0 0) | oklch(0.922 0 0) |
primary-foreground | oklch(0.985 0 0) | oklch(0.205 0 0) |
secondary, muted, accent | oklch(0.97 0 0) | oklch(0.269 0 0) |
secondary-foreground, accent-foreground | oklch(0.205 0 0) | oklch(0.985 0 0) |
muted-foreground | oklch(0.556 0 0) | oklch(0.708 0 0) |
destructive | oklch(0.577 0.245 27.325) | oklch(0.704 0.191 22.216) |
destructive-foreground | oklch(0.97 0.01 17) | oklch(0.58 0.22 27) |
danger | var(--zui-color-destructive) | same |
success | oklch(0.627 0.194 149.214) | oklch(0.723 0.219 149.579) |
success-foreground | oklch(0.982 0.018 155.826) | oklch(0.266 0.065 152.934) |
warning | oklch(0.769 0.188 70.08) | oklch(0.828 0.189 84.429) |
warning-foreground | oklch(0.279 0.077 45.635) | same |
info | oklch(0.546 0.245 262.881) | oklch(0.707 0.165 254.624) |
info-foreground | oklch(0.97 0.014 254.604) | oklch(0.282 0.091 267.935) |
border | oklch(0.922 0 0) | oklch(1 0 0 / 10%) |
input | oklch(0.922 0 0) | oklch(1 0 0 / 15%) |
ring | oklch(0.708 0 0) | oklch(0.556 0 0) |
scrim | oklch(0 0 0 / 50%) | same |
chart-1 … chart-5 | oklch(0.87 0 0), 0.556, 0.439, 0.371, 0.269 (all achromatic) | same |
sidebar, sidebar-foreground, sidebar-primary, sidebar-primary-foreground, sidebar-accent, sidebar-accent-foreground, sidebar-border, sidebar-ring | the sidebar's own palette | its own dark set |
- The brand tint is five tokens:
primaryand its foreground (solid calls to action),accentand its foreground (hovered rows, highlighted menu items), andring(the focus ring). - The status tones
destructive,success,warningandinfoeach have a foreground for text on their fill. They are separate from the tint, so re-branding does not recolour a warning. Toast icons use them. dangeris an alias fordestructive, so you can make a message redder than a destructive button.- A tooltip inverts the page by default. Set the three
tooltiptokens to give it its own colours. - Chart colours are the same in both schemes, so a series keeps its colour.
Control colours
ControlTokens holds the few colours where a control uses a different token in each scheme, not
just a different value. They are part of the theme rather than a @media (prefers-color-scheme)
rule, so they follow a fixed ColorScheme instead of the desktop setting.
Token (--zui-color-control-…) | Light | Dark |
|---|---|---|
ring-invalid | destructive at 20% | destructive at 40% |
destructive-fill | destructive | destructive at 60% |
ghost-hover | accent | accent at 50% |
outline-border | border | input |
outline-hover | accent | input at 50% |
switch-off | input | input at 80% |
switch-thumb | background | foreground |
switch-thumb-on | background | primary-foreground |
tab-ink | foreground at 60% | muted-foreground |
tab-fill | background | input at 30% |
tab-border | transparent | input |
"At N%" means color-mix(in oklab, var(--zui-color-…) N%, transparent). Outlined buttons, toggles
and fields have no fill at rest; they take the colour of the surface behind them.
Colour ramps
--zui-scale-neutral-1 … -12 and --zui-scale-accent-1 … -12. The semantic colours do not
use the ramps; they are there for graded series and your own sheets.
| Steps | Use |
|---|---|
| 1–2 | page and surface backgrounds |
| 3–5 | component backgrounds: rest, hover, pressed |
| 6–8 | borders: subtle, normal, hover |
| 9–10 | solid fill, solid fill on hover |
| 11–12 | text: normal and high contrast |
The dark ramps are tuned to keep each step's contrast; they are not the light ramps reversed.
accent-9 (#0090ff) is the same in both schemes.
| Step | neutral light | neutral dark | accent light | accent dark |
|---|---|---|---|---|
| 1 | #fcfcfd | #111113 | #fbfdff | #0d1520 |
| 2 | #f9f9fb | #18191b | #f4faff | #111927 |
| 3 | #f0f0f3 | #212225 | #e6f4fe | #0d2847 |
| 4 | #e8e8ec | #272a2d | #d5efff | #003362 |
| 5 | #e0e1e6 | #2e3135 | #c2e5ff | #004074 |
| 6 | #d9d9e0 | #363a3f | #acd8fc | #104d87 |
| 7 | #cdced6 | #43484e | #8ec8f6 | #205d9e |
| 8 | #b9bbc6 | #5a6169 | #5eb1ef | #2870bd |
| 9 | #8b8d98 | #696e77 | #0090ff | #0090ff |
| 10 | #80838d | #777b84 | #0588f0 | #3b9eff |
| 11 | #60646c | #b0b4ba | #0d74ce | #70b8ff |
| 12 | #1c2024 | #edeef0 | #113264 | #c2e6ff |
Spacing and radii
Both scales are multiples of one base value, so one declaration re-spaces or re-rounds the whole
interface: set --zui-space-base or --zui-radius-base.
| Token | Value | Typical use |
|---|---|---|
--zui-space-base | 4px | the unit |
--zui-space-xs | base × 1 | icon to label |
--zui-space-sm | base × 2 | inside a dense control |
--zui-space-md | base × 3 | inside a normal control |
--zui-space-lg | base × 4 | inside a surface, between groups |
--zui-space-xl | base × 6 | between page sections |
--zui-space-2xl | base × 8 | around page content |
--zui-space-3xl | base × 12 | between major window regions |
| Token | Value | Typical use |
|---|---|---|
--zui-radius-base | 10px | the unit |
--zui-radius-none | 0px | square |
--zui-radius-sm | base × 0.6 | checkbox, dense badge |
--zui-radius-md | base × 0.8 | button, input, menu item |
--zui-radius-lg | base | card, popover, dialog |
--zui-radius-xl | base × 1.4 | sheet, drawer |
--zui-radius-2xl, -3xl, -4xl | base × 1.8, 2.2, 2.6 | larger panels |
--zui-radius-full | 9999px | pill or circle |
The derived steps are calc() expressions over the base; none and full are fixed values.
Type
| Axis | Tokens | Values |
|---|---|---|
| family | --zui-type-family-sans, -mono | Geist, ui-sans-serif, system-ui, sans-serif; "Geist Mono", ui-monospace, SFMono-Regular, Menlo, monospace |
| size | --zui-type-size-xs … -3xl | 12px, 14px, 16px, 18px, 20px, 24px, 30px |
| line height | --zui-type-leading-xs … -3xl | 16px, 20px, 24px, 28px, 28px, 32px, 36px |
| weight | --zui-type-weight-normal, -medium, -semibold, -bold | 400, 500, 600, 700 |
| letter spacing | --zui-type-tracking-tighter, -tight, -normal, -wide, -wider, -widest | -0.05em, -0.025em, 0em, 0.025em, 0.05em, 0.1em |
The size steps are xs, sm, md, lg, xl, 2xl and 3xl. Pair each size with the line
height of the same name. Sizes are absolute pixels and independent of the spacing base, so larger
text does not also enlarge every gap.
Shadows and motion
| Token | Use |
|---|---|
--zui-shadow-none | flat |
--zui-shadow-2xs | hairline under an edge |
--zui-shadow-xs | slightly raised control |
--zui-shadow-sm | card |
--zui-shadow-md | popover, menu |
--zui-shadow-lg | dialog, sheet |
--zui-shadow-xl | dragged item |
--zui-shadow-2xl | highest |
--zui-shadow-inset | pressed-in well |
| Token | Value |
|---|---|
--zui-motion-duration-none / -fast / -normal / -slow / -slower / -slowest | 0ms, 100ms, 150ms, 200ms, 300ms, 500ms |
--zui-motion-ease-standard | cubic-bezier(0.4, 0, 0.2, 1) |
--zui-motion-ease-out | cubic-bezier(0, 0, 0.2, 1) |
--zui-motion-ease-in | cubic-bezier(0.4, 0, 1, 1) |
--zui-motion-ease-linear | linear, for repeating animations |