variables #

Style variables, or just "variables" in fuz_css, are CSS custom properties that can be grouped into a theme. Each variable can have values for light and/or dark color-schemes. 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 any individual variable can still be pinned as an escape hatch. See themes for setting them.

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.

variable.ts

export type Theme = {
	name: string;
	/** What the theme looks like, for theme pickers. */
	summary?: string;
	variables: StyleVariable[];
	/** Single-scheme themes render one appearance in both color schemes. */
	scheme?: 'dual' | 'light' | 'dark';
	/** The derived stance mirror, from `resolve_theme_stance`. */
	scheme_mirror?: StyleVariable[];
};

export type StyleVariable = {
	name: string;
	light?: string;
	dark?: string;
	summary?: string;
};

Both are zod schemas, so the same names validate at runtime: Theme.safeParse(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.