@imfusion/web-ui 0.6.4-dev.43.g3f16d49f → 0.6.4-dev.47.gbf9db4a0

package/README.md

@@ -50,12 +50,12 @@ npx web-ui-install
 Run the command again after updating the package. It refreshes the skills already installed in the project. Use
 `--reconfigure` to choose a different target. Add `--hooks` to install the lifecycle hooks for Claude Code and Codex.
 
-Start with `/imf-web-ui`. It routes a task to the companion skills it needs, or tells the agent to work without extra
-guidance.
+Start with `/imf-web-ui`. It routes library questions to the packaged user guides and UI work to the companion skills it
+needs. Agents read the guides from `node_modules/@imfusion/web-ui/docs/user-guide/` without a running Storybook.
 
 | Skill                     | Use it for                                                   |
 | ------------------------- | ------------------------------------------------------------ |
-| `/imf-web-ui`             | Route UI work to the right companion.                        |
+| `/imf-web-ui`             | Route UI work and library questions to skills and guides.    |
 | `/imf-web-ui-setup`       | Plan library wiring, project setup, or tooling changes.      |
 | `/imf-web-ui-components`  | Look up component and icon APIs.                             |
 | `/imf-web-ui-ux`          | Choose components and shape screens and flows.               |

package/dist/vite/brand-assets.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from 'vite';
+/** Serves and emits the complete ImFusion favicon set at stable root URLs. */
+export declare function imfusionBrandAssets(): Plugin;

package/dist/vite/index.d.ts

@@ -0,0 +1,2 @@
+export { imfusionBrandAssets } from './brand-assets.ts';
+export { readableCssModuleNames, type ReadableCssModuleNamesOptions } from './readable-css-module-names.ts';

package/dist/vite.js

@@ -0,0 +1,55 @@
+import { readFileSync as e, readdirSync as t } from "node:fs";
+import { dirname as n, join as r } from "node:path";
+import { fileURLToPath as i } from "node:url";
+//#region src/vite/brand-assets.ts
+var a = n(i(import.meta.resolve("@imfusion/web-ui/assets/favicon/favicon.svg"))), o = t(a).map((t) => ({
+	name: t,
+	source: e(r(a, t))
+})), s = {
+	".ico": "image/x-icon",
+	".png": "image/png",
+	".svg": "image/svg+xml"
+};
+function c(e) {
+	return s[e.slice(e.lastIndexOf("."))] ?? "application/octet-stream";
+}
+function l() {
+	return {
+		name: "imf-ui:brand-assets",
+		configureServer(e) {
+			e.middlewares.use((e, t, n) => {
+				let r = o.find(({ name: t }) => e.url?.split("?")[0] === `/${t}`);
+				if (!r) {
+					n();
+					return;
+				}
+				t.setHeader("Content-Type", c(r.name)), t.end(r.source);
+			});
+		},
+		generateBundle() {
+			for (let e of o) this.emitFile({
+				fileName: e.name,
+				source: e.source,
+				type: "asset"
+			});
+		}
+	};
+}
+//#endregion
+//#region src/vite/readable-css-module-names.ts
+function u(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 d({ prefix: e }) {
+	let t = `${e}-[name]-[local]`;
+	return {
+		name: "imf-ui:readable-css-module-names",
+		config: (e) => u(e, t)
+	};
+}
+//#endregion
+export { l as imfusionBrandAssets, d as readableCssModuleNames };

package/docs/user-guide/AiAgents.mdx

@@ -0,0 +1,51 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { Typo } from "#/components/typo";
+
+<Meta title="User Guide/AI Agents" />
+
+# AI agents
+
+The package includes optional skills for agents working in a project that uses `@imfusion/web-ui`.
+
+## Install the skills
+
+Install the package first, then run this in the consumer project:
+
+```sh
+npx web-ui-install
+```
+
+The installer asks whether to use Claude Code's `.claude/skills/`, the shared `.agents/skills/` directory, or both. Use
+`--target claude` or `--target agents` to choose without the prompt. Run it again after a package update; use
+`--reconfigure` to choose again.
+
+Add `--hooks` when the project should install the optional lifecycle hooks for Claude Code and Codex:
+
+```sh
+npx web-ui-install --hooks
+```
+
+Read the [agent-tooling topic](../../src/llms/skills/imf-web-ui-conventions/topics/agent-tooling.md) before adapting hook
+registrations. Codex also requires project trust and a review of `/hooks`.
+
+## Start with the router
+
+Use <Typo.InlineCode>/imf-web-ui</Typo.InlineCode> for UI work and library questions. It routes usage questions to the
+packaged user guides and development tasks to the matching companions:
+
+| Skill | Use it for |
+| --- | --- |
+| `/imf-web-ui-components` | Component props, parts, defaults, and icons. |
+| `/imf-web-ui-ux` | Choosing components and shaping screens or flows. |
+| `/imf-web-ui-conventions` | Code, styling, data, validation, and project conventions. |
+| `/imf-web-ui-setup` | First-time wiring and approved project setup. |
+| `/imf-web-ui-audit` | A read-only check of an existing project. |
+| `/imf-web-ui-update` | Updating the package and its installed tooling. |
+
+The router keeps small tasks small. It does not load every reference just because the package is installed.
+
+## Where the files come from
+
+The skills are shipped inside the package under `src/llms/skills/`. `web-ui-install` copies them into the consumer project.
+The package also exposes generated component, token, and icon indexes for the lookup skill. User guides ship as readable
+MDX under `docs/user-guide/`; agents read them from the installed package without a running Storybook.

package/docs/user-guide/BrandAssets.mdx

@@ -0,0 +1,105 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import faviconUrl from "#/assets/public/favicon/favicon.svg";
+import ogUrl from "#/assets/public/favicon/og-image.png";
+
+<Meta title="User Guide/Brand Assets" />
+
+# Brand assets
+
+The package ships the ImFusion favicon set and a social sharing image as plain files. Import them through the `assets`
+subpath:
+
+```
+@imfusion/web-ui/assets/<folder>/<file>
+```
+
+These are static files rather than components, so an application references them from its HTML head or copies them into its
+own output. Everything under the subpath is a real file on disk, which means a build step can resolve and copy it.
+
+## Files
+
+| File                           | Size       | Use                                                       |
+| ------------------------------ | ---------- | --------------------------------------------------------- |
+| `favicon/favicon.ico`          | 16, 32, 48 | The fallback every browser understands                    |
+| `favicon/favicon.svg`          | any        | Preferred by current browsers; stays sharp on any display |
+| `favicon/favicon-16.png`       | 16         | Explicit small PNG                                        |
+| `favicon/favicon-32.png`       | 32         | Explicit standard PNG                                     |
+| `favicon/apple-touch-icon.png` | 180        | iOS home screen                                           |
+| `favicon/icon-192.png`         | 192        | Web app manifest                                          |
+| `favicon/icon-512.png`         | 512        | Web app manifest, splash screens                          |
+| `favicon/og-image.png`         | 1200×630   | Link previews in chat and social apps                     |
+
+The mark sits on a square brand-blue tile. The white ImFusion glyph is scaled proportionally within it with a small inset at
+the sides.
+
+<div style={{ display: "flex", gap: "1.5rem", alignItems: "flex-end", margin: "1.5rem 0" }}>
+  {[16, 32, 64, 128].map(size => (
+    <div key={size} style={{ textAlign: "center" }}>
+      <img src={faviconUrl} width={size} height={size} alt="" style={{ display: "block", marginBottom: "0.5rem" }} />
+      <code style={{ fontSize: "0.75rem" }}>{size}</code>
+    </div>
+  ))}
+</div>
+
+<img src={ogUrl} alt="" width="480" style={{ display: "block", borderRadius: "0.5rem", margin: "1.5rem 0" }} />
+
+## Regenerate the favicon files
+
+`favicon.svg` is the source for every favicon variant. With [ImageMagick](https://imagemagick.org) installed, run this from
+`src/assets/public/favicon/` after changing the SVG:
+
+```sh
+for output in "favicon-16.png:16" "favicon-32.png:32" "apple-touch-icon.png:180" "icon-192.png:192" "icon-512.png:512"; do
+  file=${output%%:*}
+  size=${output##*:}
+  magick -density 512 favicon.svg -resize "${size}x${size}" "png32:$file"
+done
+
+magick -density 512 favicon.svg -define icon:auto-resize=16,32,48 favicon.ico
+```
+
+`og-image.png` is a separate 1200×630 social image.
+
+## Add the favicon to a Vite application
+
+Register the Vite plugin, then reference the stable root URLs from the document head:
+
+```ts
+import { defineConfig } from "vite";
+import { imfusionBrandAssets } from "@imfusion/web-ui/vite";
+
+export default defineConfig({
+  plugins: [imfusionBrandAssets()]
+});
+```
+
+```html
+<link rel="icon" href="/favicon.ico" sizes="48x48" />
+<link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+<meta property="og:image" content="https://example.com/og-image.png" />
+```
+
+The plugin serves the complete favicon set during development and emits it at the root of the build output. Give `og:image`
+an absolute URL. Chat and social applications fetch it from their own servers, so a relative path does not resolve.
+
+### Other build systems
+
+Copy the files into the application's static-files directory during its build. Resolve the package path rather than hard-coding
+a path into `node_modules`.
+
+## Import a single file in application code
+
+A bundler can also take one file directly, which is useful for a manifest or an `<img>`:
+
+```ts
+import iconUrl from "@imfusion/web-ui/assets/favicon/icon-512.png";
+```
+
+The bundler returns the asset's URL for use in application code. Vite also processes `index.html` and rewrites supported
+asset references there. Use the copy step above when the files need stable public filenames.
+
+## Keycloak
+
+A Keycloak login theme reads its icons from its own `resources/` directory. Copy the favicon files in when building the theme
+and reference them from the theme's template, the same way as any other application.

package/docs/user-guide/GettingStarted.mdx

@@ -0,0 +1,55 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="User Guide/Getting Started" />
+
+# Getting started
+
+## Install
+
+```sh
+npm install @imfusion/web-ui
+```
+
+To try a local checkout instead:
+
+```sh
+# from the web-ui repository
+npm pack
+
+# from your application
+npm install /path/to/web-ui-0.0.0.tgz
+```
+
+The package requires React and React DOM 19 or newer. Integrations have their own optional peer dependencies; their pages
+list them.
+
+## Add the provider
+
+Import the stylesheet and mount `WebUIProvider` once, near the application root:
+
+```tsx
+import "@imfusion/web-ui/styles.css";
+import { Button, WebUIProvider } from "@imfusion/web-ui";
+
+export function App() {
+  return (
+    <WebUIProvider>
+      <Button>Save</Button>
+    </WebUIProvider>
+  );
+}
+```
+
+Import primitives from `@imfusion/web-ui`. Do not import Base UI components or styles directly.
+
+## Add the favicon
+
+The package also ships the ImFusion favicon set and a social sharing image. See **Brand Assets** for the files and the
+`<link>` tags an application needs.
+
+## Explore token controls
+
+When exploring the library in Storybook, open `Tokens` in the top-right toolbar. The token showcase displays the controls in
+a sidebar on larger screens and a drawer on smaller screens, and changes update the preview live. The controls do not yet
+generate a copyable CSS override block. Apply the values you want in your application CSS, starting with `--imf-ui-*`
+variables.

package/docs/user-guide/HowItsBuilt.mdx

@@ -0,0 +1,33 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="User Guide/How It's Built" />
+
+# How it's built
+
+You can use the library without knowing its implementation. This explains the boundary.
+
+## Behavior comes from an implementation library
+
+Adapted interactive primitives use Base UI for focus management, keyboard behavior, and accessibility details. Web UI owns the public
+props, defaults, tokens, styles, and exports.
+
+This split lets the implementation change without forcing a consumer migration.
+
+## Web UI is the styled middle layer
+
+Every primitive adds:
+
+- `--imf-ui-*` tokens for the visual system.
+- `data-imf-ui-component` for a stable DOM identity.
+- CSS layers that let consumer styles override the defaults.
+
+The wrapper keeps the upstream surface complete. If an upstream part or prop is useful, Web UI exposes it instead of making an
+app reach around the library.
+
+## Compose parts
+
+Compound components use namespaces such as `Drawer.Root`, `Drawer.Trigger`, and `Drawer.Content`. This keeps behavior and
+layout composable without a component with a prop for every possible arrangement.
+
+For consumer import and composition rules, read the packaged
+[library-boundary topic](../../src/llms/skills/imf-web-ui-conventions/topics/library-boundary.md).

package/docs/user-guide/Introduction.mdx

@@ -0,0 +1,21 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="User Guide/Introduction" />
+
+# ImFusion Web UI
+
+`@imfusion/web-ui` is the shared React UI library for ImFusion web apps. It provides accessible primitives, ImFusion tokens,
+and one public import surface.
+
+## Find your way
+
+- **Getting Started** installs the package and mounts it in an app.
+- **Usage Patterns** covers composition, overrides, state, and color schemes.
+- **Tokens** explains the theming surface.
+- **AI Agents** explains the optional skills shipped with the package.
+- **How It's Built** explains the boundary between Web UI and its implementation libraries.
+- **Primitives** lists the components in the main package entry.
+- **Integrations** lists components that need an optional package.
+- **Development** is for contributors to this repository.
+
+The [repository README](https://bitbucket.imfusion.com/projects/WEBSDK/repos/web-ui) covers local development and releases.

package/docs/user-guide/Tokens.mdx

@@ -0,0 +1,85 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { Typo } from "#/components/typo";
+
+<Meta title="User Guide/Tokens" />
+
+# Tokens
+
+The library's theme is a set of CSS custom properties under `--imf-ui-*`.
+
+## Change a family
+
+Most customization uses a control token. Controls feed the semantic tokens consumed by components:
+
+```css
+:root {
+  --imf-ui-color-brand-hue: 210;
+}
+```
+
+Brand and primary are related. Primary hue and chroma follow brand until their own controls are changed; primary luma is
+independent. Surface controls work the same way: `main`, `support`, and `minor` start as one ladder and can be split when
+needed.
+
+Use a semantic token for a one-off role. That changes one result without changing the rest of its family.
+
+## Families
+
+| Family | Use |
+| --- | --- |
+| Brand | Identity color. |
+| Surfaces | Canvas and panels: `main`, `support`, `minor`. |
+| Primary | Actions and calls to action. |
+| Status | `negative`, `warning`, `positive`, and `info`. |
+| Accents | Three independent accent slots. |
+| Fonts | Shared font stacks and text roles. |
+| Shape | Radius and corner controls. |
+| Shadow | The shared elevation model. |
+
+The live token controls and exact names are on the
+<Typo.Link href="/?path=/story/user-guide-tokens-reference--reference" kind="internal" target="_top">token reference</Typo.Link>.
+
+## Use semantic tokens in CSS
+
+Components and consumer CSS should use semantic roles:
+
+```css
+.panel {
+  background: var(--imf-ui-color-bg-support);
+  color: var(--imf-ui-color-fg-main);
+}
+```
+
+Foreground tokens are for text, icons, borders, and focus rings. Background tokens are for fills. `fg-oncolor` is for text on
+saturated fills.
+
+## Color schemes
+
+The provider sets the active scheme on the document element:
+
+```html
+<html data-imf-ui-color-scheme="light">
+```
+
+Scheme-aware controls have light and dark values. Application CSS can select the attribute when a rule itself must change.
+
+## Fonts, shape, and shadow
+
+The font controls define the editorial and utility type roles. Radius controls plain rounded corners; chamfer is a separate
+brand shape axis. Shadow controls share one lighting model across components:
+
+- `--imf-ui-shadow-angle` sets the sun direction; the default `315deg` makes shadows fall down and right.
+- `--imf-ui-shadow-hardness` moves from diffuse (`0`) to crisp (`1`) edges without changing the elevation level.
+- `--imf-ui-shadow-spread` adds pixel spread to every shadow.
+- `--imf-ui-shadow-intensity` sets the lowest-level opacity; higher levels add one point each.
+- `--imf-ui-shadow-color` sets the cast color per scheme.
+
+Components consume these values through tokens. The package's `src/llms/tokens.gen.json` lists the shipped token names and
+authored defaults.
+
+## Explore
+
+- <Typo.Link href="/?path=/story/user-guide-tokens-showcase--showcase" kind="internal" target="_top">Showcase</Typo.Link>
+  applies the controls to real components.
+- <Typo.Link href="/?path=/story/user-guide-tokens-reference--reference" kind="internal" target="_top">Reference</Typo.Link>
+  lists every generated token.

package/docs/user-guide/UsagePatterns.mdx

@@ -0,0 +1,79 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="User Guide/Usage Patterns" />
+
+# Usage patterns
+
+## Keep imports behind Web UI
+
+Use the library's components, icons, styles, and provider. Do not import Base UI or another implementation package directly.
+That keeps the styling and public API consistent.
+
+## Compose parts
+
+Multi-part primitives are namespaces. Render the parts you need:
+
+```tsx
+<Drawer.Root>
+  <Drawer.Trigger>Open</Drawer.Trigger>
+  <Drawer.Content>…</Drawer.Content>
+</Drawer.Root>
+```
+
+All parts come from `@imfusion/web-ui`, including less common ones such as `Indent`, `SwipeArea`, and `Description`.
+
+
+## Change the look with tokens
+
+When exploring the library in Storybook, use the `Tokens` controls in the top-right toolbar. On the token showcase, they appear as a sidebar on larger screens and a drawer on smaller screens, and changes update the preview live. The controls do not yet generate a copyable CSS override block. Apply the values you want in your application CSS, starting with `--imf-ui-*` variables. A control changes a related family of semantic tokens:
+
+```css
+:root {
+  --imf-ui-color-primary-hue: 30;
+}
+```
+
+Use a semantic token for a local role. Consumer CSS outside `@layer imf-ui.components` overrides the library without `!important`:
+
+```css
+.my-button {
+  border-radius: 0;
+}
+```
+
+Components carry `data-imf-ui-component` on their roots, so it is a stable selector. CSS Module class names are internal.
+
+## Style state with data attributes
+
+Components expose runtime state through attributes such as `data-checked`, `data-disabled`, and `data-popup-open`:
+
+```css
+[data-imf-ui-component="Switch"][data-checked] {
+  outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-positive);
+}
+```
+
+Use the attribute instead of maintaining a second state class.
+
+## Choose variants locally
+
+A `variant` prop belongs to the component that defines it. `brand` means identity color; `primary` means the action color.
+They may look related, but one component's variant list is not a global list.
+
+## Color schemes
+
+`WebUIProvider` sets `data-imf-ui-color-scheme="light"` or `"dark"` on `<html>`. Select it when an application rule needs to
+change with the scheme:
+
+```css
+[data-imf-ui-color-scheme="dark"] .hero {
+  background-image: url("/hero-dark.png");
+}
+```
+
+The provider follows the OS by default. An application whose own surfaces are a fixed palette pins the scheme instead, so
+component colors cannot disagree with them:
+
+```tsx
+<WebUIProvider colorScheme="dark">{children}</WebUIProvider>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.6.4-dev.43.g3f16d49f",
+  "version": "0.6.4-dev.47.gbf9db4a0",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "homepage": "https://imfusion.com",
@@ -31,9 +31,9 @@
       "types": "./dist/integrations/*/index.d.ts",
       "import": "./dist/integrations/*.js"
     },
-    "./build/*": {
-      "types": "./dist/build/*/index.d.ts",
-      "import": "./dist/build/*.js"
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "import": "./dist/vite.js"
     },
     "./icons": {
       "types": "./dist/icons/index.d.ts",
@@ -49,6 +49,7 @@
     "dist",
     "src/assets/public",
     "docs/assets/imfusion-banner.svg",
+    "docs/user-guide",
     "THIRD_PARTY_NOTICES.md",
     "src/llms/install-templates",
     "src/docgen/doc.gen.json",

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

@@ -1,14 +1,15 @@
 ---
 name: imf-web-ui
 description:
-  "Route UI work in a project that uses @imfusion/web-ui. Use this skill whenever a user adds, edits, styles, or reviews UI
-  in a consumer project, even if they do not mention the library. Decide whether guidance is needed, then open only the
-  companion skills that match the task."
+  "Route UI work and library questions in a project that uses @imfusion/web-ui. Use this skill whenever a user adds, edits,
+  styles, or reviews UI, or asks about library setup, brand assets, favicons, theming, or usage in a consumer project, even
+  if they do not mention the library. Open only the matching packaged guide or companion skill."
 ---
 
 # Route Web UI work
 
-Start here for UI work in a project that uses `@imfusion/web-ui`. This skill is a map, not a second copy of every convention.
+Start here for UI work and library questions in a project that uses `@imfusion/web-ui`. This skill is a map, not a second
+copy of every convention.
 
 ## 1. Decide whether guidance is needed
 
@@ -22,6 +23,7 @@ not already have.
 
 | Task                                                              | Open                                                   |
 | ----------------------------------------------------------------- | ------------------------------------------------------ |
+| Understand library setup, brand assets, theming, or usage         | Packaged user guides below                             |
 | Look up a component, part, prop, default, or icon                 | `imf-web-ui-components`                                |
 | Choose components or shape a screen or flow                       | `imf-web-ui-ux`                                        |
 | Write or update documentation                                     | `/documentation-writer`, then `imf-web-ui-conventions` |
@@ -33,6 +35,24 @@ not already have.
 A screen often needs both `imf-web-ui-ux` and `imf-web-ui-components`, in that order. Setup and audit are for project-wide
 questions, not every one-file edit.
 
+### Read a packaged user guide
+
+Read only the matching page under `node_modules/@imfusion/web-ui/docs/user-guide/` in the consumer project:
+
+| Question                                                        | Page                 |
+| --------------------------------------------------------------- | -------------------- |
+| What the library provides                                       | `Introduction.mdx`   |
+| Installation, stylesheet, and provider wiring                   | `GettingStarted.mdx` |
+| Favicons, social sharing images, and static brand files         | `BrandAssets.mdx`    |
+| Composition, CSS overrides, state attributes, and color schemes | `UsagePatterns.mdx`  |
+| Token families and customization                                | `Tokens.mdx`         |
+| Agent skills and their installation                             | `AiAgents.mdx`       |
+| Library boundaries and implementation choices                   | `HowItsBuilt.mdx`    |
+
+Read MDX as text. Its imports, JSX previews, and Storybook navigation are presentation, not instructions to install or run
+Storybook in the consumer. Cite the packaged page when answering a library question. Use `imf-web-ui-components` for exact
+props and the conventions `tokens` topic for exact token names and defaults.
+
 ## 3. Keep project choices
 
 The host project's existing conventions win. The companion skills fill gaps; they do not justify refactoring a working

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

@@ -2,8 +2,11 @@
 
 ## Importing
 
-Import files from `src/assets/` so the bundler fingerprints and includes them. Do not reference an asset through a
-public-path string.
+Import application images from `src/assets/` so the bundler fingerprints and includes them. Use public URLs for files
+consumed by document metadata or manifests, with a build step that serves the files at those URLs.
+
+For the library's favicon set and social sharing image, read `BrandAssets.mdx` through the packaged user-guide route in
+`imf-web-ui`.
 
 ## Photographs: WebP
 
@@ -17,8 +20,8 @@ Keep the long edge at 2000px or less. WebP is supported by the browser floor.
 
 ## Other formats
 
-Use PNG when the image needs alpha or exact pixels. Use an inline SVG component for icons, logos, and line art so it inherits
-`currentColor` and follows the theme.
+Use PNG when the image needs alpha or exact pixels. Use an inline SVG component for in-app icons, logos, and line art so it
+inherits `currentColor` and follows the theme.
 
 ## Scope
 

package/src/llms/skills/imf-web-ui-conventions/topics/tooling.md

@@ -71,19 +71,20 @@ The pre-commit hook checks the whole repository with ESLint and Prettier, then r
 affect generated files, types, dependencies, or TeamCity configuration. It does not rewrite files during a commit; use
 `npm run format` to apply Prettier changes explicitly.
 
-## CSS class names
+## Vite plugins
 
-Register Web UI's `readableCssModuleNames` plugin in every compiler that processes the app's CSS, including development,
-Storybook, and production:
+Register Web UI's Vite plugins in the application configuration:
 
 ```ts
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
-import { readableCssModuleNames } from "@imfusion/web-ui/build/vite-css-module-names";
+import { imfusionBrandAssets, readableCssModuleNames } from "@imfusion/web-ui/vite";
 
 export default defineConfig({
-  plugins: [react(), readableCssModuleNames({ prefix: "app" })]
+  plugins: [react(), imfusionBrandAssets(), readableCssModuleNames({ prefix: "app" })]
 });
 ```
 
-A compiler left out of the plugin produces different class names and styles that appear to work only in some environments.
+`imfusionBrandAssets` serves the complete favicon set during development and emits it at stable root URLs during builds.
+Register `readableCssModuleNames` in every compiler that processes the app's CSS, including development, Storybook, and
+production. A compiler left out produces different class names and styles that appear to work only in some environments.

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

@@ -27,22 +27,39 @@ Never overwrite user changes or commit without fresh approval.
 
 ## Update the base
 
-Run from the consumer package root:
+Before installing, query the registry from the consumer package root:
 
 ```sh
-npm install @imfusion/web-ui
+npm view @imfusion/web-ui dist-tags --json
+```
+
+Honor an explicitly requested version or tag. Otherwise, target `latest`; if the installed version is a prerelease, ask
+whether to use `latest` or `dev` before proceeding. Resolve the selected tag or version with
+`npm view @imfusion/web-ui@<selected-tag-or-version> version --json` and record the exact target version. Stop if the
+registry lookup fails. Report "already current" only when the pre-update version matches this resolved target; npm's "up to
+date" message alone does not prove that.
+
+Install the resolved version, then refresh the existing installer target:
+
+```sh
+npm install @imfusion/web-ui@<resolved-version>
 npx web-ui-install
 npx web-ui-install --hooks
 ```
 
-Use `npm install @imfusion/web-ui@<version>` when the user supplied an explicit version. Stop on install failure. Preserve
-the installer's existing target. Do not use `--force` or `--legacy-peer-deps`.
+Stop on install failure. Preserve the installer's existing target. Do not use `--force` or `--legacy-peer-deps`.
 
 The installer owns the vendored skills, its `AGENTS.md` fence, and hook scripts. Run both installer commands after the
 package update even when the existing registrations look complete: they refresh scripts, prune retired registrations, and
 merge installer-owned entries idempotently into `.claude/settings.json` and `.codex/hooks.json`. Stop on malformed settings
 or installer conflicts. Read existing host registrations first and do not stack an event the project already covers.
 
+After both installer commands, inspect the installed skill diffs and briefly report any guidance changes; version-marker
+changes alone do not count. Re-read changed skills and references relevant to the remaining work, including this update skill
+if it changed. Continue from the current step using the updated guidance, keeping the original baseline, user choices, and
+completed changes in mind. Check for newly required steps without repeating completed mutations or expanding the approved
+scope.
+
 ## Verify the base update
 
 After every mutating command, compare the status with the preflight snapshot. Stop on an unexpected path or overlapping
@@ -51,7 +68,8 @@ change.
 Run the consumer's documented full verification. Read its scripts first; prefer an aggregate check, otherwise run the
 non-watch format, lint, typecheck, test, and build commands that exist.
 
-Check the dependency and lockfile, skill markers, `AGENTS.md` fence, hook registrations, and final update-owned path list.
+Verify that the installed package, manifest, and lockfile match the recorded target version. A mismatch is a base-update
+conflict. Check skill markers, the `AGENTS.md` fence, hook registrations, and the final update-owned path list.
 
 Report before the first commit:
 

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

@@ -1,17 +0,0 @@
-//#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 };