setup #

The Vite plugin is the recommended setup. It generates one stylesheet holding the theme variables, the base styles for the elements you use, and the utility classes you use, and it updates with HMR as you edit. It works with SvelteKit, Svelte, React, Preact, Solid, and plain HTML/TS/JS. Without a build step, link the package's two plain stylesheets instead.

Working setups for each framework live in the repo's examples.

Import the virtual module once, from the root layout:

JSX needs a parser plugin, which you install yourself: acorn-jsx, passed through the acorn_plugins option.

Preact is the same with @preact/preset-vite. For Solid, list the fuz_css plugin before solid(), as the Solid example does:

Then import the virtual module in your entry file:

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, within one file

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

Svelte and plain HTML/TS/JS need no parser plugin. With the Svelte plugin outside SvelteKit, list the fuz_css plugin first, as the Svelte example does:

The package ships two plain stylesheets, the base style.css and theme.css with every variable, which work in any page, and jsDelivr serves them from npm:

That's the full semantic styling and every style variable, including the builtin classes like selected and palette_a. Utility classes need the plugin, since they're generated from your source, and so does baking a theme in; without it, write the variables into your own CSS. Pin a version in the URL so a release can't change your page.

Declare the virtual module once, in a dedicated declaration file like src/fuz_css.d.ts (not a SvelteKit app.d.ts, which is a module):

The virtual:fuz.css import alone is all most projects need. Projects managing their own theme or base styles can turn the generated ones off and import the full stylesheets, so neither layer ships twice:

Every rem length on the page is measured against that root, including ones that come from elsewhere: a third-party component sized for a 16px rem renders at 62.5% of what its author intended. Size your own lengths with the style variables, and check any rem-based CSS you bring in. A @media query is the exception, since its rem is the browser's initial font size: the sm: breakpoint's 40rem is 640px.

Coming from Tailwind, whose spacing scale assumes a 16px rem (p-4 is 1rem, 16px): here 16px is 1.6rem, and the spacing tokens like p_lg carry the scale, so pasted Tailwind lengths come out smaller.

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. List it after any plugin that rewrites CSS in its transform hook.

• 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). A callback receives the defaults and returns the whole set, so () => my_definitions uses only your own
• class_interpreters - custom interpreters for dynamic class generation; an array replaces the default interpreters, and a callback receives them and returns the ones to use (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 (CI set to anything but empty, false, or 0), '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, the plugins, and the installed versions of fuz_css and its parsers
• 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 theme 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

The stylesheets work with any framework and plain HTML. The utility class generator's detection support varies by framework:

The additional_classes option is an escape hatch for classes that can't be statically detected. Angular and Vue's single-file components aren't supported; we could revisit this if there's demand.