@imfusion/web-ui 0.5.1-dev.2.gf11bbed1 → 0.5.1-dev.20.g9170acaf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.5.1-dev.2.gf11bbed1",
+  "version": "0.5.1-dev.20.g9170acaf",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "license": "UNLICENSED",
@@ -9,10 +9,17 @@
     "access": "restricted"
   },
   "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "imports": {
+    "#/*": "./src/*",
+    "#/storybook/*": "./.storybook/*"
+  },
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "web-ui-install-skills": "./bin/install-skill.js"
+    "web-ui-install": "bin/install.js"
   },
   "exports": {
     ".": {
@@ -23,6 +30,10 @@
       "types": "./dist/integrations/*/index.d.ts",
       "import": "./dist/integrations/*.js"
     },
+    "./build/*": {
+      "types": "./dist/build/*/index.d.ts",
+      "import": "./dist/build/*.js"
+    },
     "./styles.css": "./dist/style.css",
     "./docgen.json": "./src/docgen/doc.gen.json",
     "./llms.txt": "./src/llms/llms.gen.txt",
@@ -36,37 +47,35 @@
     "bin"
   ],
   "scripts": {
-    "codegen:docgen": "tsx src/docgen/gen-docgen.ts",
-    "codegen:llms": "tsx src/llms/gen-llms.ts",
-    "codegen:watch": "tsx watch src/codegen/run.ts",
-    "codegen:storybook": "tsx src/codegen/run.ts --storybook",
-    "codegen": "tsx src/codegen/run.ts",
-    "build": "npm run codegen && rm -rf dist && vite build && npm run codegen:docgen && npm run codegen:llms",
     "dev": "tsx scripts/dev.ts",
     "dev:host": "tsx scripts/dev.ts --host",
     "dev:lib": "concurrently -n codegen,lib -c yellow,blue \"npm run codegen:watch\" \"vite build --watch\"",
-    "typecheck": "npm run codegen && tsc -p tsconfig.lib.json --noEmit && tsc -p .storybook/tsconfig.json --noEmit",
+    "build": "npm run codegen && rm -rf dist && vite build && npm run codegen:docgen && npm run codegen:llms",
+    "build:storybook": "npm run codegen:storybook && storybook build",
+    "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open",
+    "storybook:free-ports": "tsx scripts/free-storybook-ports.ts",
+    "codegen": "tsx src/codegen/run.ts",
+    "codegen:watch": "tsx watch src/codegen/run.ts",
+    "codegen:storybook": "tsx src/codegen/run.ts --storybook",
+    "codegen:docgen": "tsx src/docgen/gen-docgen.ts",
+    "codegen:llms": "tsx src/llms/gen-llms.ts",
+    "verify:format": "prettier --check .",
+    "verify:lint": "eslint . --cache --max-warnings=0",
+    "verify:typecheck": "npm run codegen && tsc -p tsconfig.lib.json --noEmit && tsc -p .storybook/tsconfig.json --noEmit",
+    "verify:tests": "vitest run",
+    "verify:deps": "tsx scripts/check-pinned-dependencies.ts",
+    "verify:staged": "tsx scripts/verify/staged.ts",
+    "verify:full": "tsx scripts/verify/full.ts && npm run verify:tests",
     "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "eslint . --cache --max-warnings=0",
-    "lint:fix": "eslint . --cache --fix",
+    "lint": "eslint . --cache --fix",
     "lint:inspect": "npx @eslint/config-inspector@latest",
+    "test:unit": "vitest run --project unit",
+    "test:stories": "vitest run --project storybook",
+    "test:watch": "vitest",
     "skills:eval": "node src/llms/evals/run.mjs",
     "skills:eval:dev": "WEB_UI_SKILL_EVAL_ROOT=/private/tmp/web-ui-dev-skill-evals WEB_UI_SKILL_EVAL_RESULTS_DIR=.agents/evals/results WEB_UI_SKILL_EVAL_REPORT_PATH=.agents/evals/REPORT.md WEB_UI_SKILL_EVAL_SKILL_FAMILY=web-ui-dev WEB_UI_SKILL_EVAL_WORKSPACE_LABEL='development repository' node src/llms/evals/run.mjs --scenarios-dir .agents/evals/scenarios --setup .agents/evals/setup-env.sh",
     "skills:eval:compare": "node src/llms/evals/compare.mjs",
     "skills:eval:report": "node src/llms/evals/report.mjs",
-    "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open",
-    "storybook:free-ports": "tsx scripts/free-storybook-ports.ts",
-    "build:storybook": "npm run codegen:storybook && storybook build",
-    "test": "vitest run",
-    "test:unit": "vitest run --project unit",
-    "test:stories": "vitest run --project storybook",
-    "test:watch": "vitest",
-    "verify:preflight": "tsx scripts/verify/full.ts",
-    "verify:full": "npm run verify:preflight && npm run test",
-    "worktree:create": "tsx scripts/worktrees.ts create",
-    "worktree:close": "tsx scripts/worktrees.ts close",
-    "worktree:discard": "tsx scripts/worktrees.ts discard",
     "knip": "knip",
     "git:config": "git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only"
   },
@@ -124,6 +133,7 @@
     "globals": "15.15.0",
     "jiti": "2.7.0",
     "knip": "6.14.2",
+    "lightningcss": "1.32.0",
     "nano-staged": "1.0.2",
     "playwright": "1.60.0",
     "prettier": "3.8.3",

package/src/docgen/doc.gen.json

@@ -1281,7 +1281,7 @@
         {
           "name": "variant",
           "required": false,
-          "type": "| \"inherit\"\n| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| null",
+          "type": "| \"inherit\"\n| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"oncolor\"\n| null",
           "defaultValue": "brand",
           "description": ""
         }

package/src/llms/skills/imf-web-ui/SKILL.md

@@ -2,8 +2,8 @@
 name: imf-web-ui
 description:
   "Entry point for UI work in a project that depends on @imfusion/web-ui. Decides whether guidance is needed at all, then
-  routes to the right companion skill — component reference, UX guidance, or frontend patterns. Load when adding or editing
-  UI in a consumer repo."
+  routes to the right companion skill — component reference, UX guidance, or frontend conventions. Load when adding or
+  editing UI in a consumer repo."
 ---
 
 # imf-web-ui
@@ -24,16 +24,17 @@ Guidance skills exist to fill gaps, not to add ceremony to clear tasks.
 
 ## Routing
 
-| The task at hand                                                                                      | Open                                 |
-| ----------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| Using a specific component; checking props, sub-components, or defaults                               | `imf-web-ui-components`              |
-| First-time setup, adding a library dependency, or components rendering unstyled/broken                | `imf-web-ui-setup`                   |
-| Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states  | `imf-web-ui-ux`                      |
-| Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing     | `imf-web-ui-frontend-patterns`       |
-| Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure | `imf-web-ui-imfusion-frontend-setup` |
+| The task at hand                                                                                          | Open                              |
+| --------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| Using a specific component; checking props, sub-components, or defaults                                   | `imf-web-ui-components`           |
+| First-time setup, adding a library dependency, or components rendering unstyled/broken                    | `imf-web-ui-library-setup`        |
+| Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states      | `imf-web-ui-ux`                   |
+| Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing         | `imf-web-ui-frontend-conventions` |
+| Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure     | `imf-web-ui-frontend-setup`       |
+| Setting up or refreshing agent tooling: vendored skills, lifecycle hooks, dependency-shipped Agent Skills | `imf-web-ui-agent-setup`          |
 
-The last row is narrow on purpose. It's for "what is this project missing?" — a question about the repo as a whole. Being
-asked to add one config file is just that edit; make it, and don't open a skill to do so.
+The two setup rows are narrow on purpose. They're for "what is this project missing?" — a question about the repo as a whole.
+Being asked to add one config file is just that edit; make it, and don't open a skill to do so.
 
 Tasks routinely span two: building a screen usually means `imf-web-ui-ux` for the shape and `imf-web-ui-components` for the
 APIs. That's normal — open both, in that order.
@@ -43,6 +44,9 @@ APIs. That's normal — open both, in that order.
 TanStack is the recommended tooling library — routing, server state, forms, tables. When a task needs one of those and the
 project has no incumbent, propose it, and read the library's own docs (`npx @tanstack/cli`) rather than working from memory.
 
+Much of the suite also ships Agent Skills inside the package, reachable via TanStack Intent. Wiring that up is
+`imf-web-ui-agent-setup`.
+
 ## When to interview the human
 
 `imf-web-ui-ux` contains a short per-feature interview. Run it **only** when both hold:

package/src/llms/skills/imf-web-ui-agent-setup/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: imf-web-ui-agent-setup
+description:
+  "Install or update the LLM/agent tooling @imfusion/web-ui ships in a consumer repo: the vendored imf-web-ui-* skills, the
+  AGENTS.md fence, the agent lifecycle hooks, and the staleness wiring. Also covers reaching the Agent Skills a dependency
+  ships — TanStack Intent (@tanstack/intent) and its allowlist. Wraps npx web-ui-install and adds the judgment the binary
+  can't have — reading what the repo already registers before adding anything. Load when setting up agent tooling in a
+  consumer app, when skills are stale, when hooks should be installed or adapted, or when asked to set up TanStack Intent or
+  dependency-shipped Agent Skills. Not for project tooling (imf-web-ui-frontend-setup) or library wiring
+  (imf-web-ui-library-setup)."
+---
+
+# imf-web-ui-agent-setup
+
+Sets up or updates the agent side of a consumer repo. The binary does the mechanics; this skill does the judgment.
+
+## Skills
+
+`npx web-ui-install` installs or refreshes the vendored `imf-web-ui-*` skills (interactive target choice on first run,
+remembered after; `--reconfigure` re-opens it). It also refreshes the `<!-- imf-web-ui:begin/end -->` fence in an existing
+`AGENTS.md`. Stale check: `.imf-web-ui-skill-version.json` in each installed skill vs. the installed package version — older
+marker means re-run the binary, never hand-diff skill contents.
+
+## Hooks
+
+Three agent lifecycle hooks ship as templates in [`templates/hooks/`](templates/hooks/), registration in
+[`templates/settings.json`](templates/settings.json):
+
+- **SessionStart** — once per session: the conventions baseline is vendored, load it before writing.
+- **UserPromptSubmit** — a one-line conventions reminder per prompt. Per-prompt, not per-tool-call: a PreToolUse reminder
+  would re-inject the same text on every edit.
+- **PostToolUse** (advisory) — file-scope checks on the touched file after every Edit/Write, failures fed straight back.
+  Never exits non-zero.
+- **`baseline-staleness.sh`** — not registered as an agent hook; the repo's pre-commit calls it
+  ([`git.md`](../imf-web-ui-frontend-conventions/references/git.md), Staleness at commit time).
+
+**Read `.claude/settings.json` before installing.** Then pick per event:
+
+- **Nothing registered** → install as shipped: `npx web-ui-install --hooks` copies the scripts to `.agents/hooks/imf-web-ui/`
+  (installer-owned, refreshed wholesale) and merges the registrations without touching existing entries.
+- **The repo already covers an event** (its own session reminder, its own post-edit verify) → don't stack a second hook on
+  it. Use the template as a starting point instead: fold the missing behaviour into the repo's existing script, or adapt the
+  template and register that. Surface the situation and let the human pick.
+
+## Dependency-shipped skills
+
+Some libraries ship Agent Skills inside their npm package; TanStack does across much of the suite.
+[TanStack Intent](https://github.com/TanStack/intent) (`@tanstack/intent`) is the CLI that surfaces them — an agent holding a
+dependency but not its guidance writes plausible code against a half-remembered API.
+
+Setting it up is the project's own call, not something web-ui does on its behalf. Point it out:
+
+> This project has TanStack dependencies that ship their own Agent Skills. `@tanstack/intent` can make them reachable — worth
+> a look if you want your agent working from the library's own guidance.
+
+Intent offers two things: a fenced instructions block in `AGENTS.md`, and a `PreToolUse` hook that blocks an edit until a
+matching skill has been read. The house preference is both — the block alone is advice an agent can walk past. The hook
+refuses every edit while no matching skill is loadable, so a project adopting it wants the current docs open; that sequencing
+belongs to whoever runs it.
+
+**Allowlist the whole scope.** `intent.skills` takes `@tanstack/*`. Per-package entries like `@tanstack/react-query` look
+more precise and silently reach almost nothing, because the skills ship from packages the app never names directly. Exclude
+`@tanstack/devtools-event-client` — it publishes skills that are noise in an app repo.
+
+Read Intent's own docs before wiring it; it is young and moves. Whatever the project decides, guidance you didn't read is not
+guidance you have: use `npx @tanstack/cli` for TanStack docs, and never guess at a skill name.
+
+## Not this skill
+
+- Project tooling, docs structure, the audit checklist → `imf-web-ui-frontend-setup` (which delegates agent tooling here)
+- Library wiring (styles import, provider) → `imf-web-ui-library-setup`

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/baseline-staleness.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+# Advisory baseline-staleness check, meant to be called from the repo's pre-commit hook.
+# Compares the installed imf-web-ui skill markers against the installed package version
+# and warns on drift. Always exits 0 — staleness never blocks a commit.
+PKG=node_modules/@imfusion/web-ui/package.json
+[ -f "$PKG" ] || exit 0
+CURRENT=$(node -p "require('./$PKG').version" 2>/dev/null) || exit 0
+
+for marker in .agents/skills/imf-web-ui-*/.imf-web-ui-skill-version.json; do
+  [ -f "$marker" ] || continue
+  INSTALLED=$(node -p "require('./$marker').version" 2>/dev/null) || continue
+  if [ "$INSTALLED" != "$CURRENT" ]; then
+    echo "imf-web-ui skills are stale ($INSTALLED installed, package is $CURRENT) — run: npx web-ui-install"
+    break
+  fi
+done
+exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/post-tool-use.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+# PostToolUse (Edit|Write): advisory file-scope checks on the touched file. Never exits
+# non-zero, so a mid-flight refactor can't trap the agent. Resolve the repo from the edited
+# file, not cwd, which is not guaranteed for hooks.
+FILE=$(jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -f "$FILE" ] || exit 0
+
+ROOT=$(cd "$(dirname "$FILE")" && git rev-parse --show-toplevel 2>/dev/null) || exit 0
+cd "$ROOT" || exit 0
+
+case "$FILE" in
+  *.ts | *.tsx | *.js | *.jsx)
+    [ -x ./node_modules/.bin/eslint ] && ./node_modules/.bin/eslint --cache "$FILE" 2>&1
+    ;;
+esac
+case "$FILE" in
+  *.ts | *.tsx | *.js | *.jsx | *.css | *.json | *.md)
+    [ -x ./node_modules/.bin/prettier ] && ./node_modules/.bin/prettier --check "$FILE" 2>&1
+    ;;
+esac
+exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/session-start.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+# SessionStart: point the agent at the vendored conventions baseline once per session.
+echo "The ImFusion frontend conventions baseline is vendored in .agents/skills/ (imf-web-ui-frontend-conventions and siblings). Load the relevant skill before writing code, styles, or docs; repo docs in docs/ carry only what is unique to this repo."
+exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/user-prompt-submit.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+# UserPromptSubmit: one-line conventions reminder per prompt.
+echo "Conventions check: if this task touches code, styles, data fetching, or docs, consult the matching imf-web-ui-* skill in .agents/skills/ before acting."
+exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/settings.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/session-start.sh\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/user-prompt-submit.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/post-tool-use.sh\"",
+            "statusMessage": "Verifying file"
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/llms/skills/imf-web-ui-components/SKILL.md

@@ -3,7 +3,7 @@ name: imf-web-ui-components
 description:
   "Look up @imfusion/web-ui component APIs without reading their source: the two-hop lookup (identity index -> prop data),
   compound components, and integrations. Load when you need the props, sub-components, or defaults of a specific component —
-  not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-setup)."
+  not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-library-setup)."
 ---
 
 # imf-web-ui-components

package/src/llms/skills/imf-web-ui-frontend-conventions/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: imf-web-ui-frontend-conventions
+description:
+  "The ImFusion frontend conventions baseline — in-house conventions, valid in every ImFusion frontend and usable by anyone
+  who likes them. A router over topic references: library boundary, React, components, TypeScript, styling, data layer,
+  project structure, testing, stack, npm project, tooling config, git, assets, docs structure. Load when writing wrapper
+  components, custom UI, styling beyond the defaults, adding new files to a consumer app, writing repo docs, touching tool
+  config, or choosing any dependency."
+---
+
+# imf-web-ui-frontend-conventions
+
+The ImFusion frontend baseline. In-house conventions, not industry claims — they encode how ImFusion frontends are built, and
+anyone else is welcome to them.
+
+**The project wins.** These defaults fill vacuums: if the host project already has a convention — a styling system, a state
+library, a folder shape — that stands. They are not a license to refactor a consumer codebase toward this document.
+
+**Alignment mode.** The exception is intent: when the user asks to _align_ the repo with the baseline ("align", "alignment"
+is the flag), the project-wins guard lifts. Deviations then become migration findings — proposed as a plan, still nothing
+changed until the human approves.
+
+## The references
+
+Each topic lives in one reference. Read the one whose moment you're in; starting a new feature usually wants several.
+
+| Reference                                               | Covers                                                              | Read when                                               |
+| ------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------- |
+| [library-boundary.md](references/library-boundary.md)   | staying behind `@imfusion/web-ui`, wrappers, type derivation, peers | touching anything that renders library components       |
+| [react.md](references/react.md)                         | component roles, state kinds and owners, effects discipline         | writing new screens, components, or wrappers            |
+| [components.md](references/components.md)               | component anatomy on disk: grouping, folders, colocation            | adding a component file                                 |
+| [typescript.md](references/typescript.md)               | functional style, types, naming                                     | writing any code                                        |
+| [styling.md](references/styling.md)                     | native CSS Modules, tokens, the override contract                   | writing CSS or styling beyond the defaults              |
+| [class-names.md](references/class-names.md)             | CVA variants, `cx`, merging the incoming `className`                | writing a component with variants or a `className` prop |
+| [data.md](references/data.md)                           | `api/`+`http/` shape, Zod boundary, query/mutation patterns         | adding an API topic, a fetch, or a mutation             |
+| [project-structure.md](references/project-structure.md) | the `src/` tree, file naming, imports                               | adding files rather than editing existing ones          |
+| [testing.md](references/testing.md)                     | what's worth testing and what isn't                                 | writing or reviewing tests                              |
+| [stack.md](references/stack.md)                         | the topic→tool map, when a library owns a layer                     | choosing or adding any dependency                       |
+| [npm-project.md](references/npm-project.md)             | `package.json`, the `verify:*` script set, dependency pinning       | running or adding a script, adding a dependency         |
+| [tooling.md](references/tooling.md)                     | Prettier, ESLint, tsconfig, staged files, CSS class names           | touching tool config                                    |
+| [git.md](references/git.md)                             | `git:config`, verify scopes, staleness at commit time               | wiring hooks or the commit path                         |
+| [assets.md](references/assets.md)                       | image formats, the WebP recipe                                      | adding images or other static assets                    |
+| [docs-structure.md](references/docs-structure.md)       | what a repo documents, where, how it's written                      | writing or restructuring repo docs                      |
+
+`imf-web-ui-frontend-setup` bootstraps and audits a repo against this baseline.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/assets.md

@@ -0,0 +1,23 @@
+# Assets
+
+Import everything from `src/assets/` so the bundler fingerprints and bundles it. Never reference an image by public-path
+string.
+
+## Photographs — WebP
+
+```bash
+magick source.png -resize 2000x -quality 80 -define webp:method=6 src/assets/name.webp
+```
+
+- Quality 80 is visually lossless on photos and routinely cuts file size by an order of magnitude.
+- `method=6` is the densest encoding. It's a one-off cost at conversion time, so take the smaller file.
+- Cap the long edge at 2000px — nothing on the market resolves more in a content image.
+- No `<picture>` fallback needed; WebP is supported everywhere since 2020.
+
+## Other formats
+
+- **Alpha, or pixels that must stay exact** → PNG, optimized with `oxipng` or `pngquant`.
+- **Icons, logos, line art** → inline SVG component, so it inherits `currentColor` and follows the theme.
+
+These rules apply to assets as they're added or touched. Existing assets in another format are not findings to sweep —
+convert opportunistically, when you're working on them anyway.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/class-names.md

@@ -0,0 +1,42 @@
+# Class names in components
+
+How a component turns props into a `className` string. What the build does with the result is [tooling.md](tooling.md); what
+goes in the stylesheet is [styling.md](styling.md).
+
+**CVA is the only tool.** `class-variance-authority` maps variant props to CSS Module classes. No `clsx`, no
+`tailwind-merge`, no local `cn()` helper. `cx` is CVA's own concatenator and `@imfusion/web-ui` re-exports it, so it comes
+from the library alongside the components.
+
+```tsx
+import { cva } from "class-variance-authority";
+import classes from "./chip.module.css";
+
+const chip = cva(classes.root, {
+  variants: {
+    appearance: { outline: classes.appearanceOutline, solid: classes.appearanceSolid },
+    inline: { false: null, true: classes.inline }
+  }
+});
+
+export function Chip({ appearance = "outline", inline = false, className, ...props }: Props) {
+  return <span {...props} className={chip({ appearance, inline, className })} />;
+}
+```
+
+- **Base class is CVA's first argument**, variant values are CSS Module references, never string literals. A boolean axis
+  uses `null` for its off-state.
+- **The incoming `className` goes into CVA's `className` slot**, which appends it last so a caller's class always wins. With
+  no variants to map, `cx(classes.inline, className)` does the same job.
+- **Every component that accepts `className` merges it.** A component whose surface is deliberately closed omits the prop
+  entirely rather than accepting and ignoring it.
+- **Defaults live in the props destructuring, not CVA's `defaultVariants`.** react-docgen-typescript reads the destructuring,
+  so defaults declared in CVA don't reach the generated docs.
+- **Resolve a function-form `className` before merging.** Components built on a library that passes render state
+  (`className={state => …}`) receive either shape:
+
+  ```tsx
+  className={state => cx(classes.root, typeof className === "function" ? className(state) : className)}
+  ```
+
+- **Two components sharing one visual share one CVA module**, a `{name}.cva.ts` next to them, so their variant axes can't
+  drift apart.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/components.md

@@ -0,0 +1,63 @@
+# Components
+
+How a component lives on disk and how dumb it stays. Roles, state, and effects in full are [react.md](react.md); styling is
+[styling.md](styling.md).
+
+## As dumb as possible
+
+Data comes from outside — props-fed, never self-fetching. Presentational logic (formatting a label, deriving a display state)
+is fine; owning data is not:
+
+```tsx
+// components/user-card/user-card.tsx
+interface Props {
+  name: string;
+  role: string;
+  onEdit: () => void;
+}
+
+export function UserCard({ name, role, onEdit }: Props) {
+  return (
+    <Card.Root>
+      <Card.Content>
+        <Typo>{name}</Typo>
+        <Chip>{role}</Chip>
+      </Card.Content>
+      <Card.Footer>
+        <Button onClick={onEdit}>Edit</Button>
+      </Card.Footer>
+    </Card.Root>
+  );
+}
+```
+
+No query hook, no store access, no route awareness — the component renders what it's given and reports events upward. Local
+UI state (`isOpen`, a draft value) is allowed; anything whose truth lives elsewhere is not ([react.md](react.md)).
+
+## Grouping
+
+`components/` groups by kind — a layout component under `layouts/`, not beside a domain widget. Flat is fine while there are
+few; let the grouping follow what the project actually has rather than imposing it up front. The kinds worth separating are
+the component roles in [react.md](react.md).
+
+## One file or a folder
+
+A component gets a folder once it has more than one file — sub-components, styles, tests — with an `index.ts` that only
+re-exports:
+
+```
+components/data-table/
+  data-table.tsx
+  data-table-row.tsx
+  data-table.module.css
+  index.ts
+```
+
+Imports then read `#/components/data-table` and the inside can be restructured without touching call sites. Single-file
+components stay single files, directly in their group.
+
+## Colocation
+
+The stylesheet is colocated as `<component>.module.css` next to the component, and only dumb components have one — a
+container that wants CSS is asking for a layout component instead ([react.md](react.md)). Tests and local types sit next to
+their subject too. A file you have to hunt for in a parallel tree gets edited less carefully.