Imported from henriques4nti4go/fuse-ui (AGENTS.md). Install upstream with npx skills add henriques4nti4go/fuse-ui. Copyright stays with the author.

Fuse UI — Agent Guide

Style compiler + React component library. Utilities in className compile to hashed static CSS at build time (zero CSS runtime). Public npm package: fuse-ui.

Monorepo layout

packages/
  fuse/       Public umbrella (re-exports) — consumers install this only
  core/       Compiler (AST transform, UnoCSS engine, CSS generation)
  theme/      fusion global tokens + defineConfig for fuse.config.ts
  react/      React components, primitives, stories
  vite/       Vite plugin (wires compiler into apps)
  next/       Next.js / webpack plugin (withFuseUI wrapper)
apps/
  playground/ Local demo (Vite)
  storybook/  Component docs (port 6006)

Consumer setup

yarn add fuse-ui

// ── Vite / TanStack Start ──────────────────────────
// vite.config.ts
import { fuse } from 'fuse-ui/vite'

// main.tsx
import 'virtual:fuse-ui.css'

// ── Next.js ────────────────────────────────────────
// next.config.ts
import { withFuseUI } from 'fuse-ui/next'
export default withFuseUI({})

// app/layout.tsx (or pages/_app.tsx)
import 'fuse-ui/styles'

// fuse.config.ts (optional)
import { defineConfig } from 'fuse-ui/theme'

// App
import { Button, fusion } from 'fuse-ui'
import { Search } from 'fuse-ui/icons'

Scripts

Component map

Each UI component lives in its own folder under packages/react/src/components/ or primitives/.

Folder structure (per component)

components/button/
  button.tsx           Component
  button.types.ts      Props + variant types
  button.variants.ts   CVA definitions (inline Tailwind strings)
  button.stories.tsx   Storybook
  index.ts             Barrel export

Icons

• Lucide re-exported at fuse-ui/icons (packages/react/src/icons/index.ts)
• Internal components import from ../../icons/index.js
• Do not use a name-based icon registry — pass LucideIcon to <Icon icon={...} />

Global design tokens (fusion)

File: packages/theme/src/fusion.ts

Component-specific styles live co-located as string literals in *.variants.ts or *.tsx — not in fusion.ts.

Fusion style

Default palette uses zinc neutrals with black primary (primary = zinc-900).

Form fields: border-solid border-zinc-200 rounded-md focus-visible:ring-primary

Button primary: bg-primary text-zinc-50 (black button, white text)

Use zinc-* not gray-* for new components.

Styling rules (compiler)

The Fuse compiler (packages/core) only compiles:

• String literals in className, cn(), and cva()
• fusion.* member expressions

Do not extract classes to const variables — the compiler won't resolve them. Group with cn():

cva(cn(
  'flex w-full',
  'rounded-md border border-solid border-zinc-200',
))

Variants (hover:, focus:, disabled:, responsive) are supported. Vite plugin must process .ts and .tsx files (including *.variants.ts).

Conventions for new components

1. Create folder under components/<name>/ with *.tsx, *.types.ts, *.variants.ts (if variants), *.stories.tsx, index.ts
2. Use Radix primitives when accessibility matters (Dialog, Select pattern)
3. Use CVA + inline Tailwind strings for variants
4. Form fields: border border-solid border-zinc-200, rounded-md, focus-visible:ring-primary
5. Export from packages/react/src/index.ts (auto-available via fuse-ui)
6. Exclude *.stories.tsx from tsconfig.build.json
7. Fast Refresh: .tsx files should export only React components (move Radix re-exports to index.ts)

Internal packages (do not publish separately)

Local development link

# in fuse-ui monorepo
yarn build:packages && cd packages/fuse && yarn link

# in consumer project (package.json must list "fuse-ui": "*")
yarn link fuse-ui

Alternative: "fuse-ui": "file:../fuse-ui/packages/fuse" in consumer package.json.