introduction #

fuz_css is a semantic-first CSS framework and design system. It styles elements by default and integrates custom properties, themes, and utility classes into a complete system. It ships two plain CSS files, the base style.css and replaceable theme.css, that work with any framework and plain HTML, and its class generator supports HTML/JS/TS, Svelte, React, Preact, Solid, and other JSX frameworks. For more see the framework support docs, and for the companion Svelte components see fuz_ui.

The only required parts are a reset stylesheet with the semantic defaults and a replaceable theme stylesheet containing the variables used in the reset, and these require no dependencies. There's also utility classes for composition and convenience with a Vite plugin, and the library exports the full API for complex usage.

More at the docs and repo.

Design details
#

plain CSS
minimal dependencies, all optional (none needed if you only use the stylesheets)
exports a reset stylesheet with semantic defaults that styles HTML elements, and also exports the underlying data, helpers, and types for open-ended usage
supports themes as sets of style variables, baked in at build time or swapped at runtime; dark mode isn't a theme but a color scheme any theme can support
supports optional utility classes with three types (token, composite, CSS-literal) and modifiers for responsive, state, color-scheme, and pseudo-elements
uses its own concept of style variables, a specialization of CSS custom properties and design tokens that integrate with the other systems (e.g. the reset stylesheet and token classes use variables, and themes are groups of variables)
the stylesheets work with any framework and plain HTML; utility class generation supports HTML/JS/TS, Svelte, and JSX - see the utility class framework support, and for the companion Svelte integration see ThemeRoot in fuz_ui
see the comparison to alternatives to understand fuz_css relative to TailwindCSS and UnoCSS

Usage
#

npm i -D @fuzdev/fuz_css

Use the Vite plugin or Gro generator for bundled CSS that includes theme variables, base styles, and utility classes in a single import. Add the plugin to your Vite config:

// vite.config.ts
import {vite_plugin_fuz_css} from '@fuzdev/fuz_css/vite_plugin_fuz_css.ts';

export default defineConfig({plugins: [sveltekit(), vite_plugin_fuz_css()]});

Then import it, normally from your root layout:

// bundled mode (recommended)
// includes only used base styles, variables, and utilities
import 'virtual:fuz.css'; // Vite plugin
// or
import './fuz.css'; // Gro generator, written to the filesystem

That single import is all most projects need, since it already holds the base styles and theme variables your code uses. Projects managing their own theme or base styles can use utility-only mode instead, importing the full stylesheets and turning the generated ones off so neither layer ships twice:

// utility-only mode - set `base_css: null, variables: null` on the plugin
import '@fuzdev/fuz_css/style.css'; // all base styles
import '@fuzdev/fuz_css/theme.css'; // all variables
import 'virtual:fuz.css'; // used utilities only

See the classes reference for setup details and configuration options.

Browser support
#

The shipped CSS needs Chrome or Edge 120, Firefox 118, or Safari 16.2 - Safari 16.4 if you use responsive modifier classes like md:, which emit media range syntax, and 16.5 for color-scheme modifier classes like dark:, which emit nested CSS.

There are no fallbacks. Every rule sits in a cascade layer ( @layer), the color scales are computed in CSS with oklch(), calc(), and pow(), and color-mix() drives button fills, shadows, and the placeholder color. pow() sets the Chrome and Firefox floors: a browser without it keeps the page background and color scheme (the ends of each scale don't use it) but loses every stop between, which carry the text, border, and accent colors. A browser without cascade layers drops every rule, leaving unstyled HTML.

api #

Browse the full api docs.

examples #

The example repos demonstrate the classes system using the Vite plugin:

vite-svelte - Svelte 5
vite-react - React 19
vite-preact - Preact
vite-solid - Solid

For projects using Gro, see fuz_template for integration with gen_fuz_css.ts.

semantic #

fuz_css styles HTML elements in its reset stylesheet, so semantic markup gets themed and color-scheme-aware styling automatically - utility classes optional. The goal is to be accessible and attractive out of the box, minimal yet extensible.

Layers and specificity
#

All opinionated styles live in the fuz.base cascade layer, so your unlayered styles and the generated utility classes override them by layer order alone. Their selectors are also wrapped in :where() for zero specificity, so overrides stay easy even inside the fuz layers. The exceptions are the document-wide rules: :root, body, [hidden], and ::selection.

/* any styles you apply will override these */
:where(a:not(.unstyled)) {
  color: var(--link_color);
  font-weight: 700;
}

:where(button:not(.unstyled)) {
  background-color: var(--button_fill);
  border-radius: var(--border_radius, var(--control_radius));
}

.unstyled escape hatch
#

Add the .unstyled builtin class to opt out of decorative styling while keeping reset normalizations. Works for both decorative containers and interactive elements like links, buttons, inputs, and summary.

<a href="/home">styled link</a>
<a href="/home" class="unstyled">unstyled link</a>

styled link vs unstyled link

<button>styled button</button>
<button class="unstyled">unstyled button</button>

Document flow by default
#

Block elements get margin-bottom via :not(:last-child), creating natural vertical rhythm without trailing margins.

:where(
  :is(p, ul, ...[many others])
    :not(:last-child):not(.unstyled)
) {
  margin-bottom: var(--flow_margin, var(--space_lg));
}

The --flow_margin variable is unset by default, falling back to var(--space_lg). Size composite classes like .sized_sm and .sized_lg set --flow_margin to adjust vertical rhythm for all flow elements and headings.

For elements not in the flow list, use the .mb_flow and .mt_flow composite classes to get the same size-responsive spacing. Use .mb_lg when you want a fixed value that ignores size composites.

⚠️ The :not(:last-child) creates unfortunate edge cases by coupling structure to style, including usage with Svelte's component-level CSS variables, because it adds a wrapper div. Perhaps the better global optimum is to omit the last child exception? This would add unwanted margin in many cases, but perhaps that's better overall; mb_0 removes it.

Flex containers reset flow margins
#

The .row layout composite resets margins on its direct children. Flow margins make less sense in horizontal flex layout - for spacing prefer gap utilities like .gap_md and gap: var(--space_sm) instead.

:where(.row > *) {
  margin: 0;
}

Element-specific docs
#

See the related docs for specifics:

buttons - button states, colors, variants
elements - links, lists, tables, code, details
forms - inputs, labels, checkboxes, selects
typography - headings, fonts, text styles

themes #

Themes
#

A theme is a set of knob values, not a stylesheet: plain data naming variables, where a handful of high-leverage knobs (hue angles, chroma_scale, the lightness curves - see colors) reshape everything derived from them. Selecting a theme applies it to this whole website and loads its knobs into the editor below.

Contrast

Color scheme

Theme

base - The defaults: a blue accent, warm-tinted grays on an untinted page, serif headings over sans text, every knob at its starting value.

A heading

Body text with a link and inline code.

accent positive negative caution info

chip

checkbox

Contrast is a modifier, not a theme: the low and high contrast modifiers compose over any theme with compose_themes (flatten + last-wins), so every theme gets both variants for free. The OS prefers-contrast: more preference maps onto the same variables the high contrast modifier sets, so it reaches every theme with no modifier picked.

Color scheme
#

Light and dark are color schemes within a theme ( color-scheme), not separate themes: each variable can carry a value for either, so any theme can implement dark mode. The scheme follows prefers-color-scheme by default. To set it manually, add the dark class to the root html element, or use a component like ColorSchemeInput (the picker at the top of this page) from the companion Svelte library fuz_ui.

A theme can instead take a single-scheme stance with scheme: 'light' | 'dark': its one appearance renders in both color schemes, and color-scheme is pinned to match. The phosphor and marquee themes are dark-only this way, since a CRT and a lit sign have no daytime appearance. Every other theme is dual-scheme, parchment included, whose dark appearance is the same page by candlelight.

Applying a theme
#

A theme applies at build time or at runtime, and most projects want build time. Every theme on this page ships as its own module under themes/, and themes.ts holds the registry and the contrast modifiers.

Pass a theme to the Vite plugin or Gro generator and its values bake into the generated CSS - no runtime rendering, no JavaScript shipped, and the output stays tree-shaken:

// vite.config.ts
import {vite_plugin_fuz_css} from '@fuzdev/fuz_css/vite_plugin_fuz_css.ts';
import {phosphor_theme} from '@fuzdev/fuz_css/themes/phosphor.ts';

export default defineConfig({plugins: [vite_plugin_fuz_css({theme: phosphor_theme})]});

The theme's variables replace the defaults by name, so it composes with the variables option. They also render into the fuz.theme.baked cascade layer, above the OS preference mappings and with color-scheme pinned for a stance, so a baked theme behaves the same as one applied at runtime.

For runtime switching - a picker, or a theme loaded per user - use ThemeRoot from fuz_ui, which renders the theme to a <style> element in the fuz.theme layer. The two paths compose: a runtime theme overrides a baked one, since a layer's direct styles outrank its sublayers. Outside Svelte, render_theme_style in theme.ts does the same rendering for any framework.

Knobs take effect at the root: the derived color stops compute on :root and descendants inherit the result, so setting a knob like --chroma_scale on an element changes nothing below it. Set knobs through a theme, and when a subtree needs its own color, set the variable its styles read there instead.

Theme editor
#

Drag a knob and the whole page rethemes live. Extreme values can make the page hard to read, which is an honest signal, not a bug. Every edit updates a temporary "unsaved" theme in the picker above; it survives navigating away and back, but copy the Theme object from the output below to keep it.

name

based on

scheme

semantic-tier

edits write to the light scheme's slots

intents - what each meaning points at

--hue_neutral

--hue_accent

--hue_positive

--hue_negative

--hue_caution

--hue_info

levers - the highest-leverage knobs

--neutral_chroma

--chroma_scale

--radius_scale

--space_scale

--shadow_alpha_scale

--font_family

--font_size_scale

--type_scale_ratio

Color

shade

text

accent

positive

negative

caution

info

--hue_neutral

--neutral_chroma

--shade_chroma_00

--hue_accent

--chroma_scale

--hue_positive

--hue_negative

--hue_caution

--hue_info

--palette_lightness_00

--palette_lightness_100

--palette_lightness_curve

--shade_lightness_00

--shade_lightness_100

--shade_lightness_curve

--text_lightness_00

--text_lightness_100

--text_lightness_curve

--palette_chroma_min

--palette_chroma_max

--chroma_curve

--border_color

chroma character & surface colors (per-slot multipliers and micro-surface colors)

--accent_chroma_scale

--positive_chroma_scale

--negative_chroma_scale

--caution_chroma_scale

--info_chroma_scale

--border_color_lightness

--border_color_chroma

--input_fill

--caret_color

--scrollbar_thumb_color

--scrollbar_track_color

--disabled_opacity

palette hues (the letter slots - moving these makes the theme palette-tier)

palette_a

palette_b

palette_c

palette_d

palette_e

palette_f

palette_g

palette_h

palette_i

palette_j

--hue_a

hue:

--hue_b

hue:

--hue_c

hue:

--hue_d

hue:

--hue_e

hue:

--hue_f

hue:

--hue_g

hue:

--hue_h

hue:

--hue_i

hue:

--hue_j

hue:

--palette_a_chroma_scale

--palette_b_chroma_scale

--palette_c_chroma_scale

--palette_d_chroma_scale

--palette_e_chroma_scale

--palette_f_chroma_scale

--palette_g_chroma_scale

--palette_h_chroma_scale

--palette_i_chroma_scale

--palette_j_chroma_scale

Shape

--radius_scale

--border_radius_min

--control_radius

--border_style

border width & radius tokens (escape hatches - pin individual tokens)

--button_border_style

--button_border_style_active

--outline_offset

--outline_style

--outline_width_focus

--border_width

--border_width_1

--border_width_2

--border_width_3

--border_width_4

--border_width_5

--border_width_6

--border_width_7

--border_width_8

--border_width_9

--border_radius_xs3

--border_radius_xs2

--border_radius_xs

--border_radius_sm

--border_radius_md

--border_radius_lg

--border_radius_xl

Density

--space_scale

space tokens (escape hatches - pin individual tokens)

--space_xs5

--space_xs4

--space_xs3

--space_xs2

--space_xs

--space_sm

--space_md

--space_lg

--space_xl

--space_xl2

--space_xl3

--space_xl4

--space_xl5

--space_xl6

--space_xl7

--space_xl8

--space_xl9

--space_xl10

--space_xl11

--space_xl12

--space_xl13

--space_xl14

--space_xl15

Depth

--shadow_alpha_scale

--shadow_color_umbra

--shadow_color_highlight

--shadow_color_glow

--shadow_color_shroud

--button_shadow

--button_shadow_hover

--button_shadow_active

--pane_shadow

--panel_shadow

backdrop (the dialog and fullscreen backdrop dim)

--backdrop_color

Typography

--font_family

--font_size_scale

--type_scale_ratio

--font_family_sans

--font_family_serif

--font_family_mono

--heading_font_family

--font_weight

--heading_font_weight

--text_decoration

line height tokens (escape hatches - pin individual tokens)

--heading_letter_spacing

--line_height_xs

--line_height_sm

--line_height_md

--line_height_lg

--line_height_xl

Motion

duration tokens (escape hatches - pin individual tokens)

--duration_1

--duration_2

--duration_3

--duration_4

--duration_5

--duration_6

Decoration

--background_image

Gates

validate_theme and check_theme run live against the draft - the same lint and gamut/monotonicity/contrast gates the shipped themes are held to in CI.

all gates pass (484 checks)

Output

The copyable Theme object, and the CSS it renders - the variables the theme sets, plus the scheme-stance mirror when the theme is single-scheme.

theme object

rendered CSS

Validating and compiling themes
#

validate_theme(theme) in theme_validate.ts is the structural lint. Unknown variable names are errors, and everything else it flags is an advisory warning: type and range mismatches on the knob-tier variables, a stance without its resolved mirror, and intent bindings that put the accent beside a status hue or drop a palette slot's chroma character. It returns an array of issues - empty means the theme is structurally sound.

check_theme(theme) in theme_check.ts runs the gamut, ramp-monotonicity, and contrast gates against the theme's resolved values. It reports rather than throws, returning {ok, entries, unchecked}. The contrast gates measure the pairings the default styles make on the page background - body and subtle text, links, borders, fills, and colored labels, including a .palette_a button's label on its own tinted fill. They follow the role variables those styles paint through, so a theme that sets border_color to var(--text_60) has its borders measured at text_60, in an entry named border_color vs shade_00.

A value a gate depends on but can't evaluate lands in unchecked instead of passing unread: a knob that doesn't resolve to a number, or a color stop or role set to anything other than an oklch(L C H) numeric literal or an exact var() reference to another gated color. ok is true only when every entry passes and nothing is unchecked, which suits a CI or test assertion:

import {test, assert} from 'vitest';
import {check_theme} from '@fuzdev/fuz_css/theme_check.ts';
import {my_theme} from './my_theme.ts';

test('my theme clears the accessibility gates', () => {
	assert.isTrue(check_theme(my_theme).ok);
});

compile_theme(theme) is for themes that move hues or palette lightness - monochrome, rotated, or dark-only. It recomputes the per-stop sRGB gamut caps from the theme's actual hues and the lightness each stop resolves to, a pinned palette_lightness_NN included, and appends the corrected palette_chroma_NN stop overrides, returning {theme, report, issues}. Chroma pushed past the caps on purpose (chroma_scale above 1) still clips afterward, and the report says so.

fuz_css gates its own themes with these functions in its test suite, every theme × contrast-modifier composition included, and declares the pairings an exemplar knowingly gives up as exact exceptions. The editor above runs the same lint and gates live on every edit.

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.

All 569 style variables
#

classes #

fuz_css has two categories of CSS classes: utilities and builtins. Builtins are baked into the main stylesheet; utility classes have three types, are optional, and require build tool integration.

Utility classes complement semantic styles and style variables. Use them to compose styles across component boundaries, or when you prefer classes to the <style> tag and style attribute. They're optional and generated on-demand to include only what you use.

Compared to TailwindCSS and UnoCSS, fuz_css utility classes follow the grain of semantic HTML rather than being foundational to the design, and the DSL is currently more limited, with interpreters providing a programmatic escape hatch - see the comparison below.

Compared to the <style> tag, classes:

offer shorthand for style variables (p_lg vs padding: var(--space_lg))
compose across component boundaries, avoiding fragile :global() selectors
let you avoid noisy class names like foo-wrapper and bar-inner

Compared to the style attribute, classes:

support powerful modifiers for responsive widths, interaction states (like hover), and dark mode
provide more control over specificity
compose ergonomically with libraries like clsx, which Svelte supports natively

For cases where classes lack clear advantages, style and <style> are simpler and avoid generating class definitions, which can bloat your builds when overused.

Usage
#

npm i -D @fuzdev/fuz_css

Use the Vite plugin or Gro generator to generate bundled CSS that includes theme variables, base styles, and utility classes:

Vite plugin
#

The Vite plugin extracts classes and generates CSS on-demand. It works with Svelte and plain HTML/TS/JS out of the box. JSX frameworks (React, Preact, Solid) require the acorn-jsx plugin - see React and JSX below.

// vite.config.ts
import {defineConfig} from 'vite';
import {sveltekit} from '@sveltejs/kit/vite';
import {vite_plugin_fuz_css} from '@fuzdev/fuz_css/vite_plugin_fuz_css.ts';

export default defineConfig({
  plugins: [sveltekit(), vite_plugin_fuz_css()],
});

Import the virtual module in your entry file, src/routes/+layout.svelte for SvelteKit:

// +layout.svelte - bundled mode (recommended, default config)
// includes only used base styles, variables, and utilities
import 'virtual:fuz.css';

For projects managing their own theme or base styles, disable them and import separately:

// vite.config.ts - utility-only mode
vite_plugin_fuz_css({
	base_css: null,
	variables: null,
}),

// +layout.svelte - full package CSS, only used utilities
import '@fuzdev/fuz_css/style.css'; // all base styles
import '@fuzdev/fuz_css/theme.css'; // all variables
import 'virtual:fuz.css';

The plugin needs Vite 6 or later. It extracts classes from files as Vite processes them, including from node_modules dependencies, and in dev it pre-scans your sources and the root index.html at startup so the first page load is fully styled. It supports HMR: changes to classes in your code trigger automatic CSS updates. List it after any plugin that rewrites CSS in its transform hook.

Plugin options

acorn_plugins - required for JSX frameworks, e.g. acorn-jsx
additional_classes - classes to always include (for dynamic patterns that can't be statically extracted)
exclude_classes - classes to exclude from output
class_definitions - custom class definitions to merge with defaults; can define new classes or override existing ones (see composite classes)
include_default_classes - set to false to use only your own class_definitions, excluding all default token and composite classes
class_interpreters - custom interpreters for dynamic class generation; replaces the default interpreters entirely if provided (most users don't need this)
filter_file - custom filter for which files to process. Receives (id: string, root: string) and returns boolean, e.g. (id) => !id.includes('/fixtures/')
on_error - 'log' or 'throw'; defaults to 'throw' in CI, 'log' otherwise
on_warning - 'log', 'throw', or 'ignore'; defaults to 'log'
cache_dir - cache location; defaults to .fuz/cache/css
cache_salt - a string folded into the cache key; change it when only an acorn plugin's options change, since the key already covers file content and the plugins
prescan - dev-only scan of sources at server startup; true (default) scans src under the Vite root, false disables, or pass an array of directories
base_css - customize or disable base styles; set to null for utility-only mode, or provide a string to replace the defaults or a callback to modify them (see what gets included)
variables - customize or disable theme variables; set to null for utility-only mode, or provide an array to replace the defaults or a callback to modify them
theme - a themes to bake into the generated CSS, overlaid onto variables last-wins by name
additional_elements - elements to always include styles for (for runtime-created elements), or 'all' to include all base styles
additional_variables - variables to always include in theme output, or 'all' to include all theme variables

TypeScript setup

Add the virtual module declaration, like to vite-env.d.ts:

/// <reference types="vite/client" />

declare module 'virtual:fuz.css' {
  const css: string;
  export default css;
}

Gro generator
#

For projects using Gro, the gen_fuz_css.ts generator creates a *.gen.css.ts file anywhere in src/:

// src/routes/fuz.gen.css.ts for SvelteKit, or src/fuz.gen.css.ts, etc.
import {gen_fuz_css} from '@fuzdev/fuz_css/gen_fuz_css.ts';

export const gen = gen_fuz_css();

Then import the generated file, in src/routes/+layout.svelte for SvelteKit:

// +layout.svelte - bundled mode (recommended, default config)
// includes only used base styles, variables, and utilities
import './fuz.css';

For projects managing their own theme or base styles, disable them and import separately:

// fuz.gen.css.ts - utility-only mode
export const gen = gen_fuz_css({
	base_css: null,
	variables: null,
});

// +layout.svelte - full package CSS, only used utilities
import '@fuzdev/fuz_css/style.css'; // all base styles
import '@fuzdev/fuz_css/theme.css'; // all variables
import './fuz.css';

Generator options

The Gro generator accepts the same options as the Vite plugin, plus additional options for batch processing:

include_stats - include file statistics in output (file counts, cache hits/misses, class counts)
project_root - project root directory; defaults to process.cwd()
concurrency - max concurrent file processing for cache reads and extraction; defaults to 8
cache_io_concurrency - max concurrent cache writes and deletes; defaults to 50

Class detection
#

The extractor scans your source files and extracts class names using three automatic mechanisms, plus manual hints for edge cases:

1. Direct extraction from class attributes

String literals and expressions in class contexts are extracted directly:

class="..." - static strings
class={[...]} - array syntax (for clsx-compatible frameworks like Svelte)
class={{...}} - object syntax (for clsx-compatible frameworks like Svelte)
class={cond ? 'a' : 'b'} - ternary expressions
class={(cond && 'a') || 'b'} - logical expressions
class:name - class directives (Svelte)
clsx(), cn(), cx(), classNames() - utility function calls

2. Naming convention

Variables ending with class, classes, className, classNames, class_name, or class_names (case-insensitive) are always extracted, regardless of where they're used:

// extracted because of naming convention
const buttonClasses = 'palette_d font_size_lg';
const buttonClass = active ? 'active' : null;
const snake_class = 'snake';
const turtle_class_name = 'turtle';

3. Usage tracking

Variables used in class attributes are tracked back to their definitions, even if they don't follow the naming convention:

<script>
	const styles = 'some-class';   // tracked from class={styles}
	const variant = 'other-class'; // tracked from clsx()
</script>

<div class={styles}></div>
<button class={clsx('palette_d', variant)}></button>

Usage tracking works for variables inside clsx(), arrays, ternaries, and logical expressions within class attributes. Note that standalone clsx() calls outside class attributes don't trigger tracking - use the naming convention for those cases.

4. Manual hints

For dynamically constructed classes that can't be statically analyzed, use the @fuz-classes comment:

// @fuz-classes opacity:50% opacity:75% opacity:100%
const opacity_classes = [50, 75, 100].map((n) => `opacity:${n}%`);

/* @fuz-classes color_a_50 color_b_50 color_c_50 */
const color = get_dynamic_color();

A common case is iterating over variant arrays to generate demos or UI. The extractor sees class="shadow_alpha_{variant}" but can't resolve what variant will be at runtime:

<script>
	import {shadow_alpha_variants} from '@fuzdev/fuz_css/variable_data.ts';

	// @fuz-classes shadow_alpha_00 shadow_alpha_05 shadow_alpha_10 ... shadow_alpha_100
</script>

{#each shadow_alpha_variants as variant}
	<div class="shadow_alpha_{variant}">...</div>
{/each}

Edge values like _00 and _100 are especially easy to miss - they're generally not used directly in your code (they exist mainly for programmatic usage ergonomics), so the class won't be generated unless you hint it.

Classes annotated with @fuz-classes and configured with additional_classes produce errors if they can't be resolved. This helps catch typos like @fuz-classes color_a_55 instead of color_a_50. A class that only the base styles define, like selected or palette_a, resolves when base styles are bundled, and the hint ships the base rules that target it.

Alternatively, use the additional_classes option in your config to the Vite plugin or Gro generator:

vite_plugin_fuz_css({
	additional_classes: ['opacity:50%', 'opacity:75%', 'opacity:100%'],
});

Use exclude_classes to filter out false positives from extraction. This also suppresses warnings for these classes, even if they were explicitly annotated:

vite_plugin_fuz_css({
	exclude_classes: ['some:false:positive'],
});

Element hints

Similar to @fuz-classes, use @fuz-elements to declare elements that should be included even when they can't be statically detected:

// @fuz-elements dialog
const el = document.createElement('dialog');

Like @fuz-classes, explicit declarations via @fuz-elements produce errors if they can't be resolved, helping catch typos early.

CSS variable detection

CSS variables are detected via simple regex scan of var(--name patterns in all source files. Only theme variables are included; unknown variables are silently ignored. This approach catches usage in component props like size="var(--icon_size_xs)" that AST-based extraction would miss.

When variable names are constructed at runtime (e.g. with template literals), use @fuz-variables to explicitly include them:

<script>
	import {shade_scale_variants} from '@fuzdev/fuz_css/variable_data.ts';

	// @fuz-variables shade_min shade_00 shade_05 shade_10 ... shade_100 shade_max
</script>

{#each shade_scale_variants as variant}
	<div style:background="var(--shade_{variant})">...</div>
{/each}

Like @fuz-classes and @fuz-elements, explicit declarations via @fuz-variables produce errors if they can't be resolved, helping catch typos early.

5. Build-time limitations

Class and element detection happens at build time via static analysis. Content created dynamically at runtime (document.createElement(), innerHTML, framework hydration) won't be detected.

Use additional_elements to force-include element styles for runtime-created elements:

vite_plugin_fuz_css({
	additional_elements: ['dialog', 'details', 'datalist'],
});

What gets included
#

Detection finds the classes, elements, and variables your source uses (see class detection above), and resolution turns that into CSS. Bundled mode (the default for the Vite plugin and Gro generator) combines three layers into a single output, each trimmed to what your code uses:

style variables as :root custom properties (the full version of which is theme.css)
the reset stylesheet's base styles for the HTML elements you use (the full version of which is style.css)
used utility classes (always generated on demand; there's no full version)

Sections are emitted in that order inside @layer cascade layers: defaults in fuz.base, OS user-preference mappings (like prefers-contrast) in fuz.preferences, theme overrides in fuz.theme, and utilities in fuz.utilities, so utilities beat the reset by layer order (not specificity) and your own unlayered styles beat everything. The exceptions are two !important declarations, which a layer makes outrank unlayered styles too: [hidden], and the prefers-reduced-motion mapping that clears the --duration_* variables so a theme can't re-enable motion.

If you use @layer for your own styles, declare fuz's layers first so yours come later and win: @layer fuz.base, fuz.preferences, fuz.theme, fuz.utilities, app;. Without that line, fuz's layers are declared when its CSS loads, after any of yours, and beat them.

Base styles

A rule from the reset stylesheet is kept when any element or class in its selector is detected. Kept rules are emitted in source order, tree-shaking unused rules. A top-level @media, @supports, or @container rule is kept or dropped whole, by the elements and classes of the rules inside it.

Some rules are always included regardless of detection:

the universal reset (*), :root and :host, html, and body
rules whose selector can't be matched against what's detected: one naming no element or class (like ::selection and [hidden]), or an escaped or non-ASCII name (like .md\:flex)
every other at-rule, like @keyframes and @font-face

For apps that use dynamic HTML patterns, element detection may have false negatives, omitting styles that you actually need. The reliable fix is to ship the full reset with additional_elements: 'all'. Reach for an explicit additional_elements list only when you want to keep the base CSS minimal and know exactly which extra tags appear at runtime.

// ship the full base reset, not just detected tags
vite_plugin_fuz_css({
	additional_elements: 'all',
});

The base_css option replaces the reset stylesheet with a string, or transforms it with a callback that receives the default CSS. Either form takes any CSS the parser accepts and is tree-shaken by the rules above. All of it lands in fuz.base, a callback's additions included, so it sits below themes and utilities; put overrides that must win in your own stylesheet.

vite_plugin_fuz_css({
	// tree-shaken with the rest: ships when a `.prose` class is used
	base_css: (css) => css + '\n.prose { max-width: 65ch; }',
});

The generator owns the layering, so an @layer of your own in base_css is an error (base_css_layer), as are @import and @namespace, which are invalid inside a layer (base_css_unsupported_at_rule). An error never removes CSS: the rule ships as written, and the error names it and its line. Only a top-level @charset is left out, since an encoding marker means nothing in a string.

Variables

A style variable is included when:

a kept base-style rule uses it,
a generated utility class uses it,
your source references var(--name) directly, e.g. in a style attribute, a <style> block, or an imported CSS file (including a dependency's stylesheet), or
it's force-included via additional_variables.

Dependencies resolve transitively, so pulling in a variable also pulls in any it's built from via var(), and both light and dark values are kept together, so switching color-scheme at runtime never hits a missing variable. The complete set ships in theme.css for utility-only mode and direct imports; bundled mode trims it to what you use.

The variables option is the whole set to draw from. If a kept base-style rule references a variable the defaults define but your set lacks (with null, an empty array, or a partial set), generation reports the error undefined_theme_variables, since a var(--name) with no fallback would resolve to nothing. It never fires for a reference with a fallback, a name the base styles declare themselves (in the same rule, or in a top-level rule whose selector is exactly :root, :host, html, body, or *), or a custom property of your own.

Define the missing variables, or for bundled base styles over a theme stylesheet you import separately, declare the default set defined elsewhere:

import {default_variables} from '@fuzdev/fuz_css/variables.ts';

vite_plugin_fuz_css({
	variables: null,
	exclude_variables: default_variables.map((v) => v.name),
});

Forcing and excluding

When static analysis can't see something, or sees too much, override resolution with the CssGeneratorBaseOptions: additional_classes, additional_elements, and additional_variables force-include (the element and variable options also accept 'all'), while exclude_classes, exclude_elements, and exclude_variables drop items from the output. Excluding a variable that's still referenced by included styles logs a warning, since the dropped var(--name) would otherwise resolve to nothing.

Utility class types
#

Token classes
#

Token classes are technically composite classes with a close relationship to style variables: each maps design tokens to CSS properties. They're generated programmatically from variant data, making them predictable and systematic. The composites documented below are hand-written and typically represent higher-level semantic concepts. For raw CSS values, use literal classes instead.

<p class="pl_xl3 color_g_50">some token classes</p>

some token classes

Token classes use snake_case because style variables are designed for optional use in JS (imported from variables.ts, but costing nothing otherwise), so each name is consistent across both JS and CSS, instead of converting between kebab-case and camelCase. This also makes token classes visually distinct from literal classes; we find this improves readability.

Spacing

See layout.

.p_{xs5-xl15} .p_0
.pt_{xs5-xl15} .pt_0
.pr_{xs5-xl15} .pr_0
.pb_{xs5-xl15} .pb_0
.pl_{xs5-xl15} .pl_0
.px_{xs5-xl15} .px_0
.py_{xs5-xl15} .py_0
.m_{xs5-xl15} .m_0 .m_auto
.mt_{xs5-xl15} .mt_0 .mt_auto
.mr_{xs5-xl15} .mr_0 .mr_auto
.mb_{xs5-xl15} .mb_0 .mb_auto
.ml_{xs5-xl15} .ml_0 .ml_auto
.mx_{xs5-xl15} .mx_0 .mx_auto
.my_{xs5-xl15} .my_0 .my_auto
.gap_{xs5-xl15}
.column_gap_{xs5-xl15}
.row_gap_{xs5-xl15}
.top_{xs5-xl15}
.right_{xs5-xl15}
.bottom_{xs5-xl15}
.left_{xs5-xl15}
.inset_{xs5-xl15}

Padding and margin include _0 (and _auto for margin) for ergonomics: pb_0 is much shorter than padding-bottom:0. Other properties use literals for raw values.

Sizing

See layout.

.width_{xs5-xl15}
.height_{xs5-xl15}
.width_atmost_{xs-xl} .width_atleast_{xs-xl}
.height_atmost_{xs-xl} .height_atleast_{xs-xl}

Colors

See colors, shading, and typography.

.color_{a-j}_{00-100}
.bg_{a-j}_{00-100}
.accent_{00-100}.positive_{00-100}.negative_{00-100}.caution_{00-100}.info_{00-100}
.bg_accent_{00-100}.bg_positive_{00-100}.bg_negative_{00-100}.bg_caution_{00-100}.bg_info_{00-100}

Palette-letter classes are property-first, and the letter alone implies the palette: .color_a_50, .bg_a_50, .border_a_50, and .outline_a_50 apply --palette_a_50 to their named property, and .shadow_a_50 sets it as the contextual --shadow_color (.border_color_50 is the letterless alpha ramp). A bare intent or neutral scale class applies its family's dominant use: .positive_50 and .text_70 set the text color while .shade_50 sets the background, with the bg_ prefix selecting the background twin (.bg_positive_50).

Color and text classes (.color_a_50, .text_70, etc.) also set --text_color, so nested elements like <code> that use color: var(--text_color) inherit the color properly.

.text_min .text_max .text_{00-100}
.shade_min .shade_max .shade_{00-100}
.darken_{00-100} .lighten_{00-100}

The text_* and shade_* scales are separate because text and backgrounds have different contrast requirements. Use text_* for text colors and shade_* for backgrounds. Both follow "prominence" semantics for light and dark modes: low numbers are subtle, high numbers are strong.

Typography

See typography.

.font_family_sans.font_family_serif.font_family_mono
.font_size_{xs-xl9}
.line_height_{xs-xl}
.icon_size_{xs-xl3}

Borders

See borders.

.border_color_{00-100}
.border_{a-j}_{00-100}
.border_width_{1-9}
.border_radius_{xs3-xl}
.border_top_left_radius_{xs3-xl}
.border_top_right_radius_{xs3-xl}
.border_bottom_left_radius_{xs3-xl}
.border_bottom_right_radius_{xs3-xl}
.outline_width_{1-9}
.outline_width_focus.outline_width_active
.outline_color_{00-100}
.outline_{a-j}_{00-100}

Shadows

See shadows.

.shadow_{xs-xl}
.shadow_top_{xs-xl}
.shadow_bottom_{xs-xl}
.shadow_inset_{xs-xl}
.shadow_inset_top_{xs-xl}
.shadow_inset_bottom_{xs-xl}
.shadow_color_umbra.shadow_color_highlight.shadow_color_glow.shadow_color_shroud
.shadow_{a-j}_{00-100}
.shadow_alpha_{00-100}

Composite classes
#

Composites let you name and reuse patterns, extending the class system with your own vocabulary. They have four forms: raw CSS declarations, compositions of other classes, a combination of both, or full rulesets as an escape hatch for multi-selector patterns (child selectors, sibling combinators, etc.).

Four definition forms

All four of these produce the same CSS output for .centered, with the ruleset form additionally demonstrating child selectors (> * + *) which can't be expressed with the other forms.

import type {CssClassDefinition} from '@fuzdev/fuz_css/css_class_generation.ts';

export const custom_composites: Record<string, CssClassDefinition> = {
	// 1. `declaration` only - custom CSS properties
	centered: {
		declaration: `
			display: flex;
			flex-direction: column;
			align-items: center;
			justify-content: center;
			text-align: center;
		`,
	},

	// 2. `composes` only - compose existing token/composite classes
	centered: {
		composes: ['box', 'text-align:center'],
	},

	// 3. `composes` + `declaration` - compose then extend
	centered: {
		composes: ['box'],
		declaration: 'text-align: center;',
	},

	// 4. `ruleset` - full CSS with multiple selectors (not composable)
	centered: {
		ruleset: `
			.centered {
				display: flex;
				flex-direction: column;
				align-items: center;
				justify-content: center;
				text-align: center;
			}
			/* child selectors, pseudo-classes on children, etc */
			.centered > * + * {
				margin-top: var(--space_md);
			}
		`,
	},
};

Generated CSS:

.centered {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  text-align: center;
}

And the ruleset form (4) includes the additional selector:

.centered > * + * {
  margin-top: var(--space_md);
}

Nesting

Composites can compose other composites, enabling layered abstractions. Resolution is depth-first: nested composes are fully resolved before the parent's declaration is appended. Circular references are detected and produce an error.

What `composes` can reference

The composes property resolves referenced classes and combines their declarations. When both composes and declaration are present, the explicit declaration comes last (winning in the cascade for duplicate properties).

token classes (p_lg, color_a_50) - resolved to their declarations
composites with declaration - the declaration is included
composites with composes - recursively resolved
unmodified CSS literals (text-align:center, margin:0~auto, --my-var:value) - parsed and included as declarations

Not allowed: Composites with ruleset cannot be referenced in composes because they define their own selectors. Modified classes (like hover:opacity:80% or md:p_lg) cannot be used in composes arrays because they require wrapper selectors (apply them directly in markup instead). The composes property merges declarations into a single rule, but multi-selector patterns like .clickable:hover { ... } cannot be inlined. These limitations may be revisited in the future; feedback is welcome in the discussions.

Modifiers

Composites support modifiers like any other class. For composes and declaration composites, declarations are combined and wrapped. For ruleset composites, modifiers are applied to each selector (with smart conflict detection):

<!-- hover:foo resolves foo's `composes`, applies :hover -->
<div class="hover:foo md:dark:foo md:clickable">

Registering composites

Register custom composites with the Vite plugin or Gro generator:

Vite plugin

// vite.config.ts
import {custom_composites} from './src/lib/composites.ts';

vite_plugin_fuz_css({
	class_definitions: custom_composites,
}),

Gro generator

// fuz.gen.css.ts
import {custom_composites} from '#lib/composites.ts';

export const gen = gen_fuz_css({
	class_definitions: custom_composites,
});

See Usage for more details.

Builtin composites

Composable (can be used in composes arrays):

.box - centered flex container
.row - horizontal flex row
.column - vertical flex column
.ellipsis - text overflow ellipsis
.pane - pane container
.panel - panel container
.icon_button - icon button styling
.pixelated - crisp pixel-art rendering
.circular - 50% border-radius
.sized_xs - smallest sizing, cascading to children
.sized_sm - smaller sizing, cascading to children
.sized_md - default sizing, cascade reset
.sized_lg - larger sizing, cascading to children
.sized_xl - largest sizing, cascading to children
.mb_flow - flow-aware margin-bottom
.mt_flow - flow-aware margin-top

Ruleset-based (multi-selector, cannot be used in composes arrays):

.selectable - selectable element styling
.clickable - clickable element styling
.plain - plain/reset styling
.menuitem - menu item styling
.chevron - chevron indicator
.chip - chip/tag styling

Literal classes
#

Fuz supports an open-ended CSS-literal syntax: property:value. Any CSS property and value works, offering arbitrary styles without a DSL.

<!-- basic syntax: property:value -->
<div class="display:flex justify-content:center">

<!-- multi-value properties use ~ for spaces -->
<div class="margin:1px~3rem">

<!-- numeric values -->
<div class="opacity:50% font-weight:700 z-index:100">

<!-- arbitrary CSS values -->
<div class="width:calc(100%~-~20px)">

<!-- custom properties -->
<div class="--foo-bg:#abc">

The ~ character represents a space in class names (since CSS classes can't contain spaces). Use it for multi-value properties like margin:1px~auto.

Custom properties work directly: --my-var:value sets the property on the element. This is useful for scoped variables or passing values to child components.

Modifiers
#

Modifiers prefix any class type (token, composite, or literal) to apply styles conditionally based on viewport, state, or color scheme. This is what makes utility classes more powerful than inline styles.

Responsive modifiers

Mobile-first breakpoints:

Prefix	Width	CSS
`sm:`	40rem (640px)	`@media (width >= 40rem)`
`md:`	48rem (768px)	`@media (width >= 48rem)`
`lg:`	64rem (1024px)	`@media (width >= 64rem)`
`xl:`	80rem (1280px)	`@media (width >= 80rem)`
`2xl:`	96rem (1536px)	`@media (width >= 96rem)`

<!-- stack on mobile, row on medium screens and up -->
<div class="display:flex flex-direction:column md:flex-direction:row">

<!-- hide on mobile -->
<nav class="display:none md:display:flex">

<!-- max-width variant -->
<div class="max-md:display:none">

<!-- arbitrary breakpoints -->
<div class="min-width(800px):color:red max-width(600px):color:blue">

State modifiers

Pseudo-class modifiers for interaction and form states:

<button class="hover:opacity:80% focus:outline-color:blue">
<input class="disabled:opacity:50% invalid:border-color:red">
<li class="first:font-weight:bold odd:background-color:lightgray">

Available state modifiers include:

interaction: hover: focus: focus-visible: focus-within: active: link: visited: any-link: target:
form: autofill: blank: disabled: enabled: checked: indeterminate: required: optional: valid: invalid: user-valid: user-invalid: in-range: out-of-range: placeholder-shown: read-only: read-write: default:
structural: first: last: only: first-of-type: last-of-type: only-of-type: odd: even: empty: nth-child(N): nth-last-child(N): nth-of-type(N): nth-last-of-type(N):
UI states: fullscreen: modal: open: popover-open:
media: playing: paused:

Color-scheme modifiers

Apply styles in dark or light mode:

<div class="shadow_lg dark:shadow_sm">
<div class="color:black light:color:gray">

dark: and light: use :root.dark and :root.light selectors, matching fuz_css's color scheme mechanism.

Pseudo-element modifiers

Style generated content and element parts:

<span class="before:content:'→' before:margin-right:0.5rem">
<input class="placeholder:opacity:50%">

available: before: after: cue: first-letter: first-line: placeholder: selection: marker: file: backdrop:

Note: before: and after: require explicit content - there's no auto-injection. This maintains the 1:1 CSS mapping principle.

Media feature modifiers

Accessibility and context-aware styles:

<div class="motion-reduce:animation:none">
<nav class="print:display:none">

available: print: motion-safe: motion-reduce: contrast-more: contrast-less: portrait: landscape: forced-colors:

Combining modifiers
#

Combined modifiers follow a canonical order enforced with errors that guide you. Multiple states must be alphabetical (focus:hover: not hover:focus:) because both generate equivalent CSS; canonical ordering prevents duplicates.

[media:][ancestor:][...state:][pseudo-element:]class

media - one of md:, lg:, print:, etc
ancestor - one of dark: or light: (likely rtl:/ltr: in the future)
state - any of hover:, focus:, disabled:, etc, sorted alphabetically
pseudo-element - one of before:, after:, placeholder:, etc

<!-- media + ancestor + state -->
<div class="md:dark:hover:opacity:83%">

<!-- media + state + pseudo-element -->
<div class="md:hover:before:opacity:100%">

<!-- multiple states must be alphabetical -->
<button class="focus:hover:outline:2px~solid~blue">

Generated CSS for md:dark:hover:opacity:83%:

@media (width >= 48rem) {
  :root.dark .md\:dark\:hover\:opacity\:83\%:hover {
    opacity: 83%;
  }
}

Builtin classes
#

fuz_css's main stylesheet provides styles for base HTML elements using style variables, acting as a modern CSS reset that adapts to dark mode. It includes CSS classes that provide common generic functionality - these are called builtin classes.

`.unstyled`

Default list (styled):

<ul>
	<li>1</li>
	<li>2</li>
</ul>

1
2

With .unstyled:

<ul class="unstyled">
	<li>a</li>
	<li>b</li>
</ul>

a
b

The .unstyled class lets fuz_css provide solid default element styles with a simple opt-out:

:where(:is(ul, ol, menu):not(.unstyled)) {
	padding-left: var(--space_xl4);
}

This strategy supports semantic hooks for theming:

:where(:is(ul, ol, menu):not(.unstyled)) {
	padding-left: var(--list_padding_left, var(--space_xl4));
}

The :where() selector keeps specificity as low as possible to minimize interference with your styles. It's used throughout the reset stylesheet.

See the specific docs sections for more about .unstyled.

Other builtin classes

.selected - see buttons, forms
.disabled - see forms
.deselectable - see buttons
.inline - see buttons, forms
.heading - see typography
.title - see forms
.row - see layout, forms
.palette_a through .palette_j - see buttons, colors
.dark, .light on :root - see themes

Framework support
#

fuz_css ships two plain CSS files, the base style.css and theme.css, that work with any framework and plain HTML. The utility class generator's detection support varies by framework:

framework	detection	notes
plain HTML	full	static `class="..."` attributes, script variables
Svelte	full	all patterns including `class:` directives and array/object syntax
React / JSX	full	with `acorn-jsx` plugin - `className`
Preact	full	with `acorn-jsx` plugin - `class`
Solid	full	with `acorn-jsx` plugin - `class`, `classList`
Vue JSX	full	with `acorn-jsx` plugin - `class`
Vue SFC, Angular, etc.	none	template syntax not parsed; use `clsx`/`cx`/`cn` in JS/TS

The additional_classes plugin config option is an escape hatch for classes that can't be statically detected. Acorn plugins can be added via acorn_plugins for additional syntax support like JSX.

Out of the box, class generation works only with TypeScript/JS, Svelte, and JSX. Angular is not supported; Vue JSX is supported but their recommended SFC format is not. We could revisit this if there's demand.

Svelte-first
#

The extractor parses and analyzes the AST to understand Svelte's class syntax. Supported constructs:

attributes: class="...", class={[...]}, class={{...}} (identifier and string-literal keys), class:name
expressions: logical (&&, ||, ??), ternaries, template literals (complete tokens only - `color_a_50 ${base}` extracts color_a_50, but `color_${hue}_50` cannot be extracted; use @fuz-classes or additional_classes)
Svelte 5 runes: $derived() and $derived.by() for class variables
utility calls: clsx(), cn(), cx(), classNames() with nested arrays, objects, and utility calls
scripts: both <script> and <script module>, with naming convention and usage tracking

React and JSX
#

To enable JSX support for React, Preact, Solid, etc, install acorn-jsx and pass it to the plugin or generator:

npm i -D acorn-jsx

Vite plugin

// vite.config.ts
import {defineConfig} from 'vite';
import jsx from 'acorn-jsx';
import {vite_plugin_fuz_css} from '@fuzdev/fuz_css/vite_plugin_fuz_css.ts';

export default defineConfig({
  plugins: [
    vite_plugin_fuz_css({
      acorn_plugins: [jsx()],
    }),
  ],
});

Gro generator

// fuz.gen.css.ts
import {gen_fuz_css} from '@fuzdev/fuz_css/gen_fuz_css.ts';
import jsx from 'acorn-jsx';

export const gen = gen_fuz_css({
	acorn_plugins: [jsx()],
});

Supported JSX patterns:

className="..." and class="..." - static strings
className={clsx(...)} - utility function calls
className={cond ? "a" : "b"} - ternary and logical expressions
classList={{active: cond}} - Solid's classList
usage tracking: variables in className, class, and classList are tracked back to their definitions (has limitations, room for improvement)

// variable tracking works in JSX too
const styles = 'box hover:shadow_lg';
const Component = () => <div className={styles} />;

The acorn_plugins option accepts any Acorn-compatible plugin, so other syntax extensions can be supported the same way.

Custom interpreters
#

Interpreters dynamically generate CSS for class names that aren't in the static definitions (which can be extended via class_definitions or replaced with include_default_classes: false). The default CSS-literal syntax and modifier support are both implemented as interpreters, which you can extend or replace.

For advanced use cases, you can define custom interpreters that generate CSS from arbitrary class name patterns. This is similar to UnoCSS's dynamic rules, which also use regex + function patterns. An interpreter has a regex pattern and an interpret function that returns CSS (or null to pass):

import type {CssClassDefinitionInterpreter} from '@fuzdev/fuz_css/css_class_generation.ts';

// Example: grid-cols-N classes like "grid-cols-4"
// Unlike composites, interpreters can parameterize values
const grid_cols_interpreter: CssClassDefinitionInterpreter = {
  pattern: /^grid-cols-(\d+)$/,
  interpret: (matched) => {
    const n = parseInt(matched[1]!, 10);
    if (n < 1 || n > 24) return null;
    return `.grid-cols-${n} { grid-template-columns: repeat(${n}, minmax(0, 1fr)); }`;
  },
};

This generates grid-cols-1 through grid-cols-24 on-demand, something that would require 24 separate composite definitions. Note the classes for this example could also be created as composites with a helper function - fuz_css uses this strategy internally to create its token classes in css_class_definitions.ts.

Register with the Vite plugin or Gro generator:

import {css_class_interpreters} from '@fuzdev/fuz_css/css_class_interpreters.ts';

vite_plugin_fuz_css({
  class_interpreters: [grid_cols_interpreter, ...css_class_interpreters],
})

The interpreter context provides access to class_definitions, css_properties (for validation), and diagnostics (for errors/warnings). This enables full programmatic control over class-to-CSS generation.

Custom interpreters replace the defaults entirely, so include ...css_class_interpreters to preserve CSS-literal and modified-class support. This area is experimental and the API may change.

Compared to alternatives
#

TailwindCSS and UnoCSS are utility-first frameworks where classes have primacy. fuz_css is semantic-first: utilities complement HTML defaults rather than being the primary styling mechanism.

	TailwindCSS	UnoCSS	fuz_css
primary syntax	DSL-first	config-first	token DSL + CSS literals
multi-property	`@apply`, plugins	shortcuts	composites
arbitrary values	DSL (`bg-[#abc]`)	any (presets)	CSS syntax (`background:#abc`)
detection	regex	regex	AST (more capable, slower)
token source	CSS (`@theme`)	JS/TS config	TS variables (importable)
extensibility	plugins	rules, variants, presets	interpreters

fuz_css's modifier system is less expressive than TailwindCSS's variants. Missing: parent/sibling/descendant state (group-hover:, peer-invalid:, has-checked:), arbitrary variants ([&.is-dragging]:), child selectors (*:), container queries (@md:), data/ARIA variants, and more. When you need these patterns, fuz_css currently expects you to use rulesets or <style> tags, but the API is still a work in progress, and a more powerful and potentially more TailwindCSS-aligned system is on the table.

For extensibility, all three frameworks allow custom class-to-CSS mappings. UnoCSS's dynamic rules use regex + function patterns similar to fuz_css interpreters, plus separate variants for modifiers. TailwindCSS uses JS plugins and UnoCSS has the more mature extensibility story; fuz_css offers comparable power with interpreters but it's still evolving - feedback is welcome!

fuz_css fits best when you prefer semantic HTML with styled defaults. Design tokens are defined in TypeScript, naturally adapt to dark mode, and can be imported in TS for typesafe runtime access. The tradeoffs include a more limited DSL and more verbose literal syntax, which nudges you toward <style> tags, tokens when appropriate, or composites for repeated patterns.

fuz_css is still early in development. Your input and feedback is appreciated in the GitHub issues for bugs and discussions for everything else.

colors #

fuz_css's colors are derived: a handful of high-leverage knobs produce every color variables in pure CSS, in the oklch colorspace, adapting to the color-scheme automatically. OKLCH lightness is perceptually uniform (equal lightness reads equally light in every hue), so rotating a hue knob is safe: contrast and visual weight hold.

Hues use letters so themes can reassign colors without breaking semantics ("a" is blue by default but could be any color). Meaning attaches through the intent knobs layered on top: --hue_accent (links, focus, selection, selected states - what other systems call "primary") defaults to --hue_a, --hue_negative to --hue_c, and so on. Retarget an intent to move just that meaning; rotate a letter to move the palette.

Hue variables
#

Hue variables contain a single OKLCH hue angle. Because lightness and chroma are shared across all hues at each stop, the scales are interchangeable: setting a hue alone is enough, no per-hue tuning required. The one deliberate exception is the per-slot chroma multiplier - the brown slot ships muted because no hue angle renders brown at full palette chroma.

Hue variables are also useful to construct custom colors not covered by the palette. For example, fuz_css's selection color derives from --hue_accent (try selecting some text - same hue!).

Hue variables are the same in both light and dark modes (non-adaptive).

250
blue · default accent
144
green · default positive
29
red · default negative
296
purple
98
yellow
60
brown · default neutral
358
pink
41
orange · default caution
210
cyan · default info
180
teal

Palette variables
#

Each hue has intensity variants from subtle to bold (00, 05, 10, 20, ..., 80, 90, 95, 100), with 50 at the middle of the ramp. The 60 variant is the text-safe stop: links, the labels of .palette_X buttons and chips, and a selected .palette_X button's fill use it, and check_theme gates those pairings at AA.

Palette variables work for both text and backgrounds through utility classes: .color_a_50 sets the text color and .bg_a_50 the background, and the intent scales below do the same. The shade and text scales are split by role instead, one for surfaces and one for text.

Palette stops are adaptive: they switch between light and dark ramps based on color scheme. There are no absolute variants; for a color that doesn't adapt, write the literal color or define one custom property.

Intent variables
#

Intent scales name colors by meaning: --accent_NN, --positive_NN, --negative_NN, --caution_NN, and --info_NN, with the palette's stops, derived through the same ramps from each intent's hue knob (--hue_accent and the rest). Each hue binds to a palette letter by default, so an intent scale matches its letter's until a theme rebinds it: accent → a, positive → b, negative → c, caution → h, info → i.

Reach for an intent when the color carries meaning, like an error or a success, and for a letter when it's only a color, so a theme can move the meaning without recoloring every use of the letter. The classes follow the palette's: .positive_50 sets the text color and .bg_positive_50 the background. Border, outline, and shadow classes exist only for the letters, so reach an intent there with a literal like border-color:var(--negative_50).

Color knobs
#

The knobs are the theme API, and the first few carry most themes:

intent hues - --hue_accent, --hue_positive, --hue_negative, --hue_caution, --hue_info - each pointing a meaning at a palette letter (var(--hue_c)) or a literal angle, and deriving its full stop scale (--accent_00 … --accent_100)
--hue_neutral + --neutral_chroma - the temperature and strength of every surface, text, border, and shadow tint (the neutral intent, whose scales are the shade and text ramps)
--chroma_scale - one multiplier from grayscale (0) through calm (1) to vivid (above 1, deliberately clipping the weakest hues)
lightness ramps - --palette_lightness_00/_100/_curve (and the same trio for shade_ and text_): the endpoint stops plus a curve exponent bending the ramp between them, per color scheme
chroma curve - --palette_chroma_min/_max and --chroma_curve: a mid-peaked curve, clamped per stop by gamut caps computed from the worst hue
per-slot chroma multipliers - --palette_a_chroma_scale … --palette_j_chroma_scale and intent twins (--accent_chroma_scale, …), each multiplying one slot's chroma under --chroma_scale. A binding shares only the hue angle, so an intent bound to the muted brown slot needs its twin set too, and validate_theme warns when it isn't
--hue_a … --hue_j - the palette letters' angles. Rotating one recolors every use of that letter, so registered themes leave them alone and move intents instead

Every intermediate value these produce is also its own variable (--palette_lightness_30, --palette_chroma_50, …), so a theme can pin any individual stop as an escape hatch.

// a warm, slightly vivid theme in three moves
const warm_theme: Theme = {
	name: 'warm',
	variables: [
		{name: 'hue_neutral', light: '55'},
		{name: 'neutral_chroma', light: '0.03'},
		{name: 'chroma_scale', light: '1.15'},
	],
};

shading #

fuz_css offers a shading model built on adaptive style variables that respond to the color-scheme. Adaptive means the underlying values change between light and dark modes to maintain consistent prominence: low numbers stay subtle, high numbers stay strong. Each theme can implement light mode, dark mode, or both.

Light mode's starting point is plain white documents (like paper) where we subtract light to create contrast and shape. Black shadows on white make natural sense; white glows are near invisible.

Dark mode's starting point is a lightless void where we add light. Elements emit light to fill the darkness. White glows make natural sense; black shadows are near invisible.

The shade scale
#

The shade scale is the primary system for backgrounds and surfaces. All numbered shades (shade_00 through shade_100) are tinted using the theme's hue_neutral and neutral_chroma for visual cohesion. The scale also includes two untinted extremes (shade_min and shade_max) for maximum contrast needs.

Key values
#

shade_min: untinted surface-side extreme (white in light mode, black in dark mode); used for input backgrounds
shade_00: the base background
shade_05: very subtle: hover states on surface, code backgrounds
shade_10: subtle elevation: panels, cards, aside
shade_20: more elevated: active/pressed states
shade_30: default border intensity
shade_100: maximum tinted contrast
shade_max: untinted contrast-side extreme: black in light mode, white in dark mode; rarely needed

Adaptive alpha overlays (fg/bg)
#

The fg and bg variables provide alpha-based overlays that adapt to the color scheme. Unlike the opaque shade scale, these stack when nested and are used by composites like .panel and .chip.

--fg_NN (foreground direction) - darkens in light mode, lightens in dark mode; use for elevated surfaces like panels, cards, and hover states
--bg_NN (background direction) - lightens in light mode, darkens in dark mode; use for surfaces that blend toward the background

In light mode, fg is the same as darken and bg is the same as lighten. In dark mode, they're swapped.

The overlays are variables, not token classes - bg_ is the opaque background class prefix (.bg_a_50, .bg_positive_50), so reach the overlays with a literal class (background-color:var(--fg_10)) or a <style> block.

fg (toward foreground)
#

Adaptive alpha overlays that add contrast with the surface.

bg (toward background)
#

Adaptive alpha overlays that reduce contrast with the surface.

Stacking behavior
#

Unlike the opaque shade scale, alpha overlays stack when nested. Each layer adds more contrast:

<div class="background-color:var(--fg_10) p_sm">
	<div class="background-color:var(--fg_10) p_sm">
		<div class="background-color:var(--fg_10) p_sm">
			<div class="background-color:var(--fg_10) p_sm">
				...
			</div>
		</div>
	</div>
</div>

var(--fg_10)

nested var(--fg_10)

triple nested

quadruple nested

This is useful for nested UI elements like cards within cards, or hover states inside elevated containers. Composites like .panel, .chip, and .menuitem use var(--fg_10) for this stacking behavior.

Darken/lighten alpha overlays
#

The non-adaptive darken_NN and lighten_NN variables provide consistent darkening or lightening regardless of color scheme. These are the underlying primitives that fg and bg reference.

Darken
#

Alpha overlays that always add black.

Lighten
#

Alpha overlays that always add white.

Visual balance
#

Both scales are tuned for visual balance, not mathematical spacing: 0%, 3%, 6%, 12%, 21%, 32%, 45%, 65%, 80%, 89%, 96%, 98%, 100%. This provides visually even steps across the range.

When to use which
#

Use --fg_NN when you need stacking behavior or are building nested UI:

/* elevated panel (stacks when nested) */
background-color: var(--fg_10);

/* hover state (stacks on any background) */
background-color: var(--fg_10);

/* active/pressed state */
background-color: var(--fg_20);

Use shade_NN when you need explicit, predictable opaque surfaces:

/* base page background */
background-color: var(--shade_00);

/* opaque border */
border-color: var(--shade_30);

/* input backgrounds (untinted for contrast) */
background-color: var(--shade_min);

The composites (.panel, .chip, .menuitem) use --fg_NN for stacking. The page background uses shade_00 as the opaque base.

Text colors
#

For text colors, see the text scale (text_00 through text_100). Both scales use the same "prominence" semantics for light and dark modes: low numbers are subtle, high numbers are strong. They're separate scales because text and backgrounds have different contrast requirements.

buttons #

The <button> element is styled by default without adding classes. Classes like .selected and .plain and .palette_a modify the base style.

Buttons have a .selected state that can be used for various UI purposes, like showing a selected item in a menu or a styling button's aria-pressed state. Instead of having two distinct styles of buttons with outlined and filled variants, fuz_css makes outlined buttons the default, and selected buttons are filled. There's also the .deselectable modifier class for buttons that remain clickable when selected. Themes can customize this behavior.

<button>a button</button>

Colorful buttons
#

<button class="palette_a">

<button class="palette_b">

<button class="palette_c">

<button class="palette_d">

<button class="palette_e">

<button class="palette_f">

<button class="palette_g">

<button class="palette_h">

<button class="palette_i">

<button class="palette_j">

With disabled attribute
#

<button disabled>
	:|
</button>

With `.selected`
#

<button class="selected">...</button>

.selected buttons with .deselectable continue to be clickable when selected:

<button class="selected deselectable">
	...
</button>

With `.plain` and `.icon_button`
#

<button class="plain">
	+
</button>

<button class="icon_button">
	+
</button>

<button class="plain icon_button">
	+
</button>

`.selected` variants

.plain strips the fill, border, and shadow from unselected buttons at rest (the fill and shadow return on hover), so a selected plain button looks like any other selected button.

<button class="plain selected">
	+
</button>

<button class="icon_button selected">
	+
</button>

<button class="plain icon_button selected">
	+
</button>

`.selected` and `.deselectable` variants

<button class="plain selected deselectable">
	+
</button>

<button class="icon_button selected deselectable">
	+
</button>

<button class="plain icon_button selected deselectable">
	+
</button>

Size composites
#

The size composite classes .sized_xs, .sized_sm, .sized_md, .sized_lg, and .sized_xl scale buttons up and down by overriding custom properties for font, height, and padding.

<button class="sized_xs">sized_xs</button>
<button class="sized_sm">sized_sm</button>
<button class="sized_md">sized_md</button>
<button class="sized_lg">sized_lg</button>
<button class="sized_xl">sized_xl</button>

They compose with other classes like .plain and .icon_button:

Set on a container and children inherit the sizing:

<div class="sized_xs">...</div>

chips #

The .chip class creates a small inline label or tag, useful for displaying metadata, categories, or status indicators. Chips work on any element but are commonly used with <span> and <a>.

Chips have color variants (.palette_a through .palette_j) that tint both the text and background. Links (a.chip) have slightly bolder text.

<span class="chip">a chip</span> a chip

<a class="chip">a link chip</a> a link chip

Colorful chips
#

<span class="chip palette_a"> .chip.palette_a a.chip.palette_a

<span class="chip palette_b"> .chip.palette_b a.chip.palette_b

<span class="chip palette_c"> .chip.palette_c a.chip.palette_c

<span class="chip palette_d"> .chip.palette_d a.chip.palette_d

<span class="chip palette_e"> .chip.palette_e a.chip.palette_e

<span class="chip palette_f"> .chip.palette_f a.chip.palette_f

<span class="chip palette_g"> .chip.palette_g a.chip.palette_g

<span class="chip palette_h"> .chip.palette_h a.chip.palette_h

<span class="chip palette_i"> .chip.palette_i a.chip.palette_i

<span class="chip palette_j"> .chip.palette_j a.chip.palette_j

Size composites
#

The size composite classes .sized_xs, .sized_sm, .sized_md, .sized_lg, and .sized_xl scale chips up and down, adjusting font and padding.

<span class="chip sized_xs">sized_xs</span>
<span class="chip sized_sm">sized_sm</span>
<span class="chip sized_md">sized_md</span>
<span class="chip sized_lg">sized_lg</span>
<span class="chip sized_xl">sized_xl</span>

sized_xs sized_sm sized_md sized_lg sized_xl

Set on a container and children inherit the sizing:

<div class="sized_xs">...</div>

one two three

Without a size context - a size composite, a font_size_* class, or a heading - a chip keeps its element's own size, so <small class="chip"> stays small:

<span class="chip">span.chip</span>
<small class="chip">small.chip</small>

span.chip small.chip

elements #

fuz_css applies default styles to semantic HTML elements in its reset stylesheet. The styles use variables and include appropriate spacing, so plain HTML gets user-friendly styling and theme integration automatically. The defaults are low specificity using :where so they're easy to override, and you can opt out by adding .unstyled to an element.

p
#

Paragraph elements are unstyled except for spacing. Divs are totally unstyled.

p

div

p

This paragraph has no bottom margin because default spacing is omitted for the :last-child of all otherwise-spaced elements, streamlining the common case. This has some unfortunate edge cases that can usually be solved by adding .mb_lg. Coupling markup structure to styles like this may be something we change, feedback is welcome.

a
#

a link

a link with .selected

a link with .unstyled

code
#

code

code with .unstyled

pre
#

a pre is
  preformatted
					text

details and summary
#

Click this summary to see the rest of the details

The children of the details excluding the summary.

<details>
	<summary>
		Click this <code>summary</code>
		to see the rest of the <code>details</code>
	</summary>
	<p>The children of the <code>details</code> excluding the <code>summary</code>.</p>
	<Code code={'...'} />
</details>

details and summary with .unstyled

unstyled details content

blockquote
#

blockquote

blockquote with .unstyled

aside
#

the aside looks like this

<aside>
	<aside>
		<aside>nested asides</aside>
	</aside>
</aside>

aside with .unstyled

hr
#

header
#

<header>header</header>

header

footer
#

<footer>footer</footer>

section
#

<section>section</section>

Sections have a bottom margin, except for the last in the list.

section

`ul`
#

a
b
see

`ul` with `.unstyled`

a
b
see

`ol`
#

one
two
etc

`ol` with `.unstyled`

one
two
etc

`menu`
#

1

2

3

`menu` with `.unstyled`

1

2

3

table
#

<table>
	<thead>
		<tr>
			<th>th</th>
			<th>th</th>
			<th>th</th>
		</tr>
	</thead>
	<tbody>
		<tr><td>td</td><td>td</td><td>td</td></tr>
		<tr><td>td</td><td>td</td><td>td</td></tr>
		<tr><td>td</td><td>td</td><td>td</td></tr>
	</tbody>
</table>

th	th	th
td	td	td
td	td	td
td	td	td

<table class="width:100%">
	...
</table>

th	th	th
td	td	td
td	td	td
td	td	td

TODO more!

forms #

Form elements have basic default styles that can be omitted with .unstyled.

form with a fieldset
#

<form>
	<fieldset>
		<legend>
			a <MdnLink path="Web/HTML/Element/legend" />
		</legend>
		<label>
			<div class="title">
				username
			</div>
			<input
				bind:value={username}
				placeholder=">"
			/>
		</label>
		...
	</fieldset>
	...
</form>

`form` with range input
#

`form` with checkboxes
#

The above are wrapped with: <label class="row"> with .disabled as needed: <label class="row disabled">

`form` with radio inputs
#

Size composites
#

The size composite classes .sized_xs, .sized_sm, .sized_md, .sized_lg, and .sized_xl scale inputs and buttons, adjusting height and padding. Apply directly or on a container to cascade to children.

<input class="sized_xs" />
<input class="sized_sm" />
<input />
<input class="sized_lg" />
<input class="sized_xl" />

Set on a container and children inherit the sizing:

<form class="sized_xs">...</form>

typography #

h1

paragraph

h2

paragraph

h3

paragraph

h4

paragraph

h5

paragraph

h6

paragraphs

p with some small text

p _sub p ^sup p

show code

Font families
#

These three are the stacks, and each keeps meaning what it says. Body text renders in --font_family (default var(--font_family_sans)), so a theme that wants serif or mono body text retargets it rather than redefining a stack. Headings take --heading_font_family (default var(--font_family_serif)), so "one family everywhere" is deliberately two knobs, and --heading_letter_spacing (default normal) sets their tracking, where an em value follows each heading's size.

=

Font sizes
#

Two knobs set the sizes. --font_size_scale multiplies every size, body text (md) and the smaller sizes included, so a theme can enlarge reading text while small text keeps its proportion to it. The sizes above md also step by one ratio, --type_scale_ratio, which flattens or opens up the whole heading hierarchy without moving body text.

=

Font weights
#

Font weight values can be any integer from 1 to 1000.

There are no variables for font-weight but there are utility classes.

.font-weight:100

.font-weight:200

.font-weight:300

.font-weight:400

.font-weight:500

.font-weight:600

.font-weight:700

.font-weight:800

.font-weight:900

.font-weight:950

.font-weight:234

.font-weight:555

.font-weight:997

Text colors
#

The text scale (text_00 through text_100) provides tinted neutral colors optimized for text legibility. The scale uses "prominence" semantics for light and dark modes: low numbers are subtle, high numbers are strong. This matches the shade scale pattern.

text_00 - surface-side endpoint: essentially invisible on surface
text_10-text_30 - very subtle/faint text: watermarks, hints
text_50 - disabled text: text_disabled
text_80 - default body text: --text_color
text_90-text_100 - high emphasis/headings
text_min/text_max - knockout text (pure white/black without tint)

The text scale is separate from the shade scale because text and backgrounds have different contrast requirements. Use text_* for text colors and shade_* for backgrounds. For colored text, use color_a_50 etc.

=

Line heights
#

Icon sizes
#

unlike --font_size_ variables, --icon_ variables are in px not rem, so they're insensitive to browser font size

= 18px

🐢

= 32px

🐢

= 48px

🐢

= 80px

🐢

= 128px

🐢

= 192px

🐢

= 256px

🐢

Size composites
#

The size composite classes .sized_xs, .sized_sm, .sized_md, .sized_lg, and .sized_xl set --flow_margin, scaling the vertical spacing between flow elements and headings. Apply on a container to cascade to children.

<div class="sized_lg">
	<h3>heading</h3>
	<p>paragraph</p>
	<p>paragraph</p>
</div>