@imfusion/web-ui 0.5.0

package/src/llms/llms.gen.txt

@@ -0,0 +1,176 @@
+# @imfusion/web-ui component index
+
+Each entry below is an identity summary. Props for every component live in
+`node_modules/@imfusion/web-ui/src/docgen/doc.gen.json` (a real file, not the `@imfusion/web-ui/docgen.json`
+package export alias — that alias only resolves via Node's module
+resolver, not via cat/jq/grep on disk), keyed by the kebab-case folder name
+shown as `props:` below — extract one component with `jq` rather than
+reading the whole file. `further reading` links (when present) point at
+the upstream library's own docs for usage/anatomy/composition — not for
+props, which always live in the docgen file above.
+
+## AppShell
+- category: Layout, status: stable
+Application layout shell — a fixed header, collapsible navbar/aside sidebars, an optional footer, and a scrolling main area. The classic dashboard frame; also called an app layout, application frame, dashboard shell, or sidebar layout. Sizing is CSS-driven and sidebars collapse to sliding overlays on small screens.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .app-shell (jq: jq '.app-shell' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Button
+- category: Buttons, status: stable
+Triggers an action — submit, confirm, cancel, navigate, or destructive operations. Six semantic variants (primary, secondary, positive, negative, outline, ghost) communicate intent across four sizes (sm, md, lg, hero). The brand's chamfered shape; hover inverts fill and label. An optional endIcon slot aligns the label left and pins the icon right. Also called a CTA or action.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .button (jq: jq '.button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/button.md
+
+## Callout
+- category: Display, status: stable
+Inline status banner — a persistent, non-interactive message that sits in the content flow to convey info, success, warning, or error state. Composed from slots: Callout.Root wraps a Callout.Icon (status glyph), an optional Callout.Title, and a Callout.Description. Tonal `variant` (info/positive/warning/negative) tints the surface and colours the icon and text. Also called an alert, callout, or inline notice. Not a Toast (transient) or Alert Dialog (modal).
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .callout (jq: jq '.callout' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Card
+- category: Layout, status: stable
+Surface container — groups related content on a tonal background. Composed from slots: Card.Root wraps an optional edge-to-edge Card.Image plus padded Card.Header, Card.Content, and Card.Footer. Tonal or coloured `variant`, opt-in shadow and radius, and a `density` scale. Also called a panel, tile, or paper.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .card (jq: jq '.card' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Checkbox
+- category: Inputs, status: stable
+Binary form control for opt-in choices — accept terms, select table rows, pick list items. Supports an indeterminate state for parent/child selection. Also called a check box or tick box; for immediate on/off preferences, prefer Switch.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .checkbox (jq: jq '.checkbox' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/checkbox.md
+
+## Chip
+- category: Display, status: stable
+Compact inline label for tags, status, categories, counts, or metadata. Also known as a badge, tag, or pill. Two dimensions — a color variant for semantic role and a shape variant for visual appearance, including an inline form that sits naturally in flowing body text.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .chip (jq: jq '.chip' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## ChipLink
+- category: Buttons, status: stable
+Inline link styled as a chip — a small labeled anchor that auto-appends a directional icon. Use for external doc references and source attribution (opens in a new tab) or in-app navigation badges (stays in the current tab). Also called a link chip or link badge.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .chip-link (jq: jq '.chip-link' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Code
+- category: Display, status: stable
+Displays source code — Code.Inline for a fragment in running text, Code.Block for a fenced block with an optional language label and copy button. Also called a code snippet or code block.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .code (jq: jq '.code' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## CodeHighlight
+- category: Display, status: experimental
+Syntax-highlighted drop-in for the Code parts — the same Code.Block and Code.Inline, with TanStack Highlight token coloring that follows the color scheme. Imported from @imfusion/web-ui/integrations/code-highlight; requires the @tanstack/highlight peer.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .code-highlight (jq: jq '.code-highlight' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Collapsible
+- category: Display, status: stable
+Toggleable show/hide region for progressive disclosure — FAQ entries, expandable settings, detail toggles. A trigger button drives an animated open/close panel; multiple stacked form an accordion. Also called a disclosure or expand/collapse.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .collapsible (jq: jq '.collapsible' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/collapsible.md
+
+## CopyButton
+- category: Buttons, status: stable
+Button that copies a value to the clipboard and shows a transient confirmation. Also called a copy-to-clipboard button. Composes Button; commonly paired with Code.Block.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .copy-button (jq: jq '.copy-button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Drawer
+- category: Layout, status: stable
+Off-canvas panel that slides in from a screen edge. Use for mobile navigation, secondary nav, settings trays, filter sidebars, or any side sheet. Also called a sidebar, side panel, off-canvas, or sheet.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .drawer (jq: jq '.drawer' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/drawer.md
+
+## ImageDisplayOptions
+- category: Inputs, status: experimental
+A panel or toolbar of controls bound to an image dataset's display options.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .image-display-options (jq: jq '.image-display-options' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://docs.imfusion.com/
+
+## Input
+- category: Inputs, status: stable
+Single-line text input for form data entry. Also called a text field or input field. Supports controlled and uncontrolled modes, and integrates with Base UI's Field context for validation state (valid, invalid, dirty, touched, filled, focused).
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .input (jq: jq '.input' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/input.md
+
+## Logo
+- category: Display, status: stable
+Brand mark display primitive — renders a logo from a URL or inline React element with consistent sizing. Also called a wordmark, brand icon, or logotype.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .logo (jq: jq '.logo' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## NavigationMenu
+- category: Display, status: experimental
+Navigation menu — a horizontal (or vertical) strip of triggers that open flat, anchored flyout panels for site or app wayfinding, with multi-column mega-menu content and a viewport-responsive inline master/detail submenu. Composed from slots: NavigationMenu.Root, List, Item, Trigger, Icon, Content, Link, FlyoutLink, LinkList, LinkCard, InlineSubmenu, Portal, Positioner, Popup, Viewport, Arrow, Backdrop. Also called a nav bar, menu bar, or mega menu.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .navigation-menu (jq: jq '.navigation-menu' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/navigation-menu.md
+
+## Popover
+- category: Display, status: stable
+Floating panel anchored to a trigger element. Use for contextual menus, tooltips-with-actions, rich hover cards, quick-edit forms, or any non-modal detail overlay. Also called a popup, flyout, or floating menu.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .popover (jq: jq '.popover' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/popover.md
+
+## Row
+- category: Layout, status: stable
+Horizontal layout primitive — children are arranged left-to-right with configurable spacing, alignment, and optional wrapping. Also called hstack, horizontal stack, flex row.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .row (jq: jq '.row' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Select
+- category: Inputs, status: stable
+Single-choice dropdown — pick one value from a known list. Keyboard-accessible listbox with a labelled trigger and a portalled popup. Best for short, fixed option sets (status, role, country). Also called a dropdown or picker.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .select (jq: jq '.select' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/select.md
+
+## Separator
+- category: Layout, status: stable
+Thin line that visually divides content into groups — section break, list item rule, sidebar division. Also called a divider, hr, or horizontal / vertical rule.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .separator (jq: jq '.separator' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/separator.md
+
+## Slider
+- category: Inputs, status: stable
+Drag a thumb along a track to pick a numeric value or range. Use for continuous or stepped numeric input where magnitude matters — volume, brightness, opacity, price ranges. Also called a range input.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .slider (jq: jq '.slider' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/slider.md
+
+## Spinner
+- category: Display, status: stable
+Loading indicator built from the animated ImFusion glyph. Also called a loader, progress spinner, or activity indicator; signals indeterminate loading.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .spinner (jq: jq '.spinner' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Stack
+- category: Layout, status: stable
+Vertical layout primitive — children stack top-to-bottom with configurable spacing and alignment. Use it instead of writing flex column layouts by hand. Also called a vstack or column.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .stack (jq: jq '.stack' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Switch
+- category: Inputs, status: stable
+Two-state toggle for immediate on/off preferences — enable a feature, mute audio, toggle dark mode. Takes effect right away (no submit step); for form-submission booleans, a checkbox is more conventional. Also called a toggle.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .switch (jq: jq '.switch' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/switch.md
+
+## Table
+- category: Display, status: stable
+Styled, static building blocks for tabular data — Root, Header, Body, Row, HeaderCell, Cell, HeaderButton, SortableHeaderCell. Also called a data grid anatomy. Purely presentational with no data logic; for a full data grid, drive these parts with a headless table library (TanStack Table recommended) that you install yourself.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .table (jq: jq '.table' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
+## Tabs
+- category: Display, status: stable
+Tabbed navigation — switches between panels of content within one view via a horizontal (or vertical) strip of labels with a sliding active-state underline. Composed from slots: Tabs.Root, Tabs.List, Tabs.Tab, Tabs.Indicator, Tabs.Panel. Also called a tab strip or tab bar.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .tabs (jq: jq '.tabs' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/tabs.md
+
+## Toggle
+- category: Inputs, status: experimental
+A two-state button that can be on or off. Compose several inside a ToggleGroup for a segmented control.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .toggle (jq: jq '.toggle' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/toggle.md
+
+## ToggleGroup
+- category: Inputs, status: experimental
+A set of connected Toggle buttons sharing one value: single-select by default (a segmented control), or multi-select with `multiple`. Compose one Toggle per segment, each with a value. Also called a segmented control or segmented button.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .toggle-group (jq: jq '.toggle-group' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/toggle-group.md
+
+## Tooltip
+- category: Display, status: stable
+Hover- or focus-triggered floating label giving terse contextual help for a control or term. Use for icon-button descriptions, truncated-text reveals, and field hints. Also called a hint, hovercard, or info bubble; for click-triggered panels with actions use Popover instead.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .tooltip (jq: jq '.tooltip' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/tooltip.md
+
+## Typo
+- category: Display, status: stable
+Typographic primitives — a family of heading (H1–H4), paragraph (P, Lead), and inline accent (InlineCode, Highlight, Link) components. Most support a color role — main, support, or minor — plus the standard HTML attributes for its element; InlineCode is a fixed neutral chip (it renders Code.Inline).
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .typo (jq: jq '.typo' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)

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

@@ -0,0 +1,46 @@
+---
+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."
+---
+
+# imf-web-ui
+
+`@imfusion/web-ui` ships a small family of skills. This one is the map — it costs almost nothing to load and tells you which
+companion to open, or that you need none at all. Don't load a companion speculatively: route first, zoom second.
+
+## Row zero — is help needed at all?
+
+Before routing, check whether this task needs guidance in the first place. It does **not** when:
+
+- The request is explicit and small ("make the button say Save", "add a column for email"), or
+- You're repeating a pattern that already exists nearby in the codebase — copy it, and
+- The components involved are already imported and used correctly.
+
+In that case: just do the work. At most, do a silent props lookup via `imf-web-ui-components` if you're unsure of an API.
+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, 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 around the library; styling beyond defaults; state or code structure   | `imf-web-ui-frontend-patterns` |
+
+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.
+
+## When to interview the human
+
+`imf-web-ui-ux` contains a short per-feature interview. Run it **only** when both hold:
+
+1. The request is foggy — you couldn't say what the primary action of the screen is, who uses it, or what data it shows.
+2. A human is available to answer.
+
+Never interview when a spec, mockup, or clear instruction exists — asking questions the conversation already answered is
+worse than not asking at all. When in doubt and no human is around, make the conservative choice, and say which assumptions
+you made.

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

@@ -0,0 +1,100 @@
+---
+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)."
+---
+
+# imf-web-ui-components
+
+`@imfusion/web-ui` ships two generated files inside `node_modules` so an agent can discover and use its components without
+reading source or checking out the library's repo:
+
+- **`node_modules/@imfusion/web-ui/src/llms/llms.gen.txt`** — an identity index: every component's name, category, status,
+  and a one-sentence description of what it's for and what else it's called.
+- **`node_modules/@imfusion/web-ui/src/docgen/doc.gen.json`** — full prop tables (name, type, default, description) for every
+  component, keyed by kebab-case folder name.
+
+Neither file is reachable through the package's pretty import paths (`@imfusion/web-ui/llms.txt`,
+`@imfusion/web-ui/docgen.json`) — those are Node module-resolution aliases, meaningless to `cat`/`jq`/`grep` reading files
+off disk. Use the `node_modules/...` paths above directly.
+
+## The lookup, in two hops
+
+**Hop 1 — find the component.** Read the whole index; it's small (~13KB for the full library) and safe to load in full:
+
+```sh
+cat node_modules/@imfusion/web-ui/src/llms/llms.gen.txt
+```
+
+Each entry looks like this:
+
+```
+## Button
+- category: Buttons, status: stable
+Triggers an action — submit, confirm, cancel, navigate, or destructive operations. Six semantic variants ...
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .button (jq: jq '.button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/button.md
+```
+
+**Hop 2 — pull that component's props.** Don't read the whole docgen file (~500KB across all components) — slice out just the
+one entry with the exact command the index gave you:
+
+```sh
+jq '.button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json
+```
+
+That returns `{ root: { name, description, props: [...] }, subComponents: [...] }`. `root` is the primary export (`Button`);
+`subComponents` holds compound parts (e.g. `Drawer.Root`, `Drawer.Trigger`, `Drawer.Content` all live under the `drawer`
+key). Match the sub-component you need by its dotted `name`.
+
+**`jq` may not be installed.** Check with `which jq` before relying on it. If it's missing, do **not** fall back to reading
+the whole `doc.gen.json` file — that defeats the entire point of the two-hop design (~500KB across all components vs. one
+~9KB entry) and will burn your context budget for no reason. Use whatever's actually available instead:
+
+```sh
+node -e "console.log(JSON.stringify(JSON.parse(require('fs').readFileSync('node_modules/@imfusion/web-ui/src/docgen/doc.gen.json','utf8')).button, null, 2))"
+```
+
+(Node ships everywhere this package can be installed, so this always works as a fallback.) Or ask the user to install `jq` if
+you expect to look up several components in one session.
+
+**"Further reading" links, if present, are not a props source.** They point at the upstream library's (usually Base UI's) own
+documentation for composition, anatomy, keyboard/focus behavior, and accessibility notes docgen can't express. Props always
+come from `doc.gen.json` — never treat the linked page's prop table as authoritative for a web-ui component; web-ui may add,
+remove, or default differently.
+
+## A component not found in the index?
+
+The index is regenerated on every `@imfusion/web-ui` release; it should be exhaustive. If a component you expect is missing,
+don't guess at an API — that's a real gap to report, not something to work around by inventing props. Tell the web-ui
+maintainer, or file it in the [WEBSDK Jira project](https://imfusion.atlassian.net/browse/WEBSDK) if you have access. If the
+gap is about _which_ component to use rather than a missing one, that's a design question: open `imf-web-ui-ux`.
+
+## Compound components
+
+A component whose docgen entry has a non-empty `subComponents` array is used as a namespace, not a single import — e.g.
+`import { Drawer } from "@imfusion/web-ui"` then `<Drawer.Root>`, `<Drawer.Trigger>`, `<Drawer.Content>`. The index's
+category/description covers the whole family; look at `subComponents` in the docgen entry to see which parts exist and what
+each one's own props are.
+
+## Integrations (own-entry components)
+
+A description mentioning "Imported from `@imfusion/web-ui/integrations/<name>`" is a signal this component isn't in the
+default import — e.g.:
+
+```tsx
+import { Code } from "@imfusion/web-ui/integrations/code-highlight";
+```
+
+These exist because their behavior depends on an optional peer dependency (e.g. `@tanstack/highlight` for `CodeHighlight`)
+that most consumers shouldn't be forced to install. Check the component's description for which peer to add, and add it
+explicitly to your own `package.json` — web-ui does not install it for you.
+
+## Data grids (Table + a headless library)
+
+For a data grid, drive the styled `Table` parts with a headless table library you install yourself. **TanStack Table**
+(`@tanstack/react-table`) is recommended. Map your `useReactTable` instance onto `Table.Root` / `Table.Header` / `Table.Row`
+/ `Table.Cell`, and use `Table.SortableHeaderCell` for sortable columns — it carries the `aria-sort` state and the sort
+indicator. See the Table primitive's Storybook docs for the pairing.

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

@@ -0,0 +1,67 @@
+---
+name: imf-web-ui-frontend-patterns
+description:
+  "Raise the quality of frontend code written around @imfusion/web-ui — including quickly vibe-coded frontends. Library
+  boundary contract (tokens, CSS layers, type derivation), component roles, state placement, effects discipline, and stack
+  defaults. Load when writing wrapper components, custom UI, or styling beyond the defaults."
+---
+
+# imf-web-ui-frontend-patterns
+
+One guard, once: **if the host project already has a convention — a styling system, a state library, a folder shape — the
+project wins.** These defaults fill vacuums. They are not a license to refactor a consumer codebase toward this document.
+
+Everything else below is how to build.
+
+## Stay behind the library
+
+Never import Base UI (or any other upstream this library wraps) directly — no upstream stylesheets, no upstream components,
+even when upstream docs show it that way. Everything a component needs ships in `@imfusion/web-ui`. If the library is missing
+something upstream has, report the gap (see `imf-web-ui-components`); don't reach around it.
+
+## Style through the sanctioned seams
+
+All library styles live in the `imf-ui.components` CSS layer, so **any plain selector you write wins** — that's the whole
+override contract:
+
+- Target the stable hooks: `data-imf-ui-component` attributes and your own classes/wrappers.
+- Never target the library's internal class names — they are generated and change without notice.
+- Never `!important` — if you think you need it, you're targeting the wrong thing.
+
+## Build custom UI from tokens
+
+Anything you build that the library doesn't cover — a stat widget, a custom panel — uses `--imf-ui-*` variables for color,
+spacing, radius, and type instead of hardcoded values. That's what makes custom UI look native next to library components,
+and what keeps it correct when the theme changes. A hex code or a magic `px` next to a concept the tokens already name is a
+defect.
+
+## Derive types, don't import them
+
+Prop types come from the components themselves: `React.ComponentProps<typeof Button>`. The library deliberately exports no
+`Props` types — don't look for them, and don't re-declare prop shapes by hand.
+
+## Integrations own their peers
+
+Components under `@imfusion/web-ui/integrations/*` depend on optional peers (e.g. `@tanstack/highlight` for `CodeHighlight`).
+Add the peer explicitly to the consumer's `package.json` — never rely on hoisting.
+
+## React patterns
+
+The full treatment — component roles with an example, state placement, effects discipline, and the react.dev sources to
+consult while building — lives in [references/react-patterns.md](references/react-patterns.md). Read it before writing new
+screens or wrappers. The core in one breath:
+
+- **Three roles.** Dumb components own how things look, layout components own arrangement, smart containers own data and
+  logic. Styling never lives in containers.
+- **State lives where its truth lives.** URL → query cache → context → store → local state; walk the list, stop at the first
+  match.
+- **Effects are a last resort**, and always extracted into purpose-named hooks.
+- **Compose, don't configure.** If a component's prop list reads like a settings page, it wanted to be two or three
+  components.
+
+## Starting a frontend from scratch
+
+When the consumer app is greenfield, default to the TanStack suite: **Router** (URL state, type-safe search params),
+**Query** (server state), **Form** (form state), and **Table** for data grids, which you pair with web-ui's styled `Table`
+parts (`Table.SortableHeaderCell` carries the sort glue). Documentation is available straight from the terminal via
+`npx tanstack`. This is the stack the state ladder assumes.

package/src/llms/skills/imf-web-ui-frontend-patterns/references/react-patterns.md

@@ -0,0 +1,94 @@
+# React patterns
+
+The house defaults for the React code around `@imfusion/web-ui`, in full. The links throughout are for **you, the agent**:
+consult them while building — they are the authoritative source when a case here is ambiguous. Hand them to the human only if
+asked.
+
+## Component roles
+
+Dumb/smart separation is standard React practice (it traces back to Dan Abramov's
+["Presentational and Container Components"](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) and
+survives in [Thinking in React](https://react.dev/learn/thinking-in-react)). The house version has three roles:
+
+- **Dumb components** own how things _look_. They style and compose library primitives, receive plain data and callbacks as
+  props, and know nothing about fetching, routing, or business logic. All non-layout styling lives here — and only here.
+- **Layout components** own _arrangement_ — and nothing else. `Stack`- and `Row`-based wrappers with token gaps, a page grid,
+  a section frame. They exist because smart containers are styleless: when a container needs two panels side by side, that
+  arrangement is a layout component, not an inline style.
+- **Smart containers** own how things _work_. Routes (or explicit container components) fetch data, hold orchestration logic,
+  and wire the other two together. Zero styling — the moment a container wants CSS, extract a layout component.
+
+```tsx
+// Dumb — renders what it's given
+function UserCard({ name, role, onEdit }: { name: string; role: string; onEdit: () => void }) {
+  return (
+    <Card.Root>
+      <Card.Content>
+        <Typo>{name}</Typo>
+        <Chip>{role}</Chip>
+      </Card.Content>
+      <Card.Footer>
+        <Button onClick={onEdit}>Edit</Button>
+      </Card.Footer>
+    </Card.Root>
+  );
+}
+
+// Smart — knows where data comes from, renders the dumb component
+function UserCardContainer({ userId }: { userId: string }) {
+  const { data } = useUserQuery(userId);
+  const openEditor = useEditorNavigation(userId);
+  return <UserCard name={data.name} role={data.role} onEdit={openEditor} />;
+}
+```
+
+Why it matters here: dumb components are the layer where `@imfusion/web-ui` lives. Keeping them free of logic keeps every
+screen restylable, testable with plain props, and resilient to library updates. The one web-ui-specific addition: wrap
+`experimental` components (marked in the identity index) in a dumb component once per app even if you add nothing yet — a
+breaking upstream change then lands in one file instead of every call site.
+
+## Compose, don't configure
+
+Build screen-level pieces by composing primitives (`Stack`, `Row`, `Card`, your dumb components) rather than growing one
+component with a dozen boolean props. If a component's prop list reads like a settings page, it wanted to be two or three
+components. When state must be shared between siblings, lift it to the nearest common parent —
+[Sharing State Between Components](https://react.dev/learn/sharing-state-between-components) — rather than syncing copies.
+
+## Put state where its truth lives
+
+Work down this list and stop at the first match:
+
+1. **Shareable via URL?** (filters, sort, pagination, active tab) → router search params. Back button and copied links are UX
+   features you get for free.
+2. **Comes from an API?** → the data-fetching layer's cache (e.g. TanStack Query). Never copy server data into `useState` —
+   that's how stale-UI bugs are born.
+3. **Scoped to a subtree, resets on leave?** (wizard progress) → React context.
+4. **App-wide and persistent?** → a client store, and only now.
+5. **Local to one component?** (input value, open/closed) → `useState`.
+
+Most frontends need far less of tier 4 than they think; tiers 1–2 usually dissolve the "we need a store" instinct. For
+structuring the state itself, [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) is the
+reference — especially its rules on avoiding redundant and duplicated state.
+
+## Effects: last resort, and named
+
+Before writing `useEffect`, check: derived values belong in render (or `useMemo`), responses to user actions belong in the
+event handler, and server synchronization belongs in the data-fetching layer. Effects are for synchronizing with systems
+_outside_ React. The definitive catalog of effect misuses — read it before every effect you're tempted to write — is
+[You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect).
+
+When an effect is genuinely needed, extract it into a custom hook named for its purpose — `useSyncedScroll`,
+`useDocumentTitle`, `useHotkey` — never an anonymous `useEffect` block inline in a component. The name documents intent, the
+hook isolates the dependency array, and the component body stays declarative. Pattern reference:
+[Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks).
+
+## Reading list
+
+Consult while building; each is the authority for its topic:
+
+- [Thinking in React](https://react.dev/learn/thinking-in-react) — decomposition and one-way data flow
+- [Keeping Components Pure](https://react.dev/learn/keeping-components-pure) — why dumb components stay dumb
+- [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) — shaping state without duplication
+- [Sharing State Between Components](https://react.dev/learn/sharing-state-between-components) — lifting state
+- [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) — the effect misuse catalog
+- [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) — named effects live here

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

@@ -0,0 +1,30 @@
+---
+name: imf-web-ui-setup
+description:
+  "One-time wiring of @imfusion/web-ui into a consumer project: the styles import and the WebUIProvider wrapper. Load when
+  installing the library for the first time, or when its components render unstyled or without theme context."
+---
+
+# imf-web-ui-setup
+
+Every consumer entry point needs exactly two lines, in this order:
+
+```tsx
+import "@imfusion/web-ui/styles.css";
+import { WebUIProvider, Button } from "@imfusion/web-ui";
+```
+
+Wrap the app root in `<WebUIProvider>` once. Components rendered outside it won't have the theme/CSS-variable context they
+expect.
+
+Never import a Base UI (or other upstream) stylesheet or component directly — everything a web-ui component needs is already
+inside `styles.css` and the package's own exports; reaching around web-ui to the upstream library is always wrong, even if
+the upstream docs show it that way.
+
+## Symptoms of a broken setup
+
+- **Components render but look unstyled** — the `styles.css` import is missing from the entry point.
+- **Components render but ignore the theme (wrong colors, no CSS variables resolving)** — they're mounted outside
+  `<WebUIProvider>`.
+- **An integration component throws on import** — its optional peer dependency isn't installed; check the component's
+  description in the docgen index (`imf-web-ui-components`) for which peer to add to your `package.json`.

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

@@ -0,0 +1,103 @@
+---
+name: imf-web-ui-ux
+description:
+  "UX guidance for building screens with @imfusion/web-ui when no designer is around: pick the right component for an
+  interaction, lay out common screen types, handle empty/loading/error states. Load when building or reshaping a screen,
+  flow, or feature UI — not for prop lookups (that's imf-web-ui-components)."
+---
+
+# imf-web-ui-ux
+
+Most teams consuming `@imfusion/web-ui` don't have a designer on call. This skill stands in: it encodes the library authors'
+UX experience — the whole experience of a screen, its visual design, and the usability where both meet. Follow it by default;
+deviate when the product has a real reason to. Code-level patterns (tokens, layers, wrappers) live in
+`imf-web-ui-frontend-patterns`; project wiring lives in `imf-web-ui-setup`.
+
+Component names below are real — verify any API against the docgen index (`imf-web-ui-components`) before use. Never invent a
+component this library doesn't ship.
+
+## Before recommending or building: the interview
+
+If — and only if — the request is foggy and a human is available, ask what the conversation hasn't already answered, from
+this list, and nothing more. This applies to recommendation questions, not just build tasks: when someone asks "which
+component for X?" and the choice hinges on facts you don't have (how many controls, how often used, how much data), **ask
+those questions first and recommend after** — don't recommend and then list caveats, because the caveats _are_ the interview,
+inverted.
+
+1. Who uses this screen, and how often? (daily power-user tool vs. occasional visit changes density and shortcuts)
+2. What is the **one** primary action? (a screen with three primary buttons has zero)
+3. What data does it show — shape and volume? (5 rows or 5,000 decides table vs. cards vs. search-first)
+4. What happens when it's empty, loading, or failing?
+5. Where does it live — full page, or a step inside another flow?
+
+If no human is around: make the conservative choice, and state your assumptions in the handoff.
+
+## Choosing the surface
+
+- **Full page** — the default. Reach for an overlay only when context must be preserved behind the task.
+- **`Drawer`** — a focused sub-task that interrupts the page: edit-details, multi-field create, confirm-with-context. This
+  library ships no modal `Dialog`; `Drawer` is the blocking surface. If a true centered dialog is genuinely required, raise
+  it upstream — don't hand-roll one.
+- **`Popover`** — light, dismissable, contextual: a small form, a filter panel, extra actions. If it needs a heading and
+  three fields, it wanted to be a `Drawer`.
+- **`Tooltip`** — hints only. Never essential information, never interactive content.
+- **`Collapsible`** — progressive disclosure inside the page: advanced options, long secondary content.
+- **`Tabs`** — parallel views of the same subject. If users must complete all of them, it's a flow, not tabs.
+
+## Choosing between look-alikes
+
+- **`Button` vs. `ChipLink` vs. `Chip`** — does it _do_ something (`Button`), _go_ somewhere (`ChipLink`), or _label_
+  something (`Chip`)?
+- **`Table` alone vs. `Table` + a table library** — static, small data reads fine as bare `Table` parts; the moment sorting,
+  pagination, or column logic appears, drive the parts with a headless table library (TanStack Table recommended) you install
+  yourself, using `Table.SortableHeaderCell` for the sort glue.
+- **`Callout` vs. transient feedback** — `Callout` is for persistent, in-place status (errors, warnings, empty-state hints).
+  The library ships no `Toast`; for fire-and-forget confirmations prefer inline feedback near the trigger, and raise the
+  toast need upstream rather than hand-rolling one.
+- **`Input`/`Select`/`Checkbox`/`Switch`/`Slider`** — `Switch` for instant effect, `Checkbox` for submitted forms; `Select`
+  beyond ~5 options, radio-style choices below that; `Slider` only when the _relative_ position means more than the exact
+  number.
+
+## Layout and hierarchy
+
+- Frame the app with **`AppShell`**; inside it, compose **`Stack`** and **`Row`** with token-based gaps instead of
+  hand-written flex containers with magic-number margins. **`Separator`** over border hacks.
+- Text hierarchy comes from **`Typo`** — pick levels by role (page title, section, body, caption), don't skip levels for
+  visual effect, don't style raw HTML headings next to it.
+- **One primary action per view.** Everything else uses the quieter `Button` variants (see its docgen entry for the semantic
+  variant list). If two things compete for primary, decide which one the screen is _for_.
+- Density follows the interview: power-user + high volume → compact tables, visible shortcuts; occasional use + low volume →
+  generous spacing, explanatory text.
+
+## States are part of the screen
+
+Every screen ships four states, not one:
+
+- **Empty** — say what this screen _will_ show and what to do next; an empty `Table` with no explanation is a bug.
+- **Loading** — `Spinner`, or skeletons for known layouts; keep the frame stable so content doesn't jump in.
+- **Error** — `Callout` with what failed and what the user can do; never a blank region, never only a console log.
+- **Loaded** — the one you were going to build anyway.
+
+## Looking native
+
+Custom UI the library doesn't cover should be indistinguishable from library UI: build it from `--imf-ui-*` tokens and
+compose it with library primitives. The goal lives here; the mechanics (tokens, layers, wrappers) live in
+`imf-web-ui-frontend-patterns`.
+
+## Experimental components
+
+The identity index marks each component `stable` or `experimental`. Experimental ones are fine to use, but expect API
+movement across releases — prefer wrapping them once (see `imf-web-ui-frontend-patterns`) so a breaking change lands in one
+file, not forty call sites.
+
+## Deep dives
+
+The 80/20 fundamentals behind this skill's advice, distilled from authoritative sources, live in child files. Read the one
+that matches the work — they are for you, the agent, while designing; hand the source links to the human only on request:
+
+- [references/usability-heuristics.md](references/usability-heuristics.md) — Nielsen's ten heuristics, applied to web-ui
+  screens. Read when reviewing or reworking an existing flow.
+- [references/visual-design.md](references/visual-design.md) — hierarchy, grouping, alignment, whitespace. Read when a screen
+  is functionally complete but looks wrong and you can't say why.
+- [references/forms.md](references/forms.md) — form layout, labels, validation timing, error wording. Read before building
+  any form beyond two fields.