Theming

Status: implemented in crates/zeyn/assets/zeyn.css.

The default UI kit reads every color, font, size and radius from CSS custom properties on :root. An organization changes the look by overriding a few of them. It never needs to edit zeyn.css or write selectors.

1. How a theme is applied

The server serves zeyn.css first and then, when the app has one, an extra stylesheet with token overrides. The override file only contains :root blocks:

:root {
  --z-brand: #7a2448;
  --z-font: "Source Sans 3", "Segoe UI", system-ui, sans-serif;
  --z-radius: 8px;
  --z-density: 0.75;
}

Rules for the override file:

• It must be served from the app's own origin. The Content Security Policy is style-src 'self', so inline <style> blocks and third party stylesheets are blocked.
• Fonts must already be installed on the users' machines or be served from the app's origin. The kit itself loads no web fonts.
• Load it after zeyn.css, so equal selectors win by order.
• Set the base tokens in section 2. The derived tokens in section 3 follow automatically. Override a derived token only when the computed value does not work for your brand.

Light, dark and app themes

Every app has a theme picker in the menu, next to the language picker. It offers System (follows prefers-color-scheme), Light, Dark and any theme the app defines:

App::new("Billing")
    .theme(Theme::new().brand("#7a2448").radius(6))
    .themes([
        Theme::light(),
        Theme::dark(),
        Theme::named("sand", [("--z-bg", "#f5f1ea"), ("--z-surface", "#fffdf8")]).label(t!("theme.sand")),
    ])
    .default_theme("system")

• App::theme is the organization's look and applies under every theme.
• App::themes lists what users can choose. Without it the list is Light and Dark. System is offered when both are in the list. Theme::named(...) builds on the light theme; .dark_base() builds it on the dark one.
• App::default_theme is the theme of users who have not chosen. system unless set.
• App::theme_picker(false) hides the picker; everyone gets the default theme.
• A single theme locks the app: .themes([Theme::named("acme", tokens)]) or .theme(Theme::dark()).

Tokens are checked when the app starts. App::check (and so router and serve) reports unknown token names, values that could leave their declaration (;, braces, \, <, >, url(), bad theme names, an unknown default theme, and every color pair of section 5 that a theme pushes below WCAG 2.2 AA. Only #rgb and #rrggbb values can be checked for contrast; other color syntax is trusted.

All themes are served in one stylesheet, /_zeyn/theme.css, built once at startup and loaded after the kit's stylesheets. The choice is stored in the zeyn_theme cookie and, for a signed in user in an app with a view store (App::datagrid_views), in that store, so it follows the user to a new device. The server renders the theme on <html>, so the first paint is already right and no inline script is needed:

Changing the theme in the picker only changes these attributes and the color-scheme meta, then calls POST /_zeyn/theme. Nothing reloads.

To give the dark theme its own values in a hand written override file, repeat the selectors the kit uses:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) { --z-bg: #0e1012; }
}
:root[data-theme="dark"] { --z-bg: #0e1012; }

Density

--z-density scales the spacing unit. 1 is regular, 0.75 is compact. <html data-density="compact"> sets 0.75 without a stylesheet. Controls and grid rows never get smaller than 24 px, so compact mode still meets the WCAG 2.2 target size.

The row height of a virtual grid is fixed by the server (Paging::virtual_rows(px), 32 px by default) because the runtime computes scroll positions from it. Density does not change it.

2. Base tokens

These are the tokens an organization is expected to set.

3. Derived tokens

Computed from the base tokens with color-mix() and relative color syntax. They update by themselves when a base token changes.

Per element tokens set by the server markup: --z-width (window width), --z-flex (column share), --z-row-height (virtual grid row height), and for the component library --z-stack-gap, --z-split, --z-progress, --z-columns, --z-level and --z-pop-x / --z-pop-y (popup position).

Chart series colors are --z-chart-1 to --z-chart-6 in components.css, with lighter values in the dark theme. Each reaches 3:1 against --z-surface. Override them like any base token.

4. Choosing a brand color

• --z-brand carries white text in the light theme (buttons, app name band). Pick a color with at least 4.5:1 against --z-on-brand. Most mid to dark brand colors pass. For a light brand color such as yellow, also set --z-on-brand to a dark color.
• In the dark theme the kit lightens the brand for text, rings and primary buttons, and keeps the solid brand for the app name band. A different brand looks deliberate in both themes without a second color.
• Keep status colors distinct from the brand. A red brand next to red error rows makes errors harder to spot; in that case shift --z-danger toward a different red or keep the brand off grids by overriding --z-brand-subtle.
• Check your colors with the table in section 5 as a target. Any pair below the threshold fails WCAG 2.2 AA.

5. Verified contrast

Measured in Chromium on the running example app: every token was resolved to its rendered sRGB value (including color-mix() and relative colors), then the WCAG 2.x contrast ratio was computed. Thresholds: 4.5:1 for text, 3:1 for UI component outlines and focus indicators.

--z-border is decorative (dividers between items that already have text) and is not held to 3:1.

6. Other accessibility behavior

• Every interactive element shows a 2 px :focus-visible ring in --z-focus. Grid rows draw the ring inside the row so it is never clipped by the scroll container.
• Buttons, inputs, sort headers, filter boxes, pager buttons and the window close button are at least 24 x 24 px at any density.
• prefers-reduced-motion: reduce removes the toast entrance and all transitions.
• In forced-colors mode icons use CanvasText, the primary button and the focused row use Highlight, and state that relies on background tints (current menu item, row status) gets an outline or border instead.