variables #

Style variables, or just "variables" in fuz_css, are CSS custom properties that can be grouped into a theme. Each variable has a base value that applies in both color-schemes, a dark value that replaces it in dark mode, or both. They're design tokens with an API.

The goal of the variables system is to provide runtime theming that's efficient and ergonomic for both developers and end-users. Variables can be composed in multiple ways:

• by CSS classes, both utility and component
• by other variables, both in calculations and to add useful semantics (e.g. button_fill_hover uses shade_50 but can be themed independently)
• in JS like the Svelte components in fuz_ui

Variables also provide an interface that's generally secure for user-generated content, if you're into that kind of thing.

The result is a flexible system that aligns with modern CSS to deliver high-capability UX and DX with low overhead.

Most color variables are derived: knobs feed ramp stops and ramp stops feed color stops, all computed in pure CSS (calc()/pow()/oklch()). Scale knobs like radius_scale derive other families the same way, and a derived token or color stop can still be pinned as an escape hatch. The ramp stops in between are internal (--_palette_lightness_30), so a theme can't set them. See themes for setting the rest.

In bundled mode, only the variables your code uses are emitted, along with any they depend on. The full theme.css stylesheet ships every variable, for utility-only mode and direct imports.

Both are @fuzdev/fuz_schema schemas, so the same names validate at runtime: s.parse(Theme, value) reports what's wrong, parse_theme(value) returns a theme or null, and validate_theme(theme) in theme_validate.ts runs the full lint.

Hooks are the contextual surface: custom properties the base styles and classes read but don't declare as variables, so they have no :root default. Set one on an element to retune what reads it there, with a literal class like --flow_margin:0 or in a component's styles - the sized_* composites work this way, setting --flow_margin and --font_size for their subtree. Where nothing sets a hook, its read falls back to the value listed. A local hook is declared by the rule that reads it, so a value reaches it only from a rule on the same element.

Hooks aren't theme variables: from a theme's root, an inherited hook retunes every element that reads it and a local one reaches nothing, so validate_theme warns on a theme that sets one. Themes turn the knobs instead. The catalog is style_hooks.ts.