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.

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}

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.

• .color_{a-j}_{1-9}
• .bg .fg
• .bg_{1-9} .fg_{1-9}
• .bg_{a-j}_{1-9}
• .text_color_{0-10}
• .color_bg .color_fg
• .color_bg_{1-9} .color_fg_{1-9}
• .darken_{1-9} .lighten_{1-9}
• .color_darken_{1-9} .color_lighten_{1-9}
• .hue_{a-j}

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_{1-5}
• .border_color_{a-j}
• .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_{1-5}
• .outline_color_{a-j}

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_{a-j}
• .shadow_color_highlight.shadow_color_glow.shadow_color_shroud
• .shadow_alpha_{1-5}

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.

Generated CSS:

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

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_5) - 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):

Registering composites

Register custom composites with the Vite plugin or Gro generator:

Vite plugin

Gro generator

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

Ruleset-based (multi-selector, apply directly in markup):

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

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

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.

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.

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

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

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.

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

The plugin extracts classes from files as Vite processes them, including from node_modules dependencies. It supports HMR -- changes to classes in your code trigger automatic CSS updates.

Plugin options

• acorn_plugins - required for JSX frameworks, e.g. acorn-jsx
• include_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_definitions - 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) 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

TypeScript setup

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

For projects using Gro, create a *.gen.css.ts file anywhere in src/:

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

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

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:

3. Usage tracking

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

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:

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

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

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_5 ${base}` extracts color_a_5, but `color_${hue}_5` cannot be extracted; use @fuz-classes or include_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

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

Vite plugin

Gro generator

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)

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