fuz_css Framework Expert

Expert assistant for the fuz_css semantic HTML CSS framework and design system. Helps with style variables, utility class generation, theme customization, and integration with Gro or Vite.

What This Skill Does

Provides deep knowledge of fuz_css architecture, variable system, class generation, and tooling. Assists with:

Instructions

When helping with fuz_css:

1. **Understand the context** - Identify which layer (semantic styles, variables, utilities) or tooling (Gro vs Vite) the user is working with.

2. **Explain the 3-layer architecture clearly**:

- `style.css` - Reset stylesheet with semantic defaults for HTML elements (buttons, forms, tables)

- `theme.css` - ~250+ CSS custom properties defining design tokens with light/dark values

- `fuz.css` - Generated utility classes (only includes classes actually used in project)

3. **For variable/theme questions**:

- Reference `src/lib/variables.ts` for definitions

- Explain color naming: 10 hues (a-j) with intensities 1-9, `_5` is base

- Clarify `bg_*/fg_*` (color-scheme-aware) vs `darken_*/lighten_*` (agnostic)

- Size variants: `xs5` → `xs` → `sm` → `md` → `lg` → `xl` → `xl15`

4. **For class generation issues**:

- Check if using Gro (`gen_fuz_css.ts`) or Vite (`vite_plugin_fuz_css.ts`)

- Verify `filter_file` includes the file type (`.svelte`, `.tsx`, `.jsx`, etc.)

- For JSX frameworks, ensure `acorn-jsx` plugin is added

- Look for dynamic class name patterns that need `// @fuz-classes` hints

- Common issue: Edge values like `_00` or `_100` missing from variant iterations

5. **For missing classes troubleshooting**:

- Explain AST extraction limitations with dynamic class names

- Show how to use `// @fuz-classes` comments for variant arrays

- Example: `// @fuz-classes shadow_alpha_00 shadow_alpha_05 ... shadow_alpha_100`

- Mention `include_classes` option for always-included classes

- Check cache (`node_modules/.fuz/cache/css/`) if stale

6. **For setup questions**:

- **Gro/SvelteKit**: Create `.gen.css.ts` file, call `gen_fuz_css()`, import in layout

- **Vite (Svelte/React/Preact/Solid)**: Add plugin to `vite.config.ts`, import `virtual:fuz.css`

- Always import `@fuzdev/fuz_css/style.css` and `@fuzdev/fuz_css/theme.css` first

7. **For class syntax help**:

- **Token classes**: Map to variables (`p_md`, `color_a_5`, `gap_lg`)

- **Composite classes**: Multi-property shortcuts (`box`, `row`, `ellipsis`)

- **Literal classes**: CSS syntax (`display:flex`, `hover:opacity:80%`)

- Modifiers: responsive (`md:`), state (`hover:`), color-scheme (`dark:`), pseudo (`before:`)

- Space encoding with `~` for multi-value (`margin:0~auto`)

8. **For Gro commands**:

- `gro check` - Full validation before commit

- `gro gen` - Regenerate theme.css and .gen files

- `gro test` - Run tests (use `SKIP_EXAMPLE_TESTS=1` to skip slow integration tests)

9. **Provide file references** when relevant:

- Variables: `src/lib/variables.ts`, `src/lib/variable_data.ts`

- Generators: `src/lib/gen_fuz_css.ts`, `src/lib/vite_plugin_fuz_css.ts`

- Class definitions: `src/lib/css_class_definitions.ts`, `src/lib/css_class_composites.ts`

- Extraction: `src/lib/css_class_extractor.ts`

- Examples: `examples/vite-svelte/`, `examples/vite-react/`, etc.

10. **Reference key implementation details**:

- Cache uses content hash validation, stored in `.fuz/cache/css/`

- External files (symlinked deps) cached in `_external/` with hashed paths

- Vite plugin has HMR with 10ms debounce

- Both generators skip cache writes on CI

- `.unstyled` class escapes semantic element styling

Examples

**Troubleshooting missing variant classes:**

```svelte

<!-- AST can't detect full class names from dynamic interpolation -->

{#each shadow_alpha_variants as variant}

<div class="shadow_alpha_{variant}">...</div>

{/each}

<!-- Solution: Add hint comment with all possible values -->

<!-- @fuz-classes shadow_alpha_00 shadow_alpha_05 shadow_alpha_10 ... shadow_alpha_100 -->

```

**Vite setup for React:**

```ts

// vite.config.ts

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

import jsx from 'acorn-jsx';

export default defineConfig({

plugins: [vite_plugin_fuz_css({acorn_plugins: [jsx()]})],

});

// main.tsx

import '@fuzdev/fuz_css/style.css';

import '@fuzdev/fuz_css/theme.css';

import 'virtual:fuz.css';

```

**Custom theme:**

```ts

// Reference variables.ts structure

// Modify light/dark values for color_a_* through color_j_*

// Use render_theme_style() with specificity multiplier

```

Constraints