fuz_css - API docs - @fuzdev stack

readonly ["00", "05", "10", "20", "30", "40", "50", "60", "70", "80", "90", "95", "100"] import {alpha_variants} from '@fuzdev/fuz_css/variable_data.js';

AlphaVariant
#

"00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100" import type {AlphaVariant} from '@fuzdev/fuz_css/variable_data.js';

ANCESTOR_MODIFIERS
#

Map<string, ModifierDefinition> import {ANCESTOR_MODIFIERS} from '@fuzdev/fuz_css/modifiers.js';

Map of ancestor modifier names to their CSS output

arrayClasses
#

string[] import {arrayClasses} from '@fuzdev/fuz_css/example_class_utilities.js';

Array - all elements extracted

background_image
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {background_image} from '@fuzdev/fuz_css/variables.js';

BaseCssOption
#

BaseCssOption import type {BaseCssOption} from '@fuzdev/fuz_css/css_plugin_options.js';

Type for the base_css option used by CSS generators.

Supports four forms:

undefined - Use default style.css (framework defaults)
null - Disable base styles entirely (explicit opt-out)
string - Custom CSS to replace defaults
(default_css) => string - Callback to modify default CSS

See module documentation for the undefined vs null convention.

BaseDiagnostic
#

BaseDiagnostic import type {BaseDiagnostic} from '@fuzdev/fuz_css/diagnostics.js';

Base diagnostic with common fields.

`level`

type 'error' | 'warning'

`message`

type string

(definitions: Record<string, CssClassDefinition | undefined>): CssClassVariableIndex import {build_class_variable_index} from '@fuzdev/fuz_css/class_variable_index.js';

Builds an index of CSS variables used by each class definition.

`definitions`

CSS class definitions to index

type Record<string, CssClassDefinition | undefined>

returns

CssClassVariableIndex

CssClassVariableIndex with variable lookups

build_variable_graph
#

(variables: { name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; }[], content_hash: string): VariableDependencyGraph

import {build_variable_graph} from '@fuzdev/fuz_css/variable_graph.js';

Builds a dependency graph from an array of style variables.

`variables`

array of StyleVariable objects

type { name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; }[]

`content_hash`

hash of the source for cache invalidation

type string

returns

VariableDependencyGraph

VariableDependencyGraph

build_variable_graph_from_options
#

bundled_resources.ts view source

(variables: VariablesOption): VariableDependencyGraph import {build_variable_graph_from_options} from '@fuzdev/fuz_css/variable_graph.js';

Builds a variable dependency graph from a variables option. Handles all option forms: undefined (defaults), null (disabled), array, or callback.

`variables`

the variables option from generator config

type VariablesOption

returns

VariableDependencyGraph

VariableDependencyGraph built from the resolved variables

BundledCssResources
#

BundledCssResources import type {BundledCssResources} from '@fuzdev/fuz_css/bundled_resources.js';

Bundled CSS resources needed to emit base styles and theme variables. Build via create_bundled_resources; pass null for utility-only output.

button_shadow
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {button_shadow} from '@fuzdev/fuz_css/variables.js';

button_shadow_active
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {button_shadow_active} from '@fuzdev/fuz_css/variables.js';

button_shadow_hover
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {button_shadow_hover} from '@fuzdev/fuz_css/variables.js';

CacheDeps
#

deps.ts view source

CacheDeps import type {CacheDeps} from '@fuzdev/fuz_css/deps.js';

Cache-related file system deps. Abstracted to enable test isolation from the actual filesystem.

Named CacheDeps (not FsDeps) because it only covers the specific deps needed for cache management, not general filesystem access.

`read_text`

Reads a text file. Returns a not_found error if the file doesn't exist.

type (options: {path: string}) => Promise<Result<{value: string}, FsError>>

`write_text_atomic`

Writes a text file atomically (temp file + rename for crash safety). Creates parent directories if they don't exist.

type (options: {path: string; content: string}) => Promise<Result<object, FsError>>

`unlink`

Removes a file. Returns a not_found error if the file doesn't exist — callers that want rm -f semantics should ignore that kind explicitly.

type (options: {path: string}) => Promise<Result<object, FsError>>

CachedExtraction
#

`chroma_min`

Chroma requested at the ramp endpoints (stops 00/100), before capping.

type number

`chroma_max`

Chroma requested at the ramp midpoint (stop 50), before capping.

type number

`curve`

Falloff exponent of the peak; higher concentrates chroma at the middle.

type number

ClassTemplateFn
#

ClassTemplateFn<T1, T2, T3> import type {ClassTemplateFn} from '@fuzdev/fuz_css/css_class_generators.js';

generics

ClassTemplateFn<T1 = string, T2 = string, T3 = string>

`T1`

default string

`T2`

default string

`T3`

default string

collect_class_variables
#

(index: CssClassVariableIndex, class_names: Iterable<string>): Set<string> import {collect_class_variables} from '@fuzdev/fuz_css/class_variable_index.js';

Collects all variables used by a set of classes.

`index`

the class variable index

type CssClassVariableIndex

`class_names`

class names to collect variables from

type Iterable<string>

returns

Set<string>

set of all variable names used by the classes

collect_rule_variables
#

(index: StyleRuleIndex, included_indices: Set<number>): Set<string> import {collect_rule_variables} from '@fuzdev/fuz_css/style_rule_parser.js';

Collects all CSS variables used by the included rules.

`index`

the StyleRuleIndex

type StyleRuleIndex

`included_indices`

set of rule indices to include

type Set<number>

returns

Set<string>

set of variable names (without -- prefix)

color_scheme_variants
#

readonly ["light", "dark"] import {color_scheme_variants} from '@fuzdev/fuz_css/variable_data.js';

color_schemes
#

ColorScheme[] import {color_schemes} from '@fuzdev/fuz_css/theme.js';

ColorScheme
#

ColorScheme import type {ColorScheme} from '@fuzdev/fuz_css/theme.js';

ColorSchemeVariant
#

"light" | "dark" import type {ColorSchemeVariant} from '@fuzdev/fuz_css/variable_data.js';

CoreReason
#

CoreReason import type {CoreReason} from '@fuzdev/fuz_css/style_rule_parser.js';

Reasons a rule is considered "core" and always included.

CoreStyleRule
#

bundled_resources.ts view source

CoreStyleRule import type {CoreStyleRule} from '@fuzdev/fuz_css/style_rule_parser.js';

A core style rule that is always included in output.

inheritance

extends: StyleRuleBase

`is_core`

type true

`core_reason`

type CoreReason

create_bundled_resources
#

(options: CreateBundledResourcesOptions): Promise<BundledCssResources> import {create_bundled_resources} from '@fuzdev/fuz_css/bundled_resources.js';

Builds the bundled CSS resources from generator options. The style.css index is always built (even when only theme output is enabled), matching the generators' prior behavior.

`options`

type CreateBundledResourcesOptions

returns

Promise<BundledCssResources>

create_generation_diagnostic
#

(diagnostic: InterpreterDiagnostic, locations: SourceLocation[] | null): GenerationDiagnostic import {create_generation_diagnostic} from '@fuzdev/fuz_css/diagnostics.js';

Converts an InterpreterDiagnostic to a GenerationDiagnostic with locations.

`diagnostic`

interpreter diagnostic to convert

type InterpreterDiagnostic

`locations`

source locations where the class was used

type SourceLocation[] | null

returns

GenerationDiagnostic

create_style_rule_index
#

bundled_resources.ts view source

(css: string): StyleRuleIndex import {create_style_rule_index} from '@fuzdev/fuz_css/style_rule_parser.js';

Creates a StyleRuleIndex from a custom CSS string. Use this to parse user-provided base styles instead of loading from file.

`css`

raw CSS string to parse

type string

returns

StyleRuleIndex

StyleRuleIndex

CreateBundledResourcesOptions
#

CreateBundledResourcesOptions import type {CreateBundledResourcesOptions} from '@fuzdev/fuz_css/bundled_resources.js';

`base_css`

Base CSS source: custom string, callback over the default, or default.

type BaseCssOption

`variables`

Theme variables source.

type VariablesOption

`class_definitions`

Merged class definitions, indexed to their referenced variables.

type Record<string, CssClassDefinition | undefined>

`deps`

Filesystem deps for loading the default style.css.

type CacheDeps

CSS_CACHE_VERSION
#

css_class_composites.ts view source

6 import {CSS_CACHE_VERSION} from '@fuzdev/fuz_css/css_cache.js';

CSS cache version. Bump when any of these change:

CachedExtraction schema
extract_css_classes_with_locations() logic or output
ExtractionDiagnostic or SourceLocation structure

v1: Initial version with classes and diagnostics v2: Use null instead of empty arrays, add explicit_classes, elements, css_variables. v3: Add explicit_elements, explicit_variables for @fuz-elements/@fuz-variables comments. v4: Filter incomplete CSS variables in dynamic templates (e.g., var(--prefix_{expr})). v5: Remove css_variables and explicit_variables (now detected via simple regex scan). v6: Re-add explicit_variables for @fuz-variables comments (regex scan misses dynamic templates).

css_class_composites
#

Record<string, CssClassDefinition | undefined> import {css_class_composites} from '@fuzdev/fuz_css/css_class_composites.js';

css_class_definitions
#

css_class_definitions.ts view source

Record<string, CssClassDefinition | undefined> import {css_class_definitions} from '@fuzdev/fuz_css/css_class_definitions.js';

All built-in CSS class definitions (token classes + composites).

css_class_interpreters
#

css_class_interpreters.ts view source

CssClassDefinitionInterpreter[] import {css_class_interpreters} from '@fuzdev/fuz_css/css_class_interpreters.js';

Collection of all builtin interpreters for dynamic CSS class generation. Order matters: modified_class_interpreter runs first to handle hover:box before css_literal_interpreter tries to interpret it as hover:box (property:value).

CSS_DIRECTIONS
#

css_class_interpreters.ts view source

readonly ["top", "right", "bottom", "left"] import {CSS_DIRECTIONS} from '@fuzdev/fuz_css/css_class_generators.js';

css_literal_interpreter
#

CssClassDefinitionInterpreter import {css_literal_interpreter} from '@fuzdev/fuz_css/css_class_interpreters.js';

Interpreter for CSS-literal classes (e.g., display:flex, hover:opacity:80%). Generates full CSS rulesets including any modifier wrappers.

CssCacheOptions
#

CssCacheOptions import type {CssCacheOptions} from '@fuzdev/fuz_css/css_plugin_options.js';

Options for cache behavior.

`cache_dir?`

Cache directory relative to project root.

type string

default '.fuz/cache/css'

`deps?`

Filesystem deps for cache management. Defaults to production implementation. Override for testing.

type CacheDeps

CssClassDefinition
#

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

Full union including interpreters.

CssClassDefinitionBase
#

CssClassDefinitionBase import type {CssClassDefinitionBase} from '@fuzdev/fuz_css/css_class_generation.js';

`comment?`

type string

CssClassDefinitionComposition
#

CssClassDefinitionComposition import type {CssClassDefinitionComposition} from '@fuzdev/fuz_css/css_class_generation.js';

type never

`declaration?`

type never

CssClassDefinitionStatic
#

css_classes.ts view source

CssClassDefinitionStatic import type {CssClassDefinitionStatic} from '@fuzdev/fuz_css/css_class_generation.js';

Static definitions (not interpreter-based).

CssClasses
#

import {CssClasses} from '@fuzdev/fuz_css/css_classes.js';

Collection of CSS classes extracted from source files. Tracks classes per-file for efficient incremental updates. Handles include/exclude filtering and explicit class tracking. Uses null instead of empty collections to avoid allocation overhead.

`constructor`

Creates a new CssClasses collection.

type new (additional_classes?: Set<string> | null, exclude_classes?: Set<string> | null): CssClasses

`additional_classes`

classes to always include (also treated as explicit for warnings)

type Set<string> | null

default null

`exclude_classes`

classes to exclude from output (also suppresses warnings)

type Set<string> | null

default null

`add`

Adds extraction results for a file. Replaces any previous classes and diagnostics for this file.

type (id: string, data: ExtractionData): void

`id`

file identifier

type string

`data`

extraction data fields to store for this file

type ExtractionData

returns void

`delete`

type (id: string): void

`id`

type string

returns void

`get`

Gets all unique class names as a Set (with exclude filter applied).

type (): Set<string>

returns Set<string>

`get_with_locations`

Gets all classes with their source locations (with exclude filter applied). Locations from additional_classes are null.

type (): Map<string, SourceLocation[] | null>

returns Map<string, SourceLocation[] | null>

`get_all`

Gets all classes and their locations in a single call. More efficient than calling get() and get_with_locations() separately when both are needed (avoids potential double recalculation).

Results have exclude filter applied and explicit_classes includes additional_classes.

type (): { all_classes: Set<string>; all_classes_with_locations: Map<string, SourceLocation[] | null>; explicit_classes: Set<string> | null; all_elements: Set<...>; explicit_elements: Set<...> | null; explicit_variables: Set<...> | null; }

returns

{ all_classes: Set<string>; all_classes_with_locations: Map<string, SourceLocation[] | null>; explicit_classes: Set<string> | null; all_elements: Set<...>; explicit_elements: Set<...> | null; explicit_variables: Set<...> | null; }

`get_diagnostics`

Gets all extraction diagnostics from all files.

type (): ExtractionDiagnostic[]

returns ExtractionDiagnostic[]

CssClassInterpreterContext
#

CssClassInterpreterContext import type {CssClassInterpreterContext} from '@fuzdev/fuz_css/css_class_generation.js';

Context passed to CSS class interpreters. Provides access to logging, diagnostics collection, and the class registry.

`log?`

Optional logger for warnings/errors

type Logger

`diagnostics`

Diagnostics array to collect warnings and errors

type Array<InterpreterDiagnostic>

`class_definitions`

All known CSS class definitions (token + composite classes)

type Record<string, CssClassDefinition | undefined>

`css_properties`

Valid CSS properties for literal validation, or null to skip validation

type Set<string> | null

CssClassOptions
#

CssClassOptions import type {CssClassOptions} from '@fuzdev/fuz_css/css_plugin_options.js';

Options for CSS class definitions and interpretation. Controls how classes are defined and how dynamic classes are generated.

`class_definitions?`

Additional class definitions to merge with defaults. User definitions take precedence over defaults with the same name. Required when include_default_classes is false.

type Record<string, CssClassDefinition | undefined>

`include_default_classes?`

Whether to include default class definitions (token and composite classes). When false, class_definitions is required.

type boolean

`class_interpreters?`

Custom interpreters for dynamic class generation. Replaces the builtin interpreters entirely if provided.

type Array<CssClassDefinitionInterpreter>

CssClassVariableIndex
#

CssClassVariableIndex import type {CssClassVariableIndex} from '@fuzdev/fuz_css/class_variable_index.js';

Index mapping class names to their CSS variable dependencies.

`by_class`

Map from class name to set of variable names (without -- prefix)

type Map<string, Set<string>>

CssDiagnosticsOptions
#

CssDiagnosticsOptions import type {CssDiagnosticsOptions} from '@fuzdev/fuz_css/css_plugin_options.js';

Options for error and warning handling.

`on_error?`

How to handle CSS-literal errors during generation.

'log': Log errors, skip invalid classes, continue
'throw': Throw on first error, fail the build

type 'log' | 'throw'

default 'throw' in CI, 'log' otherwise

`on_warning?`

How to handle warnings during generation.

'log': Log warnings, continue
'throw': Throw on first warning, fail the build
'ignore': Suppress warnings entirely

type 'log' | 'throw' | 'ignore'

default 'log'

CssDirection
#

"top" | "right" | "bottom" | "left" import type {CssDirection} from '@fuzdev/fuz_css/css_class_generators.js';

CssExtractionOptions
#

CssExtractionOptions import type {CssExtractionOptions} from '@fuzdev/fuz_css/css_plugin_options.js';

Options for CSS class extraction from source files. Controls which files to scan and how to parse them.

`filter_file?`

Filter function to determine which files to extract classes from. By default, extracts from .svelte, .html, .ts, .js, .tsx, .jsx files, excluding test files and .gen files.

type FileFilter

`acorn_plugins?`

Additional acorn plugins for parsing. Use acorn-jsx for React/Preact/Solid projects.

type Array<AcornPlugin>

import jsx from 'acorn-jsx';
gen_fuz_css({ acorn_plugins: [jsx()] });

CssGenerationError
#

import {CssGenerationError} from '@fuzdev/fuz_css/diagnostics.js';

Error thrown when CSS generation encounters errors or warnings (depending on on_error and on_warning settings). Contains the full diagnostics array for programmatic access.

inheritance

extends: Error

`diagnostics`

type Array<Diagnostic>

`constructor`

type new (diagnostics: Diagnostic[]): CssGenerationError

`diagnostics`

type Diagnostic[]

CssGeneratorBaseOptions
#

CssGeneratorBaseOptions import type {CssGeneratorBaseOptions} from '@fuzdev/fuz_css/css_plugin_options.js';

Combined base options shared by both Gro and Vite plugins. These options work identically in both contexts.

inheritance

extends: CssExtractionOptions,CssClassOptions,CssOutputOptions,CssDiagnosticsOptions,CssCacheOptions

CssLiteralOutput
#

CssLiteralOutput import type {CssLiteralOutput} from '@fuzdev/fuz_css/css_literal.js';

Information needed to generate CSS output for a CSS-literal class.

`declaration`

CSS declaration (property: value;)

type string

`selector`

Full CSS selector including pseudo-classes/elements

type string

`media_wrapper`

Media query wrapper if any

type string | null

`ancestor_wrapper`

Ancestor wrapper if any

type string | null

CssLiteralParseResult
#

CssLiteralParseResult import type {CssLiteralParseResult} from '@fuzdev/fuz_css/css_literal.js';

Result of parsing a CSS-literal class name.

Uses a discriminated union (Result type) because parsing a single class is binary: it either succeeds or fails entirely. This differs from ExtractionResult which uses embedded diagnostics because file extraction can partially succeed (some classes extracted, others have errors).

Uses | null for diagnostics to avoid allocating empty arrays. Callers should use a guard pattern: if (result.diagnostics) { ... }

CssOutputOptions
#

CssOutputOptions import type {CssOutputOptions} from '@fuzdev/fuz_css/css_plugin_options.js';

Options for CSS output generation (theme + base + utilities). Controls how the three CSS layers are combined.

`base_css?`

Base styles (element defaults) configuration.

undefined (default): Use default style.css
null: Disable base styles entirely
string: Custom CSS to replace defaults
(default_css) => string: Callback to modify default CSS

type BaseCssOption

// Append custom reset
base_css: (css) => css + '\n\n* { box-sizing: border-box; }'

// Prepend custom styles
base_css: (css) => '.my-reset { margin: 0; }\n\n' + css

`variables?`

Theme variables configuration.

undefined (default): Use default variables from fuz_css
null: Disable theme entirely
Array<StyleVariable>: Custom variable definitions (replaces defaults)
(defaults) => Array<StyleVariable>: Callback to modify default variables

type VariablesOption

// Override specific variables
variables: (defaults) => defaults.map(v =>
    v.name === 'hue_a' ? { ...v, light: '30' } : v
)

// Add custom variables
variables: (defaults) => [
    ...defaults,
    { name: 'my_brand', light: '#ff6600', dark: '#ff8833' }
]

CssResolutionOptions
#

CssResolutionResult
#

CssResolutionResult import type {CssResolutionResult} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Result from CSS resolution.

`theme_css`

CSS for theme variables (light and dark)

type string

`base_css`

CSS for base styles (from style.css)

type string

`resolved_variables`

All resolved variable names (including transitive deps)

type Set<string>

`included_rule_indices`

Indices of rules included from the style index

type Set<number>

`included_elements`

Element names that were matched

type Set<string>

`diagnostics`

Diagnostics from resolution

type Array<GenerationDiagnostic>

`stats?`

Resolution statistics (only when include_stats is true)

type CssResolutionStats

CssResolutionStats
#

DarkenLightenVariant
#

deps_defaults.ts view source

"00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100" import type {DarkenLightenVariant} from '@fuzdev/fuz_css/variable_data.js';

default_cache_deps
#

CacheDeps import {default_cache_deps} from '@fuzdev/fuz_css/deps_defaults.js';

Default filesystem deps using node:fs/promises.

DEFAULT_CACHE_DIR
#

".fuz/cache/css" import {DEFAULT_CACHE_DIR} from '@fuzdev/fuz_css/css_cache.js';

Default cache directory relative to project root.

DEFAULT_THEME
#

themes.ts view source

Theme import {DEFAULT_THEME} from '@fuzdev/fuz_css/themes.js';

default_themes
#

themes.ts view source

Theme[] import {default_themes} from '@fuzdev/fuz_css/themes.js';

The curated theme registry that theme pickers enumerate.

Registry themes are semantic-tier by policy: they move intent bindings (which palette letter a meaning points at) and levers (chroma scale, hue shift, curves, form knobs) but never the palette hues themselves, so the letters stay a stable vocabulary across every registered theme.

Themes live one module per theme under themes/ and every module ships as an importable export — registry membership, not file location, is what separates builtins from shipped exemplars. Palette-tier themes (rotations, duotone/monochrome collapses like themes/terminal.ts) and the expressive exemplars (themes/necromancer.ts, themes/sunset_ember.ts, themes/brutalish.ts) deliberately stay out of this list.

default_variables
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; }[] import {default_variables} from '@fuzdev/fuz_css/variables.js';

These are implicitly the variables for the base theme. See also the empty variables array of the base theme in themes.ts.

delete_cached_extraction
#

(deps: CacheDeps, cache_path: string): Promise<void> import {delete_cached_extraction} from '@fuzdev/fuz_css/css_cache.js';

Deletes a cached extraction file. Silently succeeds if the file doesn't exist.

`deps`

filesystem deps for dependency injection

type CacheDeps

`cache_path`

absolute path to the cache file

type string

returns

Promise<void>

demo_class
#

"mb_xs4" import {demo_class} from '@fuzdev/fuz_css/example_class_utilities.js';

*_class suffix (snake_case)

DEMO_CLASS
#

"mb_xs3" import {DEMO_CLASS} from '@fuzdev/fuz_css/example_class_utilities.js';

SCREAMING_SNAKE_CASE naming

demo_class_list
#

"mb_xl3" import {demo_class_list} from '@fuzdev/fuz_css/example_class_utilities.js';

*class_list suffix (snake_case)

demo_class_lists
#

"mb_xl5 ml_xl2" import {demo_class_lists} from '@fuzdev/fuz_css/example_class_utilities.js';

*class_lists suffix (snake_case) - plural, multiple classes

demo_class_name
#

"mb_md" import {demo_class_name} from '@fuzdev/fuz_css/example_class_utilities.js';

*class_name suffix (snake_case)

demo_class_names
#

"mb_xl ml_lg" import {demo_class_names} from '@fuzdev/fuz_css/example_class_utilities.js';

*class_names suffix (snake_case) - plural, multiple classes

demo_classes
#

"mb_xs ml_sm" import {demo_classes} from '@fuzdev/fuz_css/example_class_utilities.js';

*_classes suffix (snake_case) - plural, multiple classes

demoClass
#

"mb_xs5" import {demoClass} from '@fuzdev/fuz_css/example_class_utilities.js';

*Class suffix (camelCase)

demoClasses
#

"mb_xs2 ml_xs" import {demoClasses} from '@fuzdev/fuz_css/example_class_utilities.js';

*Classes suffix (camelCase) - plural, multiple classes

demoClassList
#

"mb_xl2" import {demoClassList} from '@fuzdev/fuz_css/example_class_utilities.js';

*ClassList suffix (camelCase)

demoClassLists
#

"mb_xl4 ml_xl" import {demoClassLists} from '@fuzdev/fuz_css/example_class_utilities.js';

*ClassLists suffix (camelCase) - plural, multiple classes

demoClassName
#

"mb_sm" import {demoClassName} from '@fuzdev/fuz_css/example_class_utilities.js';

*ClassName suffix (camelCase)

demoClassNames
#

"mb_lg ml_md" import {demoClassNames} from '@fuzdev/fuz_css/example_class_utilities.js';

*ClassNames suffix (camelCase) - plural, multiple classes

Diagnostic
#

`name`

type string

returns

string

examples

escape_css_selector('display:flex') // 'display\\:flex'
escape_css_selector('opacity:80%') // 'opacity\\:80\\%'
escape_css_selector('nth-child(2n)') // 'nth-child\\(2n\\)'

extract_and_validate_modifiers
#

(segments: string[], class_name: string): ModifierExtractionResult import {extract_and_validate_modifiers} from '@fuzdev/fuz_css/css_literal.js';

Extracts and validates modifiers from the beginning of a segments array. Modifiers are consumed from the front until a non-modifier segment is found.

Used by both CSS-literal parsing and modified class interpretation.

`segments`

array of colon-separated segments

type string[]

`class_name`

original class name for error messages

type string

returns

ModifierExtractionResult

ModifierExtractionResult with modifiers and remaining segments, or error

extract_balanced_parens
#

(segment: string, prefix: string): string | null import {extract_balanced_parens} from '@fuzdev/fuz_css/modifiers.js';

Extracts content from balanced parentheses after a prefix. Supports nested parens for calc(), clamp(), min(), max(), etc.

`segment`

the full segment to parse (e.g., "min-width(calc(100vw - 200px))")

type string

`prefix`

the prefix before the opening paren (e.g., "min-width")

type string

returns

string | null

the content inside the balanced parens, or null if no match/unbalanced

examples

extract_balanced_parens("min-width(800px)", "min-width") // "800px"
extract_balanced_parens("min-width(calc(100vw - 20px))", "min-width") // "calc(100vw - 20px)"
extract_balanced_parens("min-width(calc(100vw)", "min-width") // null (unbalanced)

extract_css_classes
#

(source: string, options?: ExtractCssClassesOptions): Set<string> | null import {extract_css_classes} from '@fuzdev/fuz_css/css_class_extractor.js';

Unified extraction function that auto-detects file type. Returns just the class names as a Set.

`source`

the file source code

type string

`options`

extraction options

type ExtractCssClassesOptions

default {}

returns

Set<string> | null

set of class names, or null if none found

extract_css_classes_with_locations
#

(source: string, options?: ExtractCssClassesOptions): ExtractionResult import {extract_css_classes_with_locations} from '@fuzdev/fuz_css/css_class_extractor.js';

Unified extraction function that auto-detects file type. Returns full extraction result with locations and diagnostics.

`source`

the file source code

type string

`options`

extraction options

type ExtractCssClassesOptions

default {}

returns

ExtractionResult

full extraction result with classes, tracked variables, and diagnostics

extract_css_comment
#

css_variable_utils.ts view source

(css: string, rules: ParsedRule[]): string | null import {extract_css_comment} from '@fuzdev/fuz_css/css_ruleset_parser.js';

Extracts the CSS comment from a ruleset (if any). Looks for comments before the first rule.

`css`

raw CSS string

type string

`rules`

parsed rules

type ParsedRule[]

returns

string | null

comment text without delimiters, or null if no comment

extract_css_variables
#

(css: string): Set<string> import {extract_css_variables} from '@fuzdev/fuz_css/css_variable_utils.js';

Extracts CSS variable names from a CSS string.

Parses var(--name) patterns and returns the variable names without the -- prefix. Handles fallback values by extracting only the primary variable reference.

`css`

CSS string potentially containing var(--*) references

type string

returns

Set<string>

set of variable names (without -- prefix)

examples

extract_css_variables('color: var(--text_color);')
// → Set { 'text_color' }

extract_css_variables('background: var(--bg_1, var(--bg_2));')
// → Set { 'bg_1', 'bg_2' }

extract_css_variables('padding: 1rem;')
// → Set {}

extract_file_cached
#

extract_file_cached.ts view source

(options: ExtractFileCachedOptions): Promise<ExtractFileCachedResult> import {extract_file_cached} from '@fuzdev/fuz_css/extract_file_cached.js';

Loads the cached extraction when its content hash matches, otherwise extracts fresh. On a miss with caching enabled, cache_path_to_write carries the path the caller should write.

`options`

type ExtractFileCachedOptions

additional acorn plugins (e.g., acorn-jsx for React)

type AcornPlugin[] | undefined

optional

returns

ExtractionResult

extraction result with classes, tracked variables, elements, and diagnostics

extract_primary_property
#

(declaration: string): string | null import {extract_primary_property} from '@fuzdev/fuz_css/css_class_generation.js';

Extracts the CSS property name from a single-property declaration string. Returns null for multi-property declarations (composites with multiple semicolons).

`declaration`

type string

returns

string | null

examples

extract_primary_property('border-radius: var(--border_radius_sm);') // 'border-radius'
extract_primary_property('display: flex; align-items: center;') // null

extract_segments
#

(class_name: string): string[] import {extract_segments} from '@fuzdev/fuz_css/css_literal.js';

Extracts colon-separated segments from a class name, handling parentheses. Parenthesized content (like function arguments) is kept intact.

`class_name`

type string

returns

string[]

examples

extract_segments('md:hover:display:flex') // → ['md', 'hover', 'display', 'flex']
extract_segments('nth-child(2n+1):color:red') // → ['nth-child(2n+1)', 'color', 'red']
extract_segments('width:calc(100%-20px)') // → ['width', 'calc(100%-20px)']

ExtractCssClassesOptions
#

ExtractCssClassesOptions import type {ExtractCssClassesOptions} from '@fuzdev/fuz_css/css_class_extractor.js';

Options for CSS class extraction.

`filename?`

File path used to determine extraction method (Svelte vs TS) and for location tracking in diagnostics.

type string

`acorn_plugins?`

Additional acorn plugins to use when parsing TS/JS files. Useful for adding JSX support via acorn-jsx for React projects.

type Array<AcornPlugin>

import jsx from 'acorn-jsx';
extract_css_classes(source, { acorn_plugins: [jsx()] });

ExtractedModifiers
#

extract_file_cached.ts view source

ExtractedModifiers import type {ExtractedModifiers} from '@fuzdev/fuz_css/css_literal.js';

Extracted modifiers from a class name. Used by both CSS-literal parsing and modified class interpretation.

`media`

Media modifier (breakpoint or feature query)

type ModifierDefinition | null

`ancestor`

Ancestor modifier (dark/light)

type ModifierDefinition | null

`states`

State modifiers in alphabetical order (can have multiple)

type Array<ModifierDefinition>

`pseudo_element`

Pseudo-element modifier (before, after, etc.)

type ModifierDefinition | null

ExtractFileCachedOptions
#

ExtractFileCachedOptions import type {ExtractFileCachedOptions} from '@fuzdev/fuz_css/extract_file_cached.js';

`deps`

type CacheDeps

`content`

Source file contents.

type string

`content_hash`

Content hash to validate the cache against.

type string

`cache_path`

Cache file path, or null to skip the cache (CI or caching disabled).

type string | null

`filename`

File path, for parser selection and diagnostic locations.

type string

`acorn_plugins?`

type Array<AcornPlugin>

ExtractFileCachedResult
#

extract_file_cached.ts view source

ExtractFileCachedResult import type {ExtractFileCachedResult} from '@fuzdev/fuz_css/extract_file_cached.js';

`extraction`

type ExtractionData

`from_cache`

Whether the extraction came from cache.

type boolean

`cache_path_to_write`

Cache file to write (miss with caching enabled), or null.

type string | null

ExtractionData
#

inheritance

extends: BaseDiagnostic

`phase`

type 'extraction'

`location`

type SourceLocation

ExtractionResult
#

ExtractionResult import type {ExtractionResult} from '@fuzdev/fuz_css/css_class_extractor.js';

Extraction result with classes mapped to their source locations. Extends ExtractionData with tracked_vars which is internal to AST walking.

Uses embedded diagnostics (rather than a Result type) because file extraction can partially succeed: some classes may be extracted while others produce errors. This differs from CssLiteralParseResult which uses a discriminated union because single-class parsing is binary success/failure.

file_filter.ts view source

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {fg_95} from '@fuzdev/fuz_css/variables.js';

FileFilter
#

FileFilter import type {FileFilter} from '@fuzdev/fuz_css/file_filter.js';

Filter function to determine which files to process for CSS class extraction.

`(call)`

type (path: string): boolean

`path`

type string

returns boolean

filter_file_default
#

file_filter.ts view source

(path: string): boolean import {filter_file_default} from '@fuzdev/fuz_css/file_filter.js';

Default file filter for CSS class extraction. Includes .svelte, .html, .ts, .js, .tsx, .jsx files. Excludes test files (.test.ts, .spec.ts) and generated files (.gen.ts). Excludes files in test directories (/test/, /tests/, /__tests__/, /__mocks__/).

`path`

type string

returns

boolean

find_compound_end
#

(selector: string, class_pos: number): number import {find_compound_end} from '@fuzdev/fuz_css/css_ruleset_parser.js';

Finds the end position of the compound selector containing the class at class_pos. A compound selector is a sequence of simple selectors without combinators.

`selector`

the CSS selector string

type string

`class_pos`

position of the . in .class_name

type number

returns

number

position where state modifiers should be inserted (before any pseudo-element)

find_similar_variable
#

Replaces ~ with space
Ensures space before !important

`value`

raw value from class name

type string

returns

returns

string

format_variable_name
#

(str: string): string import {format_variable_name} from '@fuzdev/fuz_css/css_class_generators.js';

`str`

type string

returns

string

from_cached_extraction
#

(cached: CachedExtraction): ExtractionData import {from_cached_extraction} from '@fuzdev/fuz_css/css_cache.js';

Converts a cached extraction back to the runtime format. Preserves null semantics (null = empty).

`cached`

cached extraction data

type CachedExtraction

returns

ExtractionData

fromComment
#

vite_plugin_fuz_css.ts view source

"shadow_lg" import {fromComment} from '@fuzdev/fuz_css/example_class_utilities.js';

Comment hint - extracted via @fuz-classes, NOT via variable name pattern. Variable name fromComment doesn't end in class/classes/className.

FUZ_CSS_BANNER
#

"/* generated by vite_plugin_fuz_css */" import {FUZ_CSS_BANNER} from '@fuzdev/fuz_css/vite_plugin_fuz_css.js';

Banner comment at the top and bottom of generated CSS output.

FUZ_LAYER_ORDER_STATEMENT
#

gen_fuz_css.ts view source

"@layer fuz.base, fuz.theme, fuz.utilities;" import {FUZ_LAYER_ORDER_STATEMENT} from '@fuzdev/fuz_css/theme.js';

The fuz_css cascade layer order: defaults (variables + element styles) in fuz.base, theme overrides in fuz.theme, generated utility classes in fuz.utilities. Layer order beats specificity, so theme overrides win over the statically imported defaults regardless of head insertion order, and consumers' unlayered styles beat everything.

gen_fuz_css
#

(options?: GenFuzCssOptions): Gen import {gen_fuz_css} from '@fuzdev/fuz_css/gen_fuz_css.js';

`options`

type GenFuzCssOptions

default {}

returns

Gen

generate_base_css
#

(index: StyleRuleIndex, included_indices: Set<number>): string import {generate_base_css} from '@fuzdev/fuz_css/style_rule_parser.js';

Generates CSS from a StyleRuleIndex with only the included rules.

`index`

the StyleRuleIndex

type StyleRuleIndex

`included_indices`

set of rule indices to include

type Set<number>

returns

string

CSS string with only included rules, in original order

generate_border_radius_corners
#

(values: Iterable<string>, formatter?: ((value: string) => string) | undefined): Record<string, CssClassDefinition> import {generate_border_radius_corners} from '@fuzdev/fuz_css/css_class_generators.js';

Generate border radius corner classes for all four corners. Creates classes for top-left, top-right, bottom-left, bottom-right corners.

`values`

the values to generate classes for

type Iterable<string>

`formatter?`

optional function to format values

type ((value: string) => string) | undefined

optional

returns

Record<string, CssClassDefinition>

generate_bundled_css
#

(result: CssResolutionResult, utility_css: string, options?: GenerateBundledCssOptions): string import {generate_bundled_css} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Generates combined CSS output from resolution result.

`result`

resolution result from resolve_css

type CssResolutionResult

`utility_css`

generated utility CSS (from generate_classes_css)

type string

`options`

output options

type GenerateBundledCssOptions

default {}

returns

string

combined CSS string

generate_classes
#

<T1 = string, T2 = string, T3 = string>(template: ClassTemplateFn<T1, T2, T3>, values: Iterable<T1>, secondary?: Iterable<T2> | undefined, tertiary?: Iterable<...> | undefined): Record<...>

import {generate_classes} from '@fuzdev/fuz_css/css_class_generators.js';

Generates CSS class declarations from templates. Supports up to 3 dimensions of multiplicative combinations.

`template`

function that generates CSS from values, can return null to skip

type ClassTemplateFn<T1, T2, T3>

`values`

primary iterable of values

type Iterable<T1>

`secondary?`

optional second dimension (makes it multiplicative)

type Iterable<T2> | undefined

optional

`tertiary?`

optional third dimension for even more combinations

type Iterable<T3> | undefined

optional

returns

Record<string, CssClassDefinition>

generics

generate_classes<T1 = string, T2 = string, T3 = string>

`T1`

default string

`T2`

default string

`T3`

default string

examples

// Simple list
generate_classes(
  v => ({ name: `position_${v}`, css: `position: ${v};` }),
  ['static', 'relative', 'absolute']
)

// Two dimensions (multiplicative)
generate_classes(
  (dir, size) => ({ name: `m${dir}_${size}`, css: `margin-${dir}: ${size};` }),
  ['top', 'bottom'],
  ['0', '1px', '2px']
)

generate_classes_css
#

generate_css.ts view source

(options: GenerateClassesCssOptions): GenerateClassesCssResult import {generate_classes_css} from '@fuzdev/fuz_css/css_class_generation.js';

`options`

type GenerateClassesCssOptions

returns

GenerateClassesCssResult

generate_css
#

(options: GenerateCssOptions): GenerateCssResult import {generate_css} from '@fuzdev/fuz_css/generate_css.js';

Runs the full CSS-generation pipeline: utility classes via generate_classes_css, then — when base or theme output is enabled and bundled resources are available — base styles and theme variables via resolve_css + generate_bundled_css. Returns the combined CSS and every diagnostic produced along the way.

`options`

type GenerateCssOptions

returns

GenerateCssResult

generate_css_literal_simple
#

(output: CssLiteralOutput): string import {generate_css_literal_simple} from '@fuzdev/fuz_css/css_literal.js';

Generates simple CSS for a CSS-literal class (without grouping). Used by the interpreter for basic output.

`output`

the CSS-literal output info

type CssLiteralOutput

returns

string

CSS string for this class

generate_declaration
#

(parsed: ParsedCssLiteral): string import {generate_declaration} from '@fuzdev/fuz_css/css_literal.js';

Generates the CSS declaration for a parsed CSS-literal class.

`parsed`

type ParsedCssLiteral

returns

string

generate_directional_classes
#

(property: string, values: Iterable<string>, formatter?: ((v: string) => string) | undefined): Record<string, CssClassDefinition>

import {generate_directional_classes} from '@fuzdev/fuz_css/css_class_generators.js';

Generate directional classes for properties like margin and padding. Creates classes for all directions: base, top, right, bottom, left, x (horizontal), y (vertical).

`property`

the base CSS property name (e.g. 'margin', 'padding')

type string

`values`

the values to generate classes for

type Iterable<string>

`formatter?`

optional function to format values (defaults to identity)

type ((v: string) => string) | undefined

optional

returns

Record<string, CssClassDefinition>

generate_modified_ruleset
#

(original_ruleset: string, original_class: string, new_class_escaped: string, state_css: string, pseudo_element_css: string, media_wrapper: string | null, ancestor_wrapper: string | null): ModifiedRulesetResult

import {generate_modified_ruleset} from '@fuzdev/fuz_css/css_ruleset_parser.js';

Generates CSS for a modified ruleset with applied modifiers.

Conflict handling is per-selector within selector lists:

For .plain:hover, .plain:active with hover: modifier, only .plain:hover skips the :hover addition; .plain:active still gets :hover appended.
For multiple states like :hover:focus, each is checked individually; conflicting states are skipped while non-conflicting ones are still applied.

generate_property_classes
#

(property: string, values: Iterable<string>, formatter?: ((value: string) => string) | undefined, prefix?: string): Record<string, CssClassDefinition>

import {generate_property_classes} from '@fuzdev/fuz_css/css_class_generators.js';

Generate classes for a single CSS property with various values.

`property`

the CSS property name (e.g. 'font-size', 'gap')

type string

`values`

the values to generate classes for

type Iterable<string>

`formatter?`

optional function to format values (e.g. v => var(--space_${v}))

type ((value: string) => string) | undefined

optional

`prefix`

optional class name prefix (defaults to property with dashes replaced by underscores)

type string

default format_variable_name(property)

returns

Record<string, CssClassDefinition>

generate_selector
#

(escaped_class_name: string, parsed: ParsedCssLiteral): string import {generate_selector} from '@fuzdev/fuz_css/css_literal.js';

Generates the CSS selector for a parsed CSS-literal class. Includes state pseudo-classes and pseudo-element in the selector.

`escaped_class_name`

type string

`parsed`

type ParsedCssLiteral

returns

string

generate_shadow_classes
#

(sizes: Iterable<string>, alpha_mapping: Record<string, string>): Record<string, CssClassDefinition> import {generate_shadow_classes} from '@fuzdev/fuz_css/css_class_generators.js';

Generate shadow classes for various shadow types and sizes. Creates classes for regular, top, bottom, inset, inset-top, and inset-bottom shadows. Each shadow uses color-mix with alpha values for transparency.

`sizes`

the shadow size variants (xs, sm, md, lg, xl)

type Iterable<string>

`alpha_mapping`

mapping of sizes to alpha numbers (1-5)

type Record<string, string>

returns

Record<string, CssClassDefinition>

generate_theme_css
#

(graph: VariableDependencyGraph, resolved_variables: Set<string>): { light_css: string; dark_css: string; } import {generate_theme_css} from '@fuzdev/fuz_css/variable_graph.js';

Generates theme CSS for the resolved variables.

`graph`

the variable dependency graph

type VariableDependencyGraph

`resolved_variables`

set of variable names to include

type Set<string>

returns

{ light_css: string; dark_css: string; }

object with light_css and dark_css strings

GenerateBundledCssOptions
#

GenerateBundledCssOptions import type {GenerateBundledCssOptions} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Options for bundled CSS output generation.

`include_theme?`

Include theme variables section.

type boolean

default true

`include_base?`

Include base styles section.

type boolean

default true

`include_utilities?`

Include utility classes section.

type boolean

default true

GenerateClassesCssOptions
#

GenerateClassesCssOptions import type {GenerateClassesCssOptions} from '@fuzdev/fuz_css/css_class_generation.js';

`class_names`

type Iterable<string>

`class_definitions`

type Record<string, CssClassDefinition | undefined>

`interpreters`

type Array<CssClassDefinitionInterpreter>

`css_properties`

Valid CSS properties for literal validation, or null to skip validation

type Set<string> | null

`log?`

type Logger

`class_locations?`

type Map<string, Array<SourceLocation> | null>

`explicit_classes?`

Classes that were explicitly annotated (via @fuz-classes or additional_classes). Unresolved explicit classes produce warnings.

type Set<string> | null

GenerateClassesCssResult
#

generate_css.ts view source

GenerateClassesCssResult import type {GenerateClassesCssResult} from '@fuzdev/fuz_css/css_class_generation.js';

Result from CSS class generation.

`css`

type string

`diagnostics`

type Array<GenerationDiagnostic>

`variables_used`

CSS variables used by the generated classes (without -- prefix)

type Set<string>

GenerateCssOptions
#

`class_definitions`

type Record<string, CssClassDefinition | undefined>

`interpreters`

type Array<CssClassDefinitionInterpreter>

`css_properties`

Valid CSS properties for literal validation, or null to skip.

type Set<string> | null

`include_base`

type boolean

`include_theme`

type boolean

`resources`

Bundled resources, or null for utility-only mode.

type BundledCssResources | null

`additional_elements?`

type Iterable<string> | 'all'

`additional_variables?`

type Iterable<string> | 'all'

`exclude_elements?`

type Iterable<string>

`exclude_variables?`

type Iterable<string>

`log?`

Optional logger; only used to emit resolution stats when include_stats.

type Logger

`include_stats?`

Whether to compute and log resolution statistics.

type boolean

GenerateCssResult
#

GenerateCssResult import type {GenerateCssResult} from '@fuzdev/fuz_css/generate_css.js';

`css`

Final CSS without banner comments — callers add their own.

type string

`diagnostics`

Extraction + generation + resolution diagnostics, unfiltered.

type Array<Diagnostic>

GeneratedClassResult
#

GeneratedClassResult import type {GeneratedClassResult} from '@fuzdev/fuz_css/css_class_generators.js';

GenerationDiagnostic
#

gen_fuz_css.ts view source

GenerationDiagnostic import type {GenerationDiagnostic} from '@fuzdev/fuz_css/diagnostics.js';

Diagnostic from the generation phase.

`phase`

type 'generation'

`level`

type 'error' | 'warning'

`message`

type string

`suggestion`

type string | null

`identifier`

The class name, element name, or variable name this diagnostic refers to

type string

`locations`

Source locations where this class was used, or null if from additional_classes

type Array<SourceLocation> | null

GenFuzCssOptions
#

GenFuzCssOptions import type {GenFuzCssOptions} from '@fuzdev/fuz_css/gen_fuz_css.js';

Options for the Gro CSS generator. Extends the shared base options with Gro-specific settings.

inheritance

extends: CssGeneratorBaseOptions

`include_stats?`

Whether to include file and resolution statistics in the output.

type boolean

default false

`project_root?`

Project root directory. Source paths must be under this directory.

type string

default process.cwd()

`concurrency?`

Max concurrent file processing (cache read + extract). Bottlenecked by CPU-bound AST parsing.

type number

default 8

`cache_io_concurrency?`

Max concurrent cache writes and deletes (I/O-bound).

type number

default 50

get_all_modifier_names
#

(): string[] import {get_all_modifier_names} from '@fuzdev/fuz_css/modifiers.js';

Gets all modifier names for error message suggestions.

returns

string[]

get_all_variable_names
#

(graph: VariableDependencyGraph): Set<string> import {get_all_variable_names} from '@fuzdev/fuz_css/variable_graph.js';

Gets all variable names from the graph.

`graph`

the variable dependency graph

type VariableDependencyGraph

returns

Set<string>

set of all variable names in the graph

get_cache_path
#

(source_path: string, cache_dir: string, project_root: string): string import {get_cache_path} from '@fuzdev/fuz_css/css_cache.js';

Computes the cache file path for a source file. Cache structure mirrors source tree: src/lib/Foo.svelte → .fuz/cache/css/src/lib/Foo.svelte.json

get_classes_using_variable
#

(index: CssClassVariableIndex, variable_name: string): string[] import {get_classes_using_variable} from '@fuzdev/fuz_css/class_variable_index.js';

Gets all class names that use a specific variable.

`index`

the class variable index

type CssClassVariableIndex

`variable_name`

variable name to search for (without -- prefix)

type string

returns

string[]

array of class names that use this variable

get_file_cache_path
#

(file_id: string, cache_dir: string, project_root: string): string import {get_file_cache_path} from '@fuzdev/fuz_css/css_cache.js';

Computes cache path for a file, handling both internal and external paths. Internal files use relative paths mirroring source tree. External files (outside project root) use hashed absolute paths in _external/.

`file_id`

absolute path to the source file

type string

`cache_dir`

absolute path to the cache directory

type string

`project_root`

normalized project root (must end with /)

type string

returns

string

get_matching_rules
#

(index: StyleRuleIndex, detected_elements: Set<string>, detected_classes: Set<string>): Set<number> import {get_matching_rules} from '@fuzdev/fuz_css/style_rule_parser.js';

Gets rules that should be included based on detected elements and classes.

`index`

the StyleRuleIndex to query

type StyleRuleIndex

`detected_elements`

set of HTML element names found in source

type Set<string>

`detected_classes`

set of CSS class names found in source

type Set<string>

returns

Set<number>

set of rule indices to include

get_modifier
#

css_variable_utils.ts view source

(segment: string): (ModifierDefinition & { is_arbitrary?: boolean | undefined; }) | null import {get_modifier} from '@fuzdev/fuz_css/modifiers.js';

Gets the modifier definition for a segment. Handles both static modifiers and dynamic patterns (arbitrary breakpoints, parameterized states).

`segment`

type string

returns

(ModifierDefinition & { is_arbitrary?: boolean | undefined; }) | null

the modifier definition or null if not a known modifier

has_css_variables
#

(css: string): boolean import {has_css_variables} from '@fuzdev/fuz_css/css_variable_utils.js';

Checks if a CSS string contains any CSS variable references.

More efficient than extract_css_variables when you only need to know if variables exist, not what they are.

`css`

CSS string to check

type string

returns

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {icon_size_xs} from '@fuzdev/fuz_css/variables.js';

icon_sizes
#

{ icon_size_xs: string; icon_size_sm: string; icon_size_md: string; icon_size_lg: string; icon_size_xl: string; icon_size_xl2: string; icon_size_xl3: string; }

"accent" | "positive" | "negative" | "caution" | "info" import type {IntentVariant} from '@fuzdev/fuz_css/variable_data.js';

The semantic color intents that derive full scales through the shared ramps. The neutral is also an intent (--hue_neutral) but is absent here because its scales are shade_* and text_* rather than a neutral_00–neutral_100 family.

interpret_css_literal
#

(class_name: string, escaped_class_name: string, css_properties: Set<string> | null): InterpretCssLiteralResult import {interpret_css_literal} from '@fuzdev/fuz_css/css_literal.js';

Interprets a CSS-literal class and returns CSS generation info.

Callers should first check is_possible_css_literal() to filter non-CSS-literal classes.

`class_name`

the class name to interpret

type string

`escaped_class_name`

the CSS-escaped version of the class name

type string

`css_properties`

Set of valid CSS properties from load_css_properties() Pass null to skip property validation.

type Set<string> | null

returns

InterpretCssLiteralResult

result with output and warnings on success, or error on failure

InterpretCssLiteralResult
#

InterpretCssLiteralResult import type {InterpretCssLiteralResult} from '@fuzdev/fuz_css/css_literal.js';

Result of interpreting a CSS-literal class.

Uses | null for warnings to avoid allocating empty arrays. Callers should use a guard pattern: if (result.warnings) { ... }

InterpreterDiagnostic
#

InterpreterDiagnostic import type {InterpreterDiagnostic} from '@fuzdev/fuz_css/diagnostics.js';

Diagnostic from CSS class interpretation. Used internally by interpreters; converted to GenerationDiagnostic with locations.

`level`

type 'error' | 'warning'

`message`

type string

`identifier`

The class name, element name, or variable name this diagnostic refers to

type string

`suggestion`

type string | null

is_possible_css_literal
#

Converts a linear-light sRGB component to gamma-encoded in [0, 1].

`c`

type number

returns

number

LineHeightVariant
#

"lg" | "md" | "sm" | "xs" | "xl" import type {LineHeightVariant} from '@fuzdev/fuz_css/variable_data.js';

link_color
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {link_color} from '@fuzdev/fuz_css/variables.js';

link_color_selected
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {link_color_selected} from '@fuzdev/fuz_css/variables.js';

LiteralResolutionResult
#

LiteralResolutionResult import type {LiteralResolutionResult} from '@fuzdev/fuz_css/css_literal.js';

Result of attempting to resolve a CSS literal for composition.

load_cached_extraction
#

(deps: CacheDeps, cache_path: string): Promise<CachedExtraction | null> import {load_cached_extraction} from '@fuzdev/fuz_css/css_cache.js';

Loads a cached extraction result from disk. Returns null if the cache is missing, corrupted, or has a version mismatch. This makes the cache self-healing: any error triggers re-extraction.

`deps`

filesystem deps for dependency injection

type CacheDeps

`cache_path`

absolute path to the cache file

type string

returns

Promise<CachedExtraction | null>

load_css_properties
#

(): Promise<Set<string>> import {load_css_properties} from '@fuzdev/fuz_css/css_literal.js';

Loads CSS properties from @webref/css. Returns a fresh Set each time - callers should cache the result if needed.

returns

Promise<Set<string>>

load_default_style_css
#

(deps: CacheDeps, style_css_path?: string | undefined): Promise<string> import {load_default_style_css} from '@fuzdev/fuz_css/style_rule_parser.js';

Loads the raw default style.css content.

`deps`

filesystem deps for dependency injection

type CacheDeps

`style_css_path?`

path to style.css (defaults to package's style.css)

type string | undefined

optional

returns

Promise<string>

promise resolving to the CSS string

load_style_rule_index
#

(deps: CacheDeps, style_css_path?: string | undefined): Promise<StyleRuleIndex> import {load_style_rule_index} from '@fuzdev/fuz_css/style_rule_parser.js';

Loads and parses the default style.css file.

`deps`

filesystem deps for dependency injection

type CacheDeps

`style_css_path?`

path to style.css (defaults to package's style.css)

type string | undefined

optional

returns

Promise<StyleRuleIndex>

promise resolving to StyleRuleIndex

logicalClass
#

"mt_md" import {logicalClass} from '@fuzdev/fuz_css/example_class_utilities.js';

Logical AND - truthy value extracted

MEDIA_MODIFIERS
#

css_class_definitions.ts view source

Map<string, ModifierDefinition> import {MEDIA_MODIFIERS} from '@fuzdev/fuz_css/modifiers.js';

Map of media modifier names to their CSS output

merge_class_definitions
#

(user_definitions: Record<string, CssClassDefinition | undefined> | undefined, include_defaults: boolean): Record<string, CssClassDefinition | undefined>

import {merge_class_definitions} from '@fuzdev/fuz_css/css_class_definitions.js';

Merges user class definitions with the built-in defaults. User definitions take precedence over defaults with the same name.

`user_definitions`

user-provided class definitions to merge

type Record<string, CssClassDefinition | undefined> | undefined

`include_defaults`

whether to include built-in definitions

type boolean

returns

Record<string, CssClassDefinition | undefined>

merged class definitions

throws

Error - if `include_defaults` is false and no user definitions provided

modified_class_interpreter
#

css_class_interpreters.ts view source

CssClassDefinitionInterpreter import {modified_class_interpreter} from '@fuzdev/fuz_css/css_class_interpreters.js';

Interpreter for modified token/composite classes (e.g., hover:p_md, md:box, dark:hover:panel). Applies modifiers to existing declaration-based or ruleset-based classes.

This interpreter must run BEFORE css_literal_interpreter to handle cases like hover:box where box is a known class (not a CSS property).

ModifiedRulesetResult
#

ModifiedRulesetResult import type {ModifiedRulesetResult} from '@fuzdev/fuz_css/css_ruleset_parser.js';

Result from generating a modified ruleset.

Uses | null for skipped_modifiers to avoid allocating empty arrays. Callers should use a guard pattern: if (result.skipped_modifiers) { ... }

`css`

The generated CSS

type string

`skipped_modifiers`

Information about modifiers that were skipped for certain rules, or null if none

type Array<SkippedModifierInfo> | null

ModifiedSelectorGroupResult
#

ModifiedSelectorGroupResult import type {ModifiedSelectorGroupResult} from '@fuzdev/fuz_css/css_ruleset_parser.js';

Result from modifying a selector group with conflict detection.

Uses | null for skipped_modifiers to avoid allocating empty arrays. Callers should use a guard pattern: if (result.skipped_modifiers) { ... }

`selector`

The modified selector list as a string

type string

`skipped_modifiers`

Information about modifiers skipped for specific selectors, or null if none

type Array<SkippedModifierInfo> | null

ModifierDefinition
#

ModifierDefinition import type {ModifierDefinition} from '@fuzdev/fuz_css/modifiers.js';

Definition for a single modifier.

`name`

The prefix used in class names (e.g., 'hover', 'md', 'dark')

type string

`type`

Type determines position in modifier order and CSS output behavior

type ModifierType

`css`

The CSS output - wrapper for media/ancestor, suffix for state/pseudo-element

type string

`order?`

Optional ordering within type (for breakpoints, sorted by this value)

type number

ModifierExtractionResult
#

ModifierExtractionResult import type {ModifierExtractionResult} from '@fuzdev/fuz_css/css_literal.js';

Result of extracting modifiers from segments.

MODIFIERS
#

ModifierDefinition[] import {MODIFIERS} from '@fuzdev/fuz_css/modifiers.js';

All modifier definitions in a single declarative structure. Adding a new modifier requires only adding to this array.

ModifierType
#

ModifierType import type {ModifierType} from '@fuzdev/fuz_css/modifiers.js';

Type of modifier determining its position in the class name and CSS output.

Order in class names: [media:][ancestor:][state...:][pseudo-element:]property:value

modify_selector_group
#

(selector_group: string, original_class: string, new_class_escaped: string, states_to_add: string[], pseudo_element_css: string): ModifiedSelectorGroupResult

ModifiedSelectorGroupResult

result with modified selector list and information about skipped modifiers

modify_single_selector
#

(selector: string, original_class: string, new_class_escaped: string, state_css: string, pseudo_element_css: string): string

string

modified selector

examples

modify_single_selector('.menuitem', 'menuitem', 'hover\\:menuitem', ':hover', '')
// → '.hover\\:menuitem:hover'

modify_single_selector('.menuitem .icon', 'menuitem', 'hover\\:menuitem', ':hover', '')
// → '.hover\\:menuitem:hover .icon'

modify_single_selector('.menuitem.selected', 'menuitem', 'hover\\:menuitem', ':hover', '')
// → '.hover\\:menuitem.selected:hover'

NEUTRAL_CHROMA
#

Record<"light" | "dark", number> import {NEUTRAL_CHROMA} from '@fuzdev/fuz_css/ramps.js';

Peak chroma of the neutral (shade/text) scales. The neutral rides the palette's chroma shape scaled to this peak, which preserves the old behavior of constant HSL saturation: strong tint at mid lightness, nearly untinted near white and black.

NEUTRAL_HUE
#

number import {NEUTRAL_HUE} from '@fuzdev/fuz_css/ramps.js';

Default OKLCH hue angle of the neutral intent. In CSS the knob chains to the palette (--hue_neutral: var(--hue_f)), porting the old tint_hue behavior; this constant mirrors that default numerically.

NonCoreStyleRule
#

NonCoreStyleRule import type {NonCoreStyleRule} from '@fuzdev/fuz_css/style_rule_parser.js';

A non-core style rule included only when its elements/classes are detected.

inheritance

type Oklab

returns

Oklch

oklab_to_srgb
#

([lightness, a, b]: Oklab): RgbUnit import {oklab_to_srgb} from '@fuzdev/fuz_css/oklch.js';

Converts OKLab to gamma-encoded sRGB.

`__0`

type Oklab

returns

RgbUnit

components that may fall outside [0, 1] when the color is out of gamut

Oklch
#

Oklch import type {Oklch} from '@fuzdev/fuz_css/oklch.js';

A color in OKLCH: lightness in [0, 1], chroma ≥ 0 (unbounded), hue in degrees.

oklch_delta_e
#

(a: Oklch, b: Oklch): number import {oklch_delta_e} from '@fuzdev/fuz_css/oklch.js';

boolean

oklch_max_srgb_chroma
#

(lch: Oklch): RgbUnit import {oklch_to_srgb} from '@fuzdev/fuz_css/oklch.js';

Converts OKLCH to gamma-encoded sRGB.

`lch`

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {palette_chroma_95} from '@fuzdev/fuz_css/variables.js';

PALETTE_CHROMA_CAPS
#

Record<"light" | "dark", Record<"00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100", number>>

import {PALETTE_CHROMA_CAPS} from '@fuzdev/fuz_css/ramps.js';

Worst-hue safe chroma caps per stop: the largest chroma at that stop's default lightness that stays inside sRGB for every one of the 10 default hues (see oklch_max_srgb_chroma for the non-convexity caveat). Computed at design time from PALETTE_HUES + PALETTE_LIGHTNESS_KNOBS, floored to stay conservative; a drift test recomputes them from the color math.

palette_chroma_curve
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {palette_chroma_curve} from '@fuzdev/fuz_css/variables.js';

PALETTE_CHROMA_KNOBS
#

Record<"light" | "dark", ChromaRampKnobs> import {PALETTE_CHROMA_KNOBS} from '@fuzdev/fuz_css/ramps.js';

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {palette_g_95} from '@fuzdev/fuz_css/variables.js';

palette_glosses
#

Record<"g" | "b" | "a" | "c" | "d" | "e" | "f" | "h" | "i" | "j", { color: string; binding?: "accent" | "positive" | "negative" | "caution" | "info" | "neutral" | undefined; }>

palette_stop_oklch
#

(letter: "g" | "b" | "a" | "c" | "d" | "e" | "f" | "h" | "i" | "j", stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100", scheme: "light" | "dark"): Oklch

import {palette_stop_oklch} from '@fuzdev/fuz_css/ramps.js';

Computes the default OKLCH color of a palette stop (--palette_X_NN).

`letter`

type "g" | "b" | "a" | "c" | "d" | "e" | "f" | "h" | "i" | "j"

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

`scheme`

type "light" | "dark"

returns

Oklch

palette_variants
#

readonly ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"] import {palette_variants} from '@fuzdev/fuz_css/variable_data.js';

PaletteVariant
#

"g" | "b" | "a" | "c" | "d" | "e" | "f" | "h" | "i" | "j" import type {PaletteVariant} from '@fuzdev/fuz_css/variable_data.js';

parse_arbitrary_breakpoint
#

(segment: string): string | null import {parse_arbitrary_breakpoint} from '@fuzdev/fuz_css/modifiers.js';

Parses an arbitrary breakpoint modifier. Supports nested parentheses for calc(), clamp(), min(), max(), var(). Requires value to start with a digit or known CSS function to catch obvious mistakes.

`segment`

type string

returns

string | null

the CSS media query or null if not an arbitrary breakpoint

examples

parse_arbitrary_breakpoint("min-width(800px)") // "@media (width >= 800px)"
parse_arbitrary_breakpoint("min-width(calc(100vw - 200px))") // "@media (width >= calc(100vw - 200px))"
parse_arbitrary_breakpoint("min-width(px)") // null (invalid - no digit or function)

parse_css_literal
#

(class_name: string, css_properties: Set<string> | null): CssLiteralParseResult import {parse_css_literal} from '@fuzdev/fuz_css/css_literal.js';

Parses a CSS-literal class name into its components.

`class_name`

the class name to parse

type string

`css_properties`

Set of valid CSS properties from load_css_properties() Pass null to skip property validation.

type Set<string> | null

returns

CssLiteralParseResult

CssLiteralParseResult with parsed data or error

parse_parameterized_state
#

(segment: string): { name: string; css: string; type: "state"; } | null import {parse_parameterized_state} from '@fuzdev/fuz_css/modifiers.js';

Parses a parameterized state modifier (nth-child, nth-last-child, nth-of-type, nth-last-of-type).

`segment`

type string

returns

{ name: string; css: string; type: "state"; } | null

object with name (including parameter) and CSS, or null if not parameterized

parse_ruleset
#

(css: string): ParsedRuleset import {parse_ruleset} from '@fuzdev/fuz_css/css_ruleset_parser.js';

Parses a CSS ruleset string using Svelte's CSS parser.

`css`

raw CSS string (e.g., ".box { display: flex; }")

type string

returns

ParsedRuleset

ParsedRuleset with structured rule data and positions

parse_style_css
#

(css: string, content_hash: string): StyleRuleIndex import {parse_style_css} from '@fuzdev/fuz_css/style_rule_parser.js';

Parses a CSS stylesheet into a StyleRuleIndex.

`css`

raw CSS string (e.g., contents of style.css)

type string

`content_hash`

hash of the CSS for cache invalidation

type string

returns

StyleRuleIndex

StyleRuleIndex with rules and lookup maps

ParsedCssLiteral
#

PSEUDO_ELEMENT_MODIFIERS
#

Map<string, ModifierDefinition> import {PSEUDO_ELEMENT_MODIFIERS} from '@fuzdev/fuz_css/modifiers.js';

Map of pseudo-element modifier names to their CSS output

radius_scale
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {radius_scale} from '@fuzdev/fuz_css/variables.js';

ramp_chroma
#

(scheme: "light" | "dark", stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100", chroma_scale?: number): number

import {ramp_chroma} from '@fuzdev/fuz_css/ramps.js';

Evaluates the palette chroma at a stop: the knob curve clamped by that stop's worst-hue cap. chroma_scale multiplies above the clamp.

`scheme`

type "light" | "dark"

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

`chroma_scale`

type number

default 1

returns

number

ramp_chroma_shape
#

(stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100", curve: number): number import {ramp_chroma_shape} from '@fuzdev/fuz_css/ramps.js';

Evaluates the normalized chroma shape pow(4t(1-t), curve) at a stop — 0 at the endpoints, 1 at the midpoint.

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

`curve`

type number

returns

number

ramp_lightness
#

(knobs: LightnessRampKnobs, stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"): number

import {ramp_lightness} from '@fuzdev/fuz_css/ramps.js';

Evaluates a lightness ramp at a stop.

`knobs`

import {render_chroma_stop_css} from '@fuzdev/fuz_css/ramps.js';

Renders the capped default of a palette chroma ramp stop: the knob curve clamped by that stop's worst-hue gamut cap. Per-scheme because the caps differ; --chroma_scale multiplies outside this clamp, at the color stops.

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

`scheme`

type "light" | "dark"

returns

string

render_hue_shift_offset_css
#

(stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100", scheme: "light" | "dark"): string

import {render_hue_shift_offset_css} from '@fuzdev/fuz_css/ramps.js';

Renders a stop's hue-shift offset. --hue_shift is the total rotation in degrees across a ramp, anchored at stop 50; the scheme sign flip is baked into these per-scheme slots so positive values always rotate hue upward toward the dark end.

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

`scheme`

type "light" | "dark"

returns

string

render_lightness_stop_css
#

(family: RampFamily, stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"): string

import {render_lightness_stop_css} from '@fuzdev/fuz_css/ramps.js';

Renders the derived default of an intermediate lightness ramp stop, e.g. --palette_lightness_30: calc(var(--palette_lightness_00) + (var(--palette_lightness_100) - var(--palette_lightness_00)) * pow(0.3, var(--palette_lightness_curve))). Stops 00/100 are the endpoint knobs themselves and have no derived form.

`family`

type RampFamily

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

returns

string

render_neutral_stop_css
#

(family: "text" | "shade", stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"): string

import {render_neutral_stop_css} from '@fuzdev/fuz_css/ramps.js';

Renders the derived default of a neutral (shade/text) stop. The neutral rides the palette's chroma shape scaled by the --neutral_chroma peak.

`family`

type "text" | "shade"

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

returns

string

render_palette_stop_css
#

(letter: "g" | "b" | "a" | "c" | "d" | "e" | "f" | "h" | "i" | "j", stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"): string

import {render_palette_stop_css} from '@fuzdev/fuz_css/ramps.js';

Renders the derived default of a palette color stop, e.g. --palette_a_50. One definition serves both schemes — the scheme flip lives in the knobs.

`letter`

type "g" | "b" | "a" | "c" | "d" | "e" | "f" | "h" | "i" | "j"

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

returns

string

render_ramp_color_css
#

(hue_reference: string, stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100", alpha?: string | undefined): string

import {render_ramp_color_css} from '@fuzdev/fuz_css/ramps.js';

Renders a color derived from the palette ramps at a stop for an arbitrary hue reference — the shared template behind palette stops and intent stops (--accent_50 renders with var(--hue_accent)).

`hue_reference`

a CSS expression for the hue, e.g. var(--hue_accent)

type string

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

`alpha?`

optional CSS alpha (e.g. 40%) appended inside the oklch()

type string | undefined

optional

returns

string

render_theme_style
#

(theme: Theme, options?: RenderThemeStyleOptions): string import {render_theme_style} from '@fuzdev/fuz_css/theme.js';

`theme`

type Theme

`options`

type RenderThemeStyleOptions

default {}

returns

string

render_theme_variable
#

(variable: { name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; }, dark?: boolean, comments?: boolean): string

import {render_theme_variable} from '@fuzdev/fuz_css/theme.js';

`variable`

type { name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; }

`dark`

type boolean

default false

`comments`

type boolean

default true

returns

string

RenderThemeStyleOptions
#

RenderThemeStyleOptions import type {RenderThemeStyleOptions} from '@fuzdev/fuz_css/theme.js';

`comments?`

type boolean

`id?`

type string | null

`empty_default_theme?`

type boolean

`layer?`

The cascade layer wrapping the rendered variables. Theme overrides default to fuz.theme so they beat the fuz.base defaults by layer order; pass null to render unlayered.

type string | null

resolve_base_css_option
#

css_class_resolution.ts view source

(base_css: BaseCssOption, deps: CacheDeps): Promise<StyleRuleIndex | null> import {resolve_base_css_option} from '@fuzdev/fuz_css/style_rule_parser.js';

Resolves a base_css option to a StyleRuleIndex. Handles all option forms: undefined (defaults), null (disabled), string, or callback.

`base_css`

the base_css option from generator config

type BaseCssOption

`deps`

filesystem deps for loading default CSS

type CacheDeps

returns

Promise<StyleRuleIndex | null>

promise resolving to StyleRuleIndex, or null if disabled

resolve_class_definition
#

(def: CssClassDefinitionStatic, class_name: string, definitions: Record<string, CssClassDefinition | undefined>, css_properties?: Set<...> | null): ResolveComposesResult

import {resolve_class_definition} from '@fuzdev/fuz_css/css_class_resolution.js';

Resolves a class definition's declaration, handling composes composition.

If the definition has a composes property, resolves those classes recursively and combines with any explicit declaration. If no composes, returns the explicit declaration directly.

`def`

the class definition to resolve

type CssClassDefinitionStatic

`class_name`

the name of the class being resolved (for error messages)

type string

`definitions`

record of all known class definitions

type Record<string, CssClassDefinition | undefined>

`css_properties`

set of valid CSS properties for literal validation, or null to skip

type Set<string> | null

default null

returns

ResolveComposesResult

combined declaration or an error

resolve_composes
#

css_class_resolution.ts view source

(class_names: string[], definitions: Record<string, CssClassDefinition | undefined>, resolution_stack: Set<string>, visited: Set<string>, original_class_name: string, css_properties?: Set<...> | null): ResolveComposesResult

import {resolve_composes} from '@fuzdev/fuz_css/css_class_resolution.js';

Resolves an array of class names to their combined CSS declarations.

Recursively resolves nested composes arrays and combines all declarations. Validates that referenced classes exist and are resolvable (not rulesets or interpreters). Supports unmodified CSS literals (e.g., text-align:center) in the composes array.

Deduplication behavior:

Diamond dependencies (class reached via different composition branches) are silently skipped
Redundant listings (class already included by an earlier sibling in this array) emit a warning

`class_names`

array of class names to resolve

type string[]

`definitions`

record of all known class definitions

type Record<string, CssClassDefinition | undefined>

`resolution_stack`

set of class names currently being resolved (for cycle detection)

type Set<string>

`visited`

set of all class names already resolved (for deduplication)

type Set<string>

`original_class_name`

the class name being defined (for error messages)

type string

`css_properties`

set of valid CSS properties for literal validation, or null to skip

type Set<string> | null

default null

returns

ResolveComposesResult

combined declarations or an error

resolve_css
#

(options: CssResolutionOptions): CssResolutionResult import {resolve_css} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Resolves which CSS to include based on detected usage.

Algorithm:

Collect rules: core rules + element-matching + class-matching
Collect variables: from rules, class defs, utility generation, detected vars, additional_variables
Resolve transitive variable dependencies
Generate output: theme_css (light+dark), base_css (source order)

`options`

resolution options including indexes, detected usage, and config

type CssResolutionOptions

returns

CssResolutionResult

resolution result with theme CSS, base CSS, and diagnostics

resolve_variables_option
#

(variables: VariablesOption): { name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; }[]

import {resolve_variables_option} from '@fuzdev/fuz_css/variable_graph.js';

Resolves a variables option to a concrete array of style variables.

`variables`

the variables option (undefined, null, array, or callback)

type VariablesOption

returns

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; }[]

resolved array of style variables, or empty array if null

resolve_variables_transitive
#

css_class_resolution.ts view source

(graph: VariableDependencyGraph, initial_variables: Iterable<string>): ResolveVariablesResult import {resolve_variables_transitive} from '@fuzdev/fuz_css/variable_graph.js';

Resolves variables transitively using DFS with cycle detection. When a variable is requested, all variables it depends on are included. Both light and dark dependencies are always resolved together.

`graph`

the variable dependency graph

type VariableDependencyGraph

`initial_variables`

initial set of variable names to resolve

type Iterable<string>

returns

ResolveVariablesResult

ResolveVariablesResult with all transitive dependencies

ResolveComposesResult
#

ResolveComposesResult import type {ResolveComposesResult} from '@fuzdev/fuz_css/css_class_resolution.js';

Result from resolving a composes array to combined declarations.

ResolveVariablesResult
#

ResolveVariablesResult import type {ResolveVariablesResult} from '@fuzdev/fuz_css/variable_graph.js';

Result from transitive variable resolution.

`variables`

All resolved variable names

type Set<string>

`warnings`

Warning messages for cycles

type Array<string>

`missing`

Variable names that were requested but not found in the graph

type Set<string>

RgbUnit
#

RgbUnit import type {RgbUnit} from '@fuzdev/fuz_css/oklch.js';

An RGB color with components in the unit interval [0, 1]. Values are gamma-encoded sRGB unless a function documents linear-light. Out-of-gamut results are not clamped, so components may fall outside [0, 1].

ruleset_contains_class
#

(rules: ParsedRule[], escaped_class_name: string): boolean import {ruleset_contains_class} from '@fuzdev/fuz_css/css_ruleset_parser.js';

Checks if any selector in the ruleset contains the expected class name. Used to validate that ruleset definitions match their key.

`rules`

parsed rules from the ruleset

type ParsedRule[]

`escaped_class_name`

the CSS-escaped class name (e.g., "clickable" or "hover\\:card")

type string

returns

boolean

true if at least one selector contains ".class_name"

save_cached_extraction
#

(deps: CacheDeps, cache_path: string, content_hash: string, extraction: ExtractionData): Promise<void> import {save_cached_extraction} from '@fuzdev/fuz_css/css_cache.js';

Saves an extraction result to the cache. Uses atomic write (temp file + rename) for crash safety. Normalizes empty collections to null to avoid allocation overhead on load.

`deps`

filesystem deps for dependency injection

type CacheDeps

`cache_path`

absolute path to the cache file

type string

`content_hash`

content hash of the source file contents

type string

`extraction`

extraction data to cache

type ExtractionData

Record<"light" | "dark", LightnessRampKnobs> import {SHADE_LIGHTNESS_KNOBS} from '@fuzdev/fuz_css/ramps.js';

Fitted lightness knobs for the shade (surface) ramps.

shade_max
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {shade_max} from '@fuzdev/fuz_css/variables.js';

shade_min
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {shade_min} from '@fuzdev/fuz_css/variables.js';

shade_scale_variants
#

readonly ["min", "00", "05", "10", "20", "30", "40", "50", "60", "70", "80", "90", "95", "100", "max"] import {shade_scale_variants} from '@fuzdev/fuz_css/variable_data.js';

shade_stop_oklch
#

(stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100", scheme: "light" | "dark"): Oklch

import {shade_stop_oklch} from '@fuzdev/fuz_css/ramps.js';

Computes the default OKLCH color of a shade stop (--shade_NN).

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

`scheme`

type "light" | "dark"

returns

Oklch

shade_variants
#

readonly ["00", "05", "10", "20", "30", "40", "50", "60", "70", "80", "90", "95", "100"] import {shade_variants} from '@fuzdev/fuz_css/variable_data.js';

ShadeScaleVariant
#

SkippedModifierInfo import type {SkippedModifierInfo} from '@fuzdev/fuz_css/css_ruleset_parser.js';

Information about a modifier that was skipped for a selector during ruleset modification. The selector is still included in output, just without the conflicting modifier applied.

`selector`

The specific selector where the modifier was skipped (not the full selector list)

type string

`reason`

Reason the modifier was skipped

type 'pseudo_element_conflict' | 'state_conflict'

`conflicting_modifier`

The conflicting modifier that was not applied (e.g., "::before" or ":hover")

type string

SourceIndex
#

import {SourceIndex} from '@fuzdev/fuz_css/css_class_extractor.js';

Helper class for converting character offsets to line/column positions. Svelte template nodes (Comment, Text, ExpressionTag) only have char offsets, so this class enables efficient conversion.

Build: O(n) where n = source length Lookup: O(log m) where m = number of lines (binary search)

`constructor`

type new (source: string): SourceIndex

`source`

type string

`get_location`

Converts a character offset to a source location.

type (offset: number, file: string): SourceLocation

`offset`

0-based character offset in the source

type number

`file`

file path for the location

type string

returns SourceLocation

SourceLocation with 1-based line and column

SourceLocation
#

SourceLocation import type {SourceLocation} from '@fuzdev/fuz_css/diagnostics.js';

Source location for IDE/LSP integration.

readonly ["xs5", "xs4", "xs3", "xs2", "xs", "sm", "md", "lg", "xl", "xl2", "xl3", "xl4", "xl5", "xl6", "xl7", "xl8", "xl9", "xl10", "xl11", "xl12", "xl13", "xl14", "xl15"]

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {space_xs5} from '@fuzdev/fuz_css/variables.js';

SpaceVariant
#

"lg" | "md" | "sm" | "xs" | "xl" | "xl2" | "xl3" | "xl4" | "xl5" | "xl6" | "xl7" | "xl8" | "xl9" | "xs5" | "xs4" | "xs3" | "xs2" | "xl10" | "xl11" | "xl12" | "xl13" | "xl14" | "xl15"

import type {SpaceVariant} from '@fuzdev/fuz_css/variable_data.js';

split_selector_list
#

(selector_group: string): string[] import {split_selector_list} from '@fuzdev/fuz_css/css_ruleset_parser.js';

Splits a selector list by commas, respecting parentheses, brackets, and quoted strings.

`selector_group`

type string

returns

string[]

examples

split_selector_list('.a, .b') // → ['.a', '.b']
split_selector_list('.a:not(.b), .c') // → ['.a:not(.b)', '.c']
split_selector_list('.a[data-x="a,b"], .c') // → ['.a[data-x="a,b"]', '.c']

STATE_MODIFIERS
#

Map<string, ModifierDefinition> import {STATE_MODIFIERS} from '@fuzdev/fuz_css/modifiers.js';

Map of state modifier names to their CSS output

STYLE_VARIABLE_NAME_MATCHER
#

variable.ts view source

RegExp import {STYLE_VARIABLE_NAME_MATCHER} from '@fuzdev/fuz_css/variable.js';

StyleRule
#

StyleRule import type {StyleRule} from '@fuzdev/fuz_css/style_rule_parser.js';

A parsed style rule with metadata for filtering. Discriminated union: check is_core to narrow to CoreStyleRule or NonCoreStyleRule. All rules have a consistent shape - core_reason is null for non-core rules.

StyleRuleBase
#

StyleRuleIndex import type {StyleRuleIndex} from '@fuzdev/fuz_css/style_rule_parser.js';

Index of parsed style rules for efficient lookup.

`rules`

All rules in original order

type Array<StyleRule>

`by_element`

Rules indexed by element name

type Map<string, Array<number>>

`by_class`

Rules indexed by class name

type Map<string, Array<number>>

`content_hash`

Content hash for cache invalidation

type string

StyleVariable
#

variable.ts view source

ZodObject<{ name: ZodString; light: ZodOptional<ZodString>; dark: ZodOptional<ZodString>; summary: ZodOptional<ZodString>; }, $strip>

import type {StyleVariable} from '@fuzdev/fuz_css/variable.js';

Zod schema for validating StyleVariable objects. Use safeParse for validation; the StyleVariable type is defined separately to preserve the Flavored brand on name.

StyleVariableInfo
#

StyleVariableInfo import type {StyleVariableInfo} from '@fuzdev/fuz_css/variable_graph.js';

Information about a single style variable and its dependencies.

`name`

Variable name (without -- prefix)

type string

`light_deps`

Variables referenced in the light value

type Set<string>

`dark_deps`

Variables referenced in the dark value

type Set<string>

`light_css`

The CSS value for light mode, or undefined if not defined

type string | undefined

`dark_css`

The CSS value for dark mode, or undefined if not defined

type string | undefined

StyleVariableName
#

variable.ts view source

ZodString import type {StyleVariableName} from '@fuzdev/fuz_css/variable.js';

suggest_css_property
#

(typo: string, properties: Set<string> | null): string | null import {suggest_css_property} from '@fuzdev/fuz_css/css_literal.js';

Suggests a correct property name for a typo using Levenshtein distance.

`typo`

the mistyped property name

type string

`properties`

Set of valid CSS properties from load_css_properties() Pass null to skip suggestions.

type Set<string> | null

returns

string | null

the suggested property or null if no close match (Levenshtein distance > 2)

suggest_modifier
#

(typo: string): string | null import {suggest_modifier} from '@fuzdev/fuz_css/css_literal.js';

Suggests a correct modifier name for a typo using Levenshtein distance.

`typo`

the mistyped modifier name

type string

returns

string | null

the suggested modifier or null if no close match (Levenshtein distance > 2)

ternaryClass
#

text_max
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {text_max} from '@fuzdev/fuz_css/variables.js';

text_min
#

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {text_min} from '@fuzdev/fuz_css/variables.js';

text_scale_variants
#

readonly ["min", "00", "05", "10", "20", "30", "40", "50", "60", "70", "80", "90", "95", "100", "max"] import {text_scale_variants} from '@fuzdev/fuz_css/variable_data.js';

text_stop_oklch
#

(stop: "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100", scheme: "light" | "dark"): Oklch

import {text_stop_oklch} from '@fuzdev/fuz_css/ramps.js';

Computes the default OKLCH color of a text stop (--text_NN).

`stop`

type "00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100"

`scheme`

type "light" | "dark"

returns

Oklch

text_variants
#

readonly ["00", "05", "10", "20", "30", "40", "50", "60", "70", "80", "90", "95", "100"] import {text_variants} from '@fuzdev/fuz_css/variable_data.js';

TextScaleVariant
#

"00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100" | "min" | "max" import type {TextScaleVariant} from '@fuzdev/fuz_css/variable_data.js';

Full text scale including min/max extremes for knockout text.

TextVariant
#

"00" | "05" | "10" | "20" | "30" | "40" | "50" | "60" | "70" | "80" | "90" | "95" | "100" import type {TextVariant} from '@fuzdev/fuz_css/variable_data.js';

Theme
#

Theme import type {Theme} from '@fuzdev/fuz_css/theme.js';

`name`

type string

`variables`

type Array<StyleVariable>

theme_knob_by_name
#

Map<string, ThemeKnob> import {theme_knob_by_name} from '@fuzdev/fuz_css/knobs.js';

The catalog indexed by variable name.

theme_knob_hook_names
#

Set<string> import {theme_knob_hook_names} from '@fuzdev/fuz_css/knobs.js';

Names of hook knobs — consumed by style.css via fallbacks, not declared in default_variables. Theme validation unions these with the declared variable names.

theme_knobs
#

ThemeKnob[] import {theme_knobs} from '@fuzdev/fuz_css/knobs.js';

The theme knobs in editor display order: by axis, high leverage first, with the palette tier last within the color axis.

ThemeKnob
#

ThemeKnob import type {ThemeKnob} from '@fuzdev/fuz_css/knobs.js';

`name`

type StyleVariableName

`kind`

type KnobKind

`axis`

type KnobAxis

`leverage`

type KnobLeverage

`tier`

type KnobTier

`range?`

The safe envelope for scalar kinds — editor sliders clamp to it, while direct numeric entry may exceed it knowingly.

type [number, number]

`step?`

type number

`values?`

Allowed values for the enum kind.

type Array<string>

`hook?`

True for knobs consumed by style.css via var() fallbacks instead of being declared in default_variables (e.g. heading_font_weight, whose per-tier fallbacks flatten when set).

type boolean

`bindable?`

True for hue knobs whose default is a palette-letter binding (var(--hue_X)) — the intent and neutral hues. Editors render these as a letter picker with a custom-angle escape, and edits may write either a binding or a literal angle.

type boolean

try_resolve_literal
#

(class_name: string, css_properties: Set<string> | null, context_class_name: string): LiteralResolutionResult import {try_resolve_literal} from '@fuzdev/fuz_css/css_literal.js';

Attempts to resolve a class name as an unmodified CSS literal for composition.

Used by resolve_composes to support literals in composes arrays. Returns the declaration if successful, null if not a literal, or an error if it's a literal with issues (modifiers, invalid property, etc.).

`class_name`

the class name to try resolving

type string

`css_properties`

set of valid CSS properties, or null to skip validation

type Set<string> | null

`context_class_name`

the class being defined (for error messages)

type string

returns

LiteralResolutionResult

resolution result with declaration, or error, or null if not a literal

VariableDependencyGraph
#

VariableDependencyGraph import type {VariableDependencyGraph} from '@fuzdev/fuz_css/variable_graph.js';

Dependency graph for style variables.

`variables`

Map from variable name to its info

type Map<string, StyleVariableInfo>

`content_hash`

Content hash for cache invalidation

type string

VariablesOption
#

vite_plugin_fuz_css.ts view source

VariablesOption import type {VariablesOption} from '@fuzdev/fuz_css/css_plugin_options.js';

Type for the variables option used by CSS generators.

Supports four forms:

undefined - Use default variables (framework defaults)
null - Disable theme generation entirely (explicit opt-out)
Array<StyleVariable> - Custom variables array (replaces defaults)
(defaults) => Array<StyleVariable> - Callback to modify defaults

See module documentation for the undefined vs null convention.

vite_plugin_fuz_css
#

(options?: VitePluginFuzCssOptions): Plugin<any> import {vite_plugin_fuz_css} from '@fuzdev/fuz_css/vite_plugin_fuz_css.js';

Creates the fuz_css Vite plugin.

Extracts CSS classes from source files during Vite's transform phase and generates optimized CSS via the virtual:fuz.css virtual module.

`options`

type VitePluginFuzCssOptions

default {}

returns

Plugin<any>

VitePluginFuzCssOptions
#

vite_plugin_fuz_css.ts view source

VitePluginFuzCssOptions import type {VitePluginFuzCssOptions} from '@fuzdev/fuz_css/vite_plugin_fuz_css.js';

Options for the fuz_css Vite plugin. Extends the shared base options (no additional Vite-specific options currently needed).

inheritance

extends: CssGeneratorBaseOptions

wcag_contrast_ratio
#

wcag.ts view source

(a: RgbUnit, b: RgbUnit): number import {wcag_contrast_ratio} from '@fuzdev/fuz_css/wcag.js';

Computes the WCAG 2.x contrast ratio between two gamma-encoded sRGB colors, in [1, 21] regardless of argument order.

`a`

type RgbUnit

`b`

type RgbUnit

returns

number

Z_INDEX_MAX
#