@imfusion/web-ui 0.5.1-dev.15.g0b0aa0c5 → 0.5.1-dev.18.g81350f83

package/dist/build/vite-css-module-names/index.d.ts

@@ -0,0 +1,20 @@
+import { Plugin } from 'vite';
+export interface ReadableCssModuleNamesOptions {
+    /** Namespace for every generated class name. Short, stable, app-scoped (`imf-ui`, `acme`). */
+    prefix: string;
+}
+/**
+ * Generates readable CSS Module class names instead of the default hash, so the DOM
+ * stays legible in devtools and browser automation. `button.module.css` yields
+ * `{prefix}-button-module-root` — `[name]` is the filename, which keeps its `.module`
+ * suffix.
+ *
+ * Register it in every tool that compiles the CSS (the app build AND Storybook). A
+ * compiler left out generates different class names for the same source file and its
+ * styles silently don't apply.
+ *
+ * Defaults to opting into Lightning CSS, which drops `css.modules` options it has no
+ * equivalent for (`localsConvention`). Set `css.transformer: "postcss"` to stay on
+ * the PostCSS pipeline.
+ */
+export declare function readableCssModuleNames({ prefix }: ReadableCssModuleNamesOptions): Plugin;

package/dist/build/vite-css-module-names.js

@@ -0,0 +1,17 @@
+//#region src/build/vite-css-module-names/index.ts
+function e(e, t) {
+	let { lightningcss: n, modules: r, transformer: i } = e.css ?? {}, a = n?.cssModules;
+	if (!(typeof a == "boolean" || r === !1) && !a?.pattern && !(typeof r == "object" && r.generateScopedName)) return i === "postcss" ? { css: { modules: { generateScopedName: t } } } : { css: {
+		transformer: "lightningcss",
+		lightningcss: { cssModules: { pattern: t } }
+	} };
+}
+function t({ prefix: t }) {
+	let n = `${t}-[name]-[local]`;
+	return {
+		name: "imf-ui:readable-css-module-names",
+		config: (t) => e(t, n)
+	};
+}
+//#endregion
+export { t as readableCssModuleNames };

package/dist/index.js

@@ -301,7 +301,7 @@ function Jn({ value: e, label: t = "Copy", copiedLabel: n = "Copied", variant: i
 		"data-copied": c || void 0,
 		"aria-label": c ? n : t,
 		onClick: () => l(e),
-		className: r(Kn.root, typeof o == "string" ? o : void 0),
+		className: (e) => r(Kn.root, typeof o == "function" ? o(e) : o),
 		children: /* @__PURE__ */ X(u, {
 			size: 15,
 			strokeWidth: 2,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.5.1-dev.15.g0b0aa0c5",
+  "version": "0.5.1-dev.18.g81350f83",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "license": "UNLICENSED",
@@ -30,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",
@@ -129,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/llms/skills/imf-web-ui-frontend-conventions/SKILL.md

@@ -24,21 +24,22 @@ changed until the human approves.
 
 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        |
-| [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 config baselines           | 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                |
+| 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/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/tooling.md

@@ -58,8 +58,19 @@ The `#/` → `src/` alias and its rationale: [project-structure.md](project-stru
 
 Runner config (lint-staged or nano-staged) applying eslint `--fix` and prettier `--write` to staged files only.
 
-## CSS class names across builds
+## CSS class names
 
-If more than one tool compiles the CSS (app build plus Storybook), define the generated class-name pattern **once** and
-import it in both — otherwise the same source file gets different class names per compiler and styles silently don't apply.
-`build/css-modules-config.ts` in web-ui is the reference shape.
+Generated CSS Module class names are readable in the DOM, `{prefix}-{file}-{local}`, never the default hash. A legible DOM is
+what makes devtools and browser automation usable. The library ships the plugin that produces them; pass your own short,
+app-scoped prefix:
+
+```ts
+import { readableCssModuleNames } from "@imfusion/web-ui/build/vite-css-module-names";
+
+export default defineConfig({
+  plugins: [react(), readableCssModuleNames({ prefix: "acme" })]
+});
+```
+
+One pattern for dev, Storybook, and production. Register the plugin in **every** tool that compiles the CSS — a compiler left
+out generates different names for the same source file, and its styles silently don't apply.

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

@@ -4,9 +4,10 @@ description:
   "Set up or audit an ImFusion frontend's project tooling: the stack, package.json scripts, formatting, linting, typecheck,
   staged-file and pre-commit hooks, verification scopes, dependency pinning, tsconfig, docs structure, agent wiring. House
   conventions, not industry standards. Load when starting a new ImFusion frontend, when asked what an existing one's setup is
-  missing, or when asked to align a repo with the baseline. Not for adding one config file on request — that's just the edit.
-  Not for wiring the library itself (imf-web-ui-library-setup)."
-argument-hint: "[new|audit|align]"
+  missing, when asked to align a repo with the baseline, or when asked to check or set up one named topic from it (e.g. CSS
+  class names, Prettier). Not for a bare 'add this config file' request — that's just the edit. Not for wiring the library
+  itself (imf-web-ui-library-setup)."
+argument-hint: "[new|audit|align|<topic>]"
 ---
 
 # imf-web-ui-frontend-setup
@@ -16,7 +17,7 @@ First-time setup and audit against the ImFusion frontend baseline. The conventio
 standards: report findings as "missing against the ImFusion baseline", never "against best practice". Built for ImFusion
 frontends; anyone else who likes the baseline can run it too.
 
-Three modes, same checklist:
+Four modes, same checklist:
 
 - **New project** — work down the checklist and set each piece up.
 - **Audit** — read the repo (don't ask what it has), report present / missing / broken, change nothing until the human picks.
@@ -24,6 +25,10 @@ Three modes, same checklist:
   report what's _absent_; a working convention you'd have chosen differently is not a finding.
 - **Align** — when the user asks to _align_ the repo with the baseline ("align"/"alignment" is the flag), the project-wins
   guard lifts: deviations become migration findings, proposed as a plan, still nothing changed until approved.
+- **One topic** — any other argument names a topic instead of a mode (`class names`, `prettier`, `tooling`). Resolve it to
+  the checklist rows it touches and run the audit process against those only, reading their references as usual. Say which
+  rows you resolved it to before reporting, and if nothing matches, say so and list the rows rather than guessing or sweeping
+  everything. Same output as an audit: findings, nothing changed until the human picks.
 
 **Producer scope.** The web-ui repo itself produces this baseline; it is not a consumer frontend. Consumer-only rows — the
 AGENTS.md fence, vendored-skill staleness, the app stack and app `src/` tree — don't apply there. Audit it against the shared
@@ -31,19 +36,20 @@ rows only: scripts, tooling, git, docs.
 
 ## The checklist
 
-Each row is a reference in `../imf-web-ui-frontend-conventions/references/` — read it, then check the repo against it.
-
-| Reference              | Set up / audit                                                               |
-| ---------------------- | ---------------------------------------------------------------------------- |
-| `stack.md`             | the dependencies match the topic→tool map; devtools siblings present         |
-| `npm-project.md`       | script names table, `type`/`private`, exact pins, `.npmrc`, Node pinning     |
-| `tooling.md`           | Prettier values, ESLint flat config, tsconfig, staged-file runner            |
-| `git.md`               | `git:config` run and hooks directory present, verify scopes, staleness hooks |
-| `project-structure.md` | the `src/` tree, file naming, `#/` alias wiring                              |
-| `components.md`        | component folders and colocation                                             |
-| `styling.md`           | CSS Modules, tokens, no CSS-in-JS or utility framework                       |
-| `docs-structure.md`    | docs shape and content rules (see Docs below)                                |
-| — agent tooling        | delegated to `imf-web-ui-agent-setup` (see Agent tooling below)              |
+Each row is a reference in `../imf-web-ui-frontend-conventions/references/` — read it, then check the repo against it. A
+topic argument narrows this table to the rows it names; every other mode works down all of it.
+
+| Reference              | Set up / audit                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| `stack.md`             | the dependencies match the topic→tool map; devtools siblings present                        |
+| `npm-project.md`       | script names table, `type`/`private`, exact pins, `.npmrc`, Node pinning                    |
+| `tooling.md`           | Prettier values, ESLint flat config, tsconfig, staged-file runner, readable CSS class names |
+| `git.md`               | `git:config` run and hooks directory present, verify scopes, staleness hooks                |
+| `project-structure.md` | the `src/` tree, file naming, `#/` alias wiring                                             |
+| `components.md`        | component folders and colocation                                                            |
+| `styling.md`           | CSS Modules, tokens, no CSS-in-JS or utility framework                                      |
+| `docs-structure.md`    | docs shape and content rules (see Docs below)                                               |
+| — agent tooling        | delegated to `imf-web-ui-agent-setup` (see Agent tooling below)                             |
 
 ## Docs