api #

How far in degrees the accent hue has to sit from each status hue before validate_theme stops warning. At the chroma links and labels render at, 12 degrees reads as one color with a shift (a red accent beside the default orange caution) while 30 reads as two (a pink accent beside the default red negative), so the threshold sits between them. The defaults' closest accent and status pair, blue and cyan, is 40 degrees apart.

Acorn plugin type - a function that extends the Parser class.

All modifier names for quick lookup.

Map of ancestor modifier names to their CSS output

Overlays a theme's variables onto a resolved variable set, last-wins by name.

This is how a theme is baked in at build time: the overlaid values flow through the dependency graph like any other, so the variables a theme references are pulled in transitively and the output stays tree-shaken. A stanced theme's scheme_mirror applies first, matching the renderer's order

• and a stanced theme arriving without its mirror computed is resolved

through resolve_theme_stance here, so a hand-rolled theme bakes the same as the shipped exemplars (build time has no bundle-weight concern). A theme slot the stylesheet can't hold is dropped before it overlays, as render_theme_style drops it, so the value beneath it stays.

The default theme - inherits every base default variable.

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, and CssOutputOptions.base_css for what the generators do with the stylesheet.

Base diagnostic with common fields.

The border family's chroma as a multiple of --neutral_chroma - borders carry a stronger tint than surfaces so they read at low alpha. In CSS this is --border_color_chroma: calc(var(--neutral_chroma) * <multiple>).

Alpha (in %) of each border color stop. A perceptually-uniform curve - small gaps at the low end, large at the high end - boosted at the low end in dark mode where borders are less visible against dark backgrounds. Stop 00 renders transparent and stop 100 opaque.

OKLCH lightness of the border color family (--border_color_lightness), fitted from the HSL palette. Sits mid-ramp so borders read against both the page background and fills.

Computes the default OKLCH color of the border family (without alpha).

Border radii in rem, before the --radius_scale multiplier.

Builds a dependency graph from an array of style variables.

The graph is what the bundled theme CSS renders from, verbatim, so it applies the containment checks render_theme_style does: a slot whose value could end its own declaration (or is blank), or a variable whose name isn't a plain identifier, is left out and reported as an uncontained_theme_value error rather than written into the stylesheet.

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

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

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.

Cached extraction result for a single file. Uses null instead of empty arrays to avoid allocation overhead.

Checks if a value contains a possibly invalid calc expression.

Runs the gamut, monotonicity, and contrast gates against a theme, resolving its authored CSS back to numbers through the resolution core. Report-only: failures land in entries (with pass: false), inputs that can't be evaluated land in unchecked, and ok is true only when every entry passes and nothing is unchecked. Never throws.

Every color a gate reads is looked up by its variable name, so a theme that authors one directly - a stop (palette_a_50, shade_00, text_max, border_color_30) or a role (text_color, link_color, border_color) - is measured at the authored color when it is an oklch(L C H) numeric literal or an exact var() reference to another color the gates evaluate, and recorded in unchecked otherwise. An authored color a gate depends on never passes unread, and one no gate reads stays out of the report.

A contrast subject names what was measured: the default stop while a role is at its default (text_80 on shade_00), the role once the theme authors it (text_color on shade_00).

An intent stop that renders the same color as a palette letter's (the default for every intent) folds into that letter's gamut entry rather than duplicating it, so reports for letter-bound themes list fewer subjects than the full letters × intents grid.

Knobs for the symmetric mid-peaked chroma curve, C(t) = min + (max - min) * pow(4t(1-t), curve). The curve expresses the *request*; rendered stops are clamped by PALETTE_CHROMA_CAPS per stop, and --chroma_scale multiplies above the clamp (so vivid themes can knowingly push past the caps and gamut-clip).

Collects all CSS variables used by the included rules.

Recomputes a theme's per-stop worst-hue chroma caps from its own hues and the palette lightness each stop resolves to, then emits palette_chroma_NN overrides wherever the baked caps no longer fit - the fix for a theme (rotated hues, a monochrome collapse, a moved lightness ramp) whose gamut headroom the baked worst-hue table misjudges.

Each stop's cap is computed at the lightness the resolution core resolves for palette_lightness_NN in that scheme - a pinned intermediate stop when the theme pins one, the endpoint-and-curve ramp otherwise - so the caps describe the same colors check_theme gates.

A stop is emitted when either scheme's recomputed cap is tighter than the baked value, or looser by more than the emit epsilon, and the theme doesn't already pin that stop. Nothing is emitted when a hue fails to resolve to a number, since caps computed without it could overshoot its gamut, and a stop whose lightness fails to resolve is skipped. An override emits both slots together, so a one-scheme override can't silently kill the base default's other slot by cascade-layer order, collapsing to a single slot in the base position when the two rendered values coincide.

A stanced theme's two schemes resolve to the stanced appearance through the mirror, so its caps are baselined against the stanced scheme's baked table - the values the mirror already re-slots - and a stance alone (hues and lightness unmoved) emits nothing. Its overrides coincide across schemes and emit single-slot unless the theme authors a dark slot that splits them. A stanced theme's scheme_mirror is recomputed over the emitted variables, so the output is render-ready even when the input wasn't resolved.

The caps bound the requested chroma only: chroma_scale and the per-slot *_chroma_scale multipliers apply above the clamp. A theme that raises one past 1 clips by design - its gamut failures survive the compile, and a cap the compile loosens can add to them, since the multiplier then pushes more stops past the looser cap. The input theme is never mutated. The report re-checks the emitted theme, whose compiled-cap overrides the resolution core recognizes.

The output of compile_theme: the emitted theme plus its lint and gate report.

Composes a base theme with overlay fragments by flatten + last-wins: later variables replace same-named earlier ones wholesale, a dark-only overlay keeping the light slot beneath it (see overlay_style_variable). Any knob-only theme is already a valid fragment - the contrast modifiers in contrast_modifiers are the canonical overlays. This is the hand-flatten precursor to a first-class extends, with the same merge semantics.

The base's scheme stance wins; when the base is single-scheme, each overlay variable is re-slotted to the stanced scheme's value so a dual-slot fragment can't leak the other scheme's appearance past the stance. The base's scheme_mirror carries through minus any names the overlays set - the mirror was computed against the base's own variables, so entries for newly composed names would shadow nothing but still render

• and overlay values win over the remaining mirror by source order.

The composed name appends the overlay names so name-keyed pickers and renderers treat the composition as its own theme, and the base's summary carries through.

Computes the worst-hue safe chroma cap at one lightness: the minimum oklch_max_srgb_chroma across the hues, floored to 4 decimals to stay conservative (the browser clips anything past it). The generalization of the baked PALETTE_CHROMA_CAPS to an arbitrary hue set and lightness - a theme's compile step calls it with each stop's own resolved lightness to detect where the baked worst-hue envelope no longer fits.

The contrast modifiers: small axis fragments composed over any theme via compose_themes rather than picked as themes themselves. Composition is flatten + last-wins, so a modifier's variables replace the base theme's same-named ones - a base that moves the same knobs cedes them to the modifier. Both move the shade endpoint (shade_lightness_00), since contrast is the ground-to-text range, so a theme whose identity is its ground yields it. High contrast also bends the text curve (text_lightness_curve) and sets border_color to a stop that holds a control's boundary against a ground its fill can no longer separate from

• a base with its own border_color cedes it like any other variable,

stronger rules included. Neither touches the neutral cast, which stays the theme's.

Reasons a rule is considered "core" and always included. conditional_core marks a conditional group rule (@media, @supports, @container) that contains something which always ships on its own - a core rule or an at_rule. at_rule marks every at-rule that is not a conditional group (@keyframes, @font-face, @property, @scope, ...): detection has no way to tell whether one is used, so it ships as written. untargetable marks rules with a selector the index can't match - one that names no element or class at all (pseudo-element or attribute selectors like ::selection and [hidden]), or one with an escaped or non-ASCII identifier (.md\:flex, .café) - so tree-shaking would drop them whether or not the project uses them.

A core style rule that is always included in output.

Builds the bundled CSS resources from generator options. The style-rule index is always built, even when only theme output is enabled - from the default style.css unless base_css supplies a stylesheet.

Creates the cache-path lookup the generators share: a file's cache path under cache_dir in project_root, or null on CI, where nothing is cached.

Creates the core a generator renders through.

Creates the diagnostic dispatch a generator runs after each render: a diagnostic level set to 'throw' fails the render with a CssGenerationError, and the rest are logged to sink - except that a message the previous dispatch already logged isn't logged again.

A render reports every file's diagnostics, so a dev server or watch mode re-rendering on each edit would otherwise repeat every warning in the project on every change. A diagnostic that goes away and comes back is logged again.

Converts an InterpreterDiagnostic to a GenerationDiagnostic with locations.

Creates a StyleRuleIndex from the stylesheet a base_css option supplies, reporting a value that can't be parsed as a base_css problem.

Creates a ThemeKnobResolver for theme, sharing the resolution core used by validate_theme/check_theme/compile_theme. The instance memoizes per name+scheme, so repeated lookups (a UI rendering every knob) stay cheap - create one per theme value and discard when the theme changes.

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). v7: Add extraction_key, so a change to acorn_plugins or cache_salt misses.

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

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).

Checks that text can sit inside a CSS comment without closing it.

Checks that a custom property name is a plain identifier, so it can't smuggle a value or a second declaration in with it.

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

A CSS <number> as a pattern source, stricter than what Number() accepts - no hex, binary, Infinity, or empty string.

Checks that a declaration value can't end its own declaration or rule: quotes and brackets balance, and nothing outside a string closes the declaration (a top-level ;), opens or closes a block, sets !important, opens a comment, or escapes a character. Stricter than the grammar where that keeps the rule simple - braces, comments, and escapes outside strings are rejected outright, as is an unquoted url( whose contents a quoted one would hold, so quote a URL that needs them.

Options for cache behavior.

Full union including interpreters.

Pure utility composition (composes only).

Custom CSS declaration (optionally seeded with composes).

Interpreter for dynamic CSS class generation based on pattern matching.

Full ruleset with selectors.

Static definitions (not interpreter-based).

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.

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

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

Options for error and warning handling.

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

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.

A generator's shared core - see create_css_generator.

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

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

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) { ... }

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

What one render reads: the classes extracted so far and the var() names scanned from source.

Options for CSS resolution.

Result from CSS resolution.

Statistics from CSS resolution (only included when include_stats is true).

Default filesystem deps using node:fs/promises.

Default cache directory relative to project root.

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, 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 registered themes from shipped exemplars. The registry holds the plain working themes: the base and themes/ledger.ts (compact, cool, for tools used all day).

The exemplars deliberately stay out of this list. Each takes one channel to carry the structure and quiets the rest, and is named for the artifact that already looks that way: themes/zine.ts (line and weight), themes/pebble.ts (depth and softness), themes/parchment.ts (type and ruling), themes/phosphor.ts (packing, dark-only), themes/guestbook.ts (controls as beveled objects), themes/marquee.ts (color, dark-only and the one palette-tier exemplar), and themes/signage.ts (scale and weight, for legibility).

Contrast is not a theme: the low/high contrast pair are modifiers (contrast_modifiers) composed over any theme with compose_themes.

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

Deletes a cached extraction file. Best-effort: every unlink error is swallowed, not just not_found - the cache is disposable and callers delete fire-and-forget.

Union of all diagnostic types.

How generation diagnostics are handled - see CssDiagnosticsOptions.

Where a dispatcher writes the diagnostics it logs.

Layout distances in px - breakpoint-ish widths, insensitive to font size.

Transition durations in seconds, from a UI beat to a slow ambient sweep.

Serializes a string as a CSS identifier, so any string can name an element id in a selector ('#' + escape_css_identifier(id) matches the element whose id attribute is that string). Follows the CSSOM identifier serialization, except that ASCII punctuation is escaped by code point (\3c ) rather than with a bare backslash, since \</style still closes a <style> element - the output can't end its rule or its element.

Escapes special characters in a CSS class name for use in a selector. CSS selectors require escaping of characters like :, %, (, ), etc.

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.

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

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

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

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.

Extracts the custom properties a CSS string declares.

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

Extracts CSS classes from a Svelte file using AST parsing.

Extracts CSS classes from a TypeScript/JS file using AST parsing.

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

Extracts the CSS variables a string references with no fallback - the ones that must be defined for the value to resolve. var(--a, 1px) can't resolve to nothing, so a is left out, while the b in var(--a, var(--b)) is required.

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

Options for CSS class extraction.

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

Cacheable extraction data fields shared between extraction and caching layers. Uses null instead of empty collections to avoid allocation overhead.

Diagnostic from the extraction phase.

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.

Filter function to determine which files to process for CSS class extraction. The generators pass each file's absolute id and the project root (Vite's root, Gro's project_root), so a filter can judge a path by where it sits in the project rather than where the project sits on disk. A filter that ignores the root keeps working.

Default file filter for CSS class extraction. Includes .svelte, .html, .ts, .js, .tsx, .jsx files, and .css files for their variable references (see is_css_file) - except a CSS id with a query, like the Foo.svelte?svelte&type=style&lang.css id of a Svelte component's styles, which its .svelte file already covers. Excludes test files (.test.ts, .spec.ts) and generated files (.gen.ts). Excludes files in test directories (test/, tests/, __tests__/, __mocks__/), judged inside the project or the dependency's package (see to_filter_scope), so a project checked out under a test/ directory still extracts.