@imfusion/web-ui 0.11.1-dev.6.gf4b6c627 → 0.11.1-dev.62.gfcd31b6e

package/src/llms/llms.gen.txt

@@ -19,6 +19,12 @@ The signed-in person's account row: the avatar in a lead column, the name or ema
 Application layout shell for a header, sidebars, footer, and scrolling main area. Also called an app layout or dashboard shell; sizing is CSS-driven and sidebars can become sliding panels 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)
 
+## Autocomplete
+- category: Inputs, status: experimental
+Text input that suggests options as you type, keeping free text. Also called a typeahead or search suggestions. Use Combobox when the value must come from the list.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .autocomplete (jq: jq '.autocomplete' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/autocomplete.md
+
 ## Avatar
 - category: Display, status: experimental
 Round badge that stands for a person, showing their photo, their initials, or a person glyph. Also called a profile picture or user badge; for a signed-in account row with a name, use AccountCard.
@@ -78,6 +84,12 @@ Show-and-hide region for secondary content such as FAQs, settings, or details. A
 Light, System, and Dark segments that set and remember the page's color scheme. Also called an appearance or theme switch; built on ToggleGroup, which is the choice for any other segmented selection.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .color-scheme-toggle (jq: jq '.color-scheme-toggle' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
+## Combobox
+- category: Inputs, status: experimental
+Text input with a filterable list of options, for choosing one or several from a long list. Also called a searchable select, typeahead, or multi-select. Use Select for short lists and Autocomplete when free text is allowed.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .combobox (jq: jq '.combobox' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/combobox.md
+
 ## CopyButton
 - category: Buttons, status: stable
 Copies a value to the clipboard and briefly shows confirmation. Also called a copy-to-clipboard button; commonly used with Code.Block.
@@ -107,6 +119,11 @@ Semantic group for related form controls with a shared legend. Also called a for
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .fieldset (jq: jq '.fieldset' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/fieldset.md
 
+## FileDropZone
+- category: Inputs, status: experimental
+Drop zone with picker buttons for files or whole folders, reporting accepted and rejected files. Also called a file upload area or dropzone. For a single native file control inside a form, use Input.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .file-drop-zone (jq: jq '.file-drop-zone' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
 ## FrameSelection
 - category: Inputs, status: experimental
 Frame or slice picker bound to the focused frame of ImFusion image sets, with a focus and count readout. For a position picker not tied to the SDK, use Slider with variant="position".
@@ -123,6 +140,11 @@ Renders a Web UI icon with an optional semantic foreground color. The default in
 Square button that shows a single icon and no visible text, with its accessible name from `label`. Also called an icon-only or toolbar button. Use Button with `startIcon` or `endIcon` when a text label is visible.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .icon-button (jq: jq '.icon-button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
+## Image
+- category: Display, status: experimental
+Picture with AVIF and WebP sources, reserved space, lazy loading, and a fallback while it loads or when it fails. Also called a photo, thumbnail or media. Use Avatar for a person and Card.Image for a card's edge-to-edge slot.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .image (jq: jq '.image' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
 ## ImageDisplayOptions
 - category: Inputs, status: experimental
 Panel and toolbar controls for an image dataset's display options, including window, level, gamma, and invert settings.
@@ -140,6 +162,12 @@ Single-line text input for form data entry. Also called a text field; it support
 Shows a keyboard key or shortcut, such as the letter that activates a button. Also called a key hint; Button and Toggle render it through their `shortcut` prop.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .kbd (jq: jq '.kbd' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
+## LayoutMode
+- category: Inputs, status: experimental
+Picker bound to the ImFusion viewer's layout mode: Auto, Rows, Focus + stack, or Focus + rows, as a compact icon row or a labeled vertical list. Also called a layout or view arrangement switch; for a segmented choice not tied to the SDK, use ToggleGroup.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .layout-mode (jq: jq '.layout-mode' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://docs.imfusion.com/
+
 ## Logo
 - category: Display, status: stable
 Renders a logo from a URL or inline React element with consistent sizing. Also called a wordmark or brand mark.
@@ -169,6 +197,12 @@ Floating panel anchored to a trigger for contextual content, quick forms, or act
 - 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
 
+## Progress
+- category: Display, status: experimental
+Bar for the completion of a running task, such as an upload or export. Also called a progress bar. Indeterminate when the amount is unknown. Use Meter for a static measure within a range.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .progress (jq: jq '.progress' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/progress.md
+
 ## Prose
 - category: Layout, status: experimental
 Flow container that spaces long-form text and the blocks inside it. Also called an article or rich-text container. Use Stack or Row for UI layout.
@@ -229,6 +263,11 @@ Two-state control for an on/off setting that takes effect immediately. Also call
 - 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
 
+## TabNav
+- category: Display, status: experimental
+Row of links to routes with a bar under the current one, such as the sections of a project. Also called route tabs or link tabs; use Tabs to switch panels on one page.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .tab-nav (jq: jq '.tab-nav' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
 ## Table
 - category: Display, status: stable
 Presentational table parts for static tabular data. Pair them with a headless table library for sorting, pagination, or selection.
@@ -236,10 +275,16 @@ Presentational table parts for static tabular data. Pair them with a headless ta
 
 ## Tabs
 - category: Display, status: stable
-Switches between related panels within one view. Also called a tab strip or tab bar; it supports horizontal and vertical layouts.
+Switches between related panels within one view. Also called a tab strip or tab bar; it supports horizontal and vertical layouts and a boxed or underline look. Use TabNav for links to routes.
 - 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
 
+## Textarea
+- category: Inputs, status: experimental
+Multi-line text input for longer free text, such as a description or note. Also called a text area; use Input for a single line. It reads validation state from Field.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .textarea (jq: jq '.textarea' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/input.md
+
 ## Toast
 - category: Display, status: experimental
 Transient message stack that reports the outcome of a background action without interrupting the page. Use for save confirmations, undo offers, and async progress; attach one to an element for contextual feedback like a copy confirmation. Also called a snackbar, notification, or flash message; for a message that stays inline in the page use Callout instead.
@@ -268,3 +313,9 @@ Hover- or focus-triggered label for brief help about a control or term. Also cal
 - category: Display, status: stable
 Semantic text primitives for display and standard headings, paragraphs, lists, quotes, links, and inline code. The namespace uses native HTML elements and token-based text roles.
 - 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)
+
+## ViewTools
+- category: Inputs, status: experimental
+Toolbar that limits mouse interaction in the ImFusion main 2D and MPR views to pan, zoom, or windowing, with a reset button for the view group. For a segmented control not tied to the SDK, use ToggleGroup.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .view-tools (jq: jq '.view-tools' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://docs.imfusion.com/

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

@@ -66,8 +66,11 @@ next action is the add from that topic. A Vite config that reads tsconfig `paths
 `vite-tsconfig-paths`) is Broken: it loads the React types package as React once Web UI comes from the registry. The fix is
 to drop it and give the `#/` alias through `imports` in `package.json`. A major or minor mismatch between the project and Web
 UI on a package listed under Aligned runtime packages in the `tooling` topic is a Deviation. Report both versions, with
-`npm install <package>@<Web UI's version>` as the fix. A route file that holds several views inline is a Deviation, and so is
-a route whose only view sits alone in its `-` folder. Name the views, with the move as the fix.
+`npm install <package>@<Web UI's version>` as the fix. An `engines.node` that admits a Node outside the `engines.node` of the
+installed `node_modules/@imfusion/web-ui/package.json` is a Deviation; report both ranges, with Web UI's as the fix. A route
+file that holds several views inline is a Deviation, and so is a route whose only view sits alone in its `-` folder. Name the
+views, with the move as the fix. A form whose state and validation are written by hand instead of TanStack Form is a
+Deviation, however many forms share the pattern. Name each form, with TanStack Form and its existing schema as the fix.
 
 ## Topics
 

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

@@ -25,11 +25,11 @@ a gap or to make a deliberate deviation visible; do not refactor a project just
 | [styling](topics/styling.md)                     | Writing CSS or customizing Web UI.                              |
 | [tokens](topics/tokens.md)                       | Choosing an exact token name.                                   |
 | [class-names](topics/class-names.md)             | Mapping variants and `className` to CSS.                        |
-| [validation](topics/validation.md)               | Accepting data from outside the frontend.                       |
+| [validation](topics/validation.md)               | Accepting data from outside the frontend, or building a form.   |
 | [data](topics/data.md)                           | Adding API queries, mutations, or invalidation.                 |
 | [project-structure](topics/project-structure.md) | Adding files or routes.                                         |
 | [testing](topics/testing.md)                     | Deciding what to test.                                          |
-| [tooling](topics/tooling.md)                     | Adding a dependency or configuring a tool.                      |
+| [tooling](topics/tooling.md)                     | Adding a dependency, configuring a tool, or building a form.    |
 | [npm-project](topics/npm-project.md)             | Changing `package.json`, scripts, pins, or Node.                |
 | [git](topics/git.md)                             | Configuring hooks or choosing verification scope.               |
 | [agent-tooling](topics/agent-tooling.md)         | Installing skills or lifecycle hooks.                           |

package/src/llms/skills/imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md

@@ -2,7 +2,8 @@
 
 One block per topic, one box per topic section. Check a box only after checking that section's rules against the repo. A full
 audit checks every box; a scoped audit names its topics first and checks only their blocks. Blocks mirror each topic's `##`
-sections one to one — change a topic's sections and this file follows in the same commit.
+sections one to one, and a topic split into a folder gets one `###` block per subtopic — change a topic's sections and this
+file follows in the same commit.
 
 ## Library setup — `library-setup`
 
@@ -35,10 +36,23 @@ sections one to one — change a topic's sections and this file follows in the s
 
 ## React — `react`
 
+### Composition — `react/composition`
+
 - [ ] Composition: pages (smart containers), partials, dumb components
 - [ ] Compose, don't configure
+- [ ] Render rules
+
+### State — `react/state`
+
 - [ ] Put state where its truth lives
+- [ ] State shape
+- [ ] Fallbacks without TanStack
+
+### Effects — `react/effects`
+
 - [ ] Effects: last resort, and named
+- [ ] Dependencies
+- [ ] Effect Events for values the effect should not react to
 
 ## Components — `components`
 
@@ -46,6 +60,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Grouping
 - [ ] One file or a folder
 - [ ] Colocation
+- [ ] Semantic elements
 
 ## TypeScript & code style — `typescript`
 
@@ -80,6 +95,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Schema first, type derived
 - [ ] TanStack Router search params
 - [ ] Failure handling
+- [ ] Forms
 
 ## Data — `data`
 
@@ -127,7 +143,8 @@ sections one to one — change a topic's sections and this file follows in the s
 ## Assets — `assets`
 
 - [ ] Importing
-- [ ] Photographs: WebP
+- [ ] Photographs: AVIF and WebP
+- [ ] Loading
 - [ ] Other formats
 - [ ] Scope
 

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

@@ -8,15 +8,39 @@ consumed by document metadata or manifests, with a build step that serves the fi
 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
+## Photographs: AVIF and WebP
 
-Convert photographs to WebP before adding them:
+Encode photographs as AVIF and WebP at 800 and 1600px wide. A source narrower than a width skips it, and `srcSet` lists only
+the widths that exist:
 
 ```sh
-magick source.png -resize 2000x -quality 80 -define webp:method=6 src/assets/name.webp
+for w in 800 1600; do
+  magick source.png -resize "${w}x>" -quality 55 src/assets/name-$w.avif
+  magick source.png -resize "${w}x>" -quality 80 -define webp:method=6 src/assets/name-$w.webp
+done
 ```
 
-Keep the long edge at 2000px or less. WebP is supported by the browser floor.
+Render them through `<picture>`: an AVIF `<source>`, then a WebP `<source>`, each with `srcSet` and `sizes`, then an `<img>`
+fallback. The browser takes the first format it supports at the width that fits. Both formats are supported by the browser
+floor.
+
+```tsx
+<picture>
+  <source type="image/avif" srcSet={`${name800Avif} 800w, ${name1600Avif} 1600w`} sizes="(max-width: 40rem) 100vw, 40rem" />
+  <source type="image/webp" srcSet={`${name800Webp} 800w, ${name1600Webp} 1600w`} sizes="(max-width: 40rem) 100vw, 40rem" />
+  <img src={name800Webp} width={800} height={400} alt="…" />
+</picture>
+```
+
+`Image` from `@imfusion/web-ui` renders this `<picture>` from `avifSrcSet`, `webpSrcSet`, `srcSet`, `sizes`, `width`,
+`height` and `alt`. It adds lazy loading and async decoding, a pulse while the image loads and a glyph when it fails. Use it
+for content images instead of writing the `<picture>` by hand.
+
+## Loading
+
+Every `<img>` carries `width` and `height` in the source's aspect ratio, so the browser reserves its space before it loads.
+An image below the fold gets `loading="lazy"` and `decoding="async"`. The one image that is the page's largest paint gets
+`fetchpriority="high"` and loads eagerly.
 
 ## Other formats
 

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

@@ -53,3 +53,13 @@ Keep a component's stylesheet, tests, and local types beside the component. A co
 be a layout or dumb component instead.
 
 A route-local component keeps its stylesheet and tests in the route's `-` folder beside it.
+
+## Semantic elements
+
+Inside `AppShell`, the shell's parts render the landmarks: `AppShell.Header` a `<header>`, `AppShell.Navbar` a `<nav>`,
+`AppShell.Aside` an `<aside>`, `AppShell.Main` the page's one `<main>`, and `AppShell.Footer` a `<footer>`. A page puts its
+content inside those parts.
+
+Custom markup uses the element for its meaning: `<section>` and `<article>` for content groups, `<time dateTime>` for a date,
+`Button` for an action, and the router's `Link` for a destination. A page has one `Typo.H1`, and heading levels descend
+without skipping.

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

@@ -7,6 +7,9 @@ integration seams.
 
 - Do not import Base UI or another implementation package directly, including its stylesheet.
 - If Web UI is missing a component or part, report the gap instead of reaching around it.
+- Use what Web UI already ships before building your own: a component, a part, or a helper such as `initialsFromName`. A
+  native element or local function that duplicates one, such as a `div role="separator"` or a hand-written initials function,
+  is a finding.
 - Import glyphs from `@imfusion/web-ui/icons` and render them with `Icon`.
 
 ## Stand in for a missing component

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

@@ -5,7 +5,8 @@ Keep project metadata, scripts, and dependency policy in `package.json` and the
 ## package.json
 
 - Use ESM with `"type": "module"`.
-- Set the Node floor with `engines.node` or `.nvmrc`.
+- Set `engines.node` to the range in Web UI's own `package.json`, so the app promises no Node that Web UI or the `#/` alias
+  rejects. A `.nvmrc` selects a version inside that range.
 - Use the `#/` source alias when the project has one, and wire it through the package `imports` field.
 - Set `private: true` only for packages that are never published.
 

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

@@ -0,0 +1,54 @@
+# React composition
+
+Which role a component plays, and how parts combine.
+
+## Composition: pages (smart containers), partials, dumb components
+
+- **Pages** live in `routes/`. They load data, read URL state, coordinate actions, and compose the view. Route files hold the
+  search schema, loaders, and pending, error, and not-found components. They do not own component CSS. Route-local views and
+  forms live in the route's `-` folder, as [project-structure.md](../project-structure.md) describes, and that folder's
+  `.module.css` files are component styles.
+- **Partials** are compositions that more than one route uses, extracted because they read as a unit. They have light logic
+  and no styling of their own.
+- **Layout components** arrange content with `Stack`, `Row`, grids, and token gaps, and wrap long-form text in `Prose`.
+- **Dumb components** receive data and callbacks, render UI, and own their styles. They do not fetch, route, or contain
+  business rules.
+
+```tsx
+function UserCard({ name, onEdit }: { name: string; onEdit: () => void }) {
+  return (
+    <Card.Root>
+      <Typo.P>{name}</Typo.P>
+      <Button onClick={onEdit}>Edit</Button>
+    </Card.Root>
+  );
+}
+```
+
+## Compose, don't configure
+
+Compose small parts instead of making one component configurable through many boolean props. Lift shared state to the nearest
+common parent.
+
+## Render rules
+
+These come from react.dev and hold for every component. Each names the React version it needs.
+
+- **Render is pure (any version).** Never mutate props, state, context, or a value created before render. Mutating an object
+  the same render just created is fine.
+- **No component defined inside another (any version).** A nested definition gets a new identity each render, so React
+  remounts it and its state resets. Define it at module level and pass data as props.
+- **No `ref.current` during render (any version).** Read and write refs in effects and handlers, except for a lazy init. A
+  value that shapes the output belongs in state.
+- **`ref` is a prop (React 19+).** Accept `ref` like any other prop in your own components; don't wrap them in `forwardRef`.
+- **`useId` for accessibility ids (React 18+).** Use it for `htmlFor`, `aria-describedby`, and similar. Never use it for list
+  keys, and never hardcode its output in tests or selectors.
+- **Error boundaries around UI units (any version).** Wrap a page section or widget, not every component. A boundary does not
+  catch errors from event handlers or async code; TanStack Query and Router surface those.
+- **With the React Compiler on, no manual memoization by default.** `useMemo`, `useCallback`, and `React.memo` are only for a
+  measured case.
+
+See [Keeping Components Pure](https://react.dev/learn/keeping-components-pure),
+[Preserving and Resetting State](https://react.dev/learn/preserving-and-resetting-state),
+[Referencing Values with Refs](https://react.dev/learn/referencing-values-with-refs), and
+[`useId`](https://react.dev/reference/react/useId).

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

@@ -0,0 +1,59 @@
+# React effects
+
+When an effect is the right tool, and how to write the ones that stay.
+
+## Effects: last resort, and named
+
+Use `useEffect` only to synchronize with something outside React. Do not use it for derived values, event responses, or
+server sync.
+
+A genuine effect belongs in a named custom hook. If it stays inline, name the callback:
+
+```tsx
+useEffect(
+  function syncDocumentTitle() {
+    document.title = title;
+  },
+  [title]
+);
+```
+
+Destructure a primitive before putting it in an effect dependency array. Keep the returned query or route object intact
+elsewhere so its namespace remains visible.
+
+## Dependencies
+
+- **No objects or functions as dependencies (any version).** They are new each render, so the effect re-runs every time.
+  Create them inside the effect, move them outside the component, or depend on the primitive they read.
+- **Hidden `<Activity>` cleans up effects (React 19.2+).** A hidden subtree unmounts its effects and re-runs them when shown.
+  Don't rely on an effect running while its UI is hidden.
+
+See [Removing Effect Dependencies](https://react.dev/learn/removing-effect-dependencies).
+
+## Effect Events for values the effect should not react to
+
+When an effect reads a value it should not react to, such as a callback prop or a setting used only once something happens,
+move that logic into `useEffectEvent` (React 19.2+) instead of adding the value to the dependencies, mirroring it in a ref,
+or suppressing the lint rule. Call the Effect Event only from inside the effect, and never use it to drop a value that should
+re-run the effect. See [`useEffectEvent`](https://react.dev/reference/react/useEffectEvent).
+
+```tsx
+const onConnected = useEffectEvent(function notifyConnected() {
+  if (!muted) toast("Connected");
+});
+
+useEffect(
+  function connectToRoom() {
+    const connection = createConnection(roomId);
+    connection.on("connected", onConnected);
+    connection.connect();
+
+    return function disconnectFromRoom() {
+      connection.disconnect();
+    };
+  },
+  [roomId]
+);
+```
+
+Read the React documentation when an effect decision is unclear.

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

@@ -0,0 +1,41 @@
+# React state
+
+Where each piece of state lives.
+
+## Put state where its truth lives
+
+Choose the first suitable level:
+
+1. **URL state**: filters, sort, pagination, and active tab. Use TanStack Router search params and validate them.
+2. **Server state**: API data. Use TanStack Query; do not copy it into `useState`.
+3. **Subtree state**: state shared by a subtree and reset when it leaves. Use React context.
+4. **Client state**: app-wide persistent state. Use TanStack Store only when the earlier levels do not fit.
+5. **Local state**: one component's open state, draft, or input value. Use `useState`.
+
+Shape state so it is not redundant or duplicated. Validate a form draft when it becomes a submitted domain value.
+
+## State shape
+
+- **One status, not exclusive booleans (any version).** `status: "idle" | "saving" | "error"` instead of `isSaving` and
+  `isError` that can both be true. Merge state variables that always change together.
+- **Reducers are pure (any version).** No requests, toasts, or timers inside a reducer. Dispatch one action per user
+  interaction, from the event handler.
+- **Slow renders (React 18+).** Keep text input state out of a transition. When a slow list follows a prop or hook value,
+  render it from `useDeferredValue(value)`.
+
+See [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) and
+[Extracting State Logic into a Reducer](https://react.dev/learn/extracting-state-logic-into-a-reducer).
+
+## Fallbacks without TanStack
+
+TanStack Form and Query are the default. A project without them uses React's own tools:
+
+- **Forms (React 19+):** `<form action={fn}>` needs no `preventDefault` and resets uncontrolled fields on success. Read
+  `useFormStatus` only in a child of the form. `useActionState` holds the result; dispatch it manually only inside an Action
+  or `startTransition`.
+- **Optimistic updates (React 19+):** `useOptimistic`, with the setter called only inside an Action. Once the save succeeds,
+  the parent's value is the truth again.
+
+See [`<form>`](https://react.dev/reference/react-dom/components/form),
+[`useActionState`](https://react.dev/reference/react/useActionState), and
+[`useOptimistic`](https://react.dev/reference/react/useOptimistic).

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

@@ -1,65 +1,12 @@
 # React
 
 Keep data flow one-way and components focused. Pages decide how data is loaded; presentational components decide how it
-looks.
+looks. Read the subtopic that matches the task.
 
-## Composition: pages (smart containers), partials, dumb components
+| Subtopic                            | Read when                                                       |
+| ----------------------------------- | --------------------------------------------------------------- |
+| [composition](react/composition.md) | Deciding a component's role, or composing parts.                |
+| [state](react/state.md)             | Deciding where state lives.                                     |
+| [effects](react/effects.md)         | Writing or reviewing `useEffect`, or reading values in effects. |
 
-- **Pages** live in `routes/`. They load data, read URL state, coordinate actions, and compose the view. Route files hold the
-  search schema, loaders, and pending, error, and not-found components. They do not own component CSS. Route-local views and
-  forms live in the route's `-` folder, as [project-structure.md](project-structure.md) describes, and that folder's
-  `.module.css` files are component styles.
-- **Partials** are compositions that more than one route uses, extracted because they read as a unit. They have light logic
-  and no styling of their own.
-- **Layout components** arrange content with `Stack`, `Row`, grids, and token gaps, and wrap long-form text in `Prose`.
-- **Dumb components** receive data and callbacks, render UI, and own their styles. They do not fetch, route, or contain
-  business rules.
-
-```tsx
-function UserCard({ name, onEdit }: { name: string; onEdit: () => void }) {
-  return (
-    <Card.Root>
-      <Typo.P>{name}</Typo.P>
-      <Button onClick={onEdit}>Edit</Button>
-    </Card.Root>
-  );
-}
-```
-
-## Compose, don't configure
-
-Compose small parts instead of making one component configurable through many boolean props. Lift shared state to the nearest
-common parent.
-
-## Put state where its truth lives
-
-Choose the first suitable level:
-
-1. **URL state**: filters, sort, pagination, and active tab. Use TanStack Router search params and validate them.
-2. **Server state**: API data. Use TanStack Query; do not copy it into `useState`.
-3. **Subtree state**: state shared by a subtree and reset when it leaves. Use React context.
-4. **Client state**: app-wide persistent state. Use TanStack Store only when the earlier levels do not fit.
-5. **Local state**: one component's open state, draft, or input value. Use `useState`.
-
-Shape state so it is not redundant or duplicated. Validate a form draft when it becomes a submitted domain value.
-
-## Effects: last resort, and named
-
-Use `useEffect` only to synchronize with something outside React. Do not use it for derived values, event responses, or
-server sync.
-
-A genuine effect belongs in a named custom hook. If it stays inline, name the callback:
-
-```tsx
-useEffect(
-  function syncDocumentTitle() {
-    document.title = title;
-  },
-  [title]
-);
-```
-
-Destructure a primitive before putting it in an effect dependency array. Keep the returned query or route object intact
-elsewhere so its namespace remains visible.
-
-Read the React documentation when a decomposition or effect decision is unclear.
+Read the React documentation when a decomposition decision is unclear.

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

@@ -19,7 +19,8 @@ Use native CSS and Web UI's public seams. The library's CSS Modules and token na
   transition: opacity var(--imf-ui-duration-quick-2) var(--imf-ui-ease-2);
 
   &:focus-visible {
-    outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-primary);
+    outline: var(--imf-ui-focus-ring-width) solid var(--imf-ui-focus-ring-color);
+    outline-offset: var(--imf-ui-focus-ring-offset);
   }
 
   &[data-disabled] {
@@ -28,6 +29,13 @@ Use native CSS and Web UI's public seams. The library's CSS Modules and token na
 }
 ```
 
+## Focus ring
+
+Web UI parts draw their own focus ring. Your own focusable elements draw the same one from the `--imf-ui-focus-ring-*`
+tokens: `width` and `color` for the outline, and one of two offsets: `offset` outside a standalone control and `offset-inset`
+for items inside a scrolling or tight container, which would clip an outside ring. A surface filled with a saturated color
+sets `--imf-ui-focus-ring-color` to `--imf-ui-color-fg-oncolor` for everything inside it.
+
 ## Build custom UI from tokens
 
 Use names from the shipped token index for colors, type, size, radius, and shadow. A literal beside a tokenized concept is a
@@ -54,6 +62,19 @@ hook, not a state flag.
 }
 ```
 
+Your own components follow the same seam. A container that changes a child sets a custom property; the child reads it with
+its own default as the fallback, so it works with or without the container:
+
+```css
+.panel {
+  --panel-row-gap: var(--imf-ui-size-2);
+}
+
+.row {
+  padding-block: var(--panel-row-gap, var(--imf-ui-size-3));
+}
+```
+
 ## Spacing
 
 Web UI components have no outer margin. The parent sets the distance between its children: `Stack` and `Row` gaps in UI,

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

@@ -25,7 +25,8 @@ Use the tool's current documentation rather than memory.
 
 Use the library that already owns the problem. Adopt Form for form rules, Query for caching and refetching, Router for URL
 state, Table for sorting and pagination, and Hotkeys for keyboard shortcuts instead of rebuilding those layers. Web UI only
-shows a key; the app binds it. Keep an existing project choice when it works.
+shows a key; the app binds it. Keep an existing project choice when it works. A layer rebuilt by hand, such as form state in
+`useState`, is not a choice to keep.
 
 ## Devtools
 
@@ -44,7 +45,7 @@ the Agent Skills the TanStack package provides.
 Vite+ runs development, build, tests, format, lint, and staged checks through one `vp` binary configured in `vite.config.ts`.
 Pin `vite-plus` exactly, alias `vite` to `npm:@voidzero-dev/vite-plus-core@<vite-plus version>`, pin `vitest` to the version
 `vp toolchain vitest` reports, and repeat both pins under `overrides`. Import `defineConfig` from `vite-plus` and Vitest APIs
-from `vite-plus/test`. It needs Node `^22.22.1 || ^24.11 || >=26` and Git 2.32 or later.
+from `vite-plus/test`. It needs Git 2.32 or later; the `npm-project` topic sets the Node range.
 
 `vp <command>` is a built-in; `vp run <script>` runs a package script.
 

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

@@ -54,3 +54,10 @@ Use `.catch()` for malformed values that can safely fall back. Use `.default()`
 - Use `parse` when invalid data is a contract failure that should reach the normal error boundary.
 - Use `safeParse` when failure is expected and the caller can show a validation message.
 - Keep trimming, coercion, transforms, and defaults in the boundary schema.
+
+## Forms
+
+Build forms with TanStack Form and validate user input in the form's validators with the Zod schema, so a field error and the
+submitted value's type come from one schema. Field values held in `useState` and checked by hand with `safeParse` are a gap,
+even when the project's other forms do the same. A project without TanStack Form follows the fallback in
+[react/state.md](react/state.md#fallbacks-without-tanstack).

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

@@ -1,7 +1,8 @@
 # Form UX
 
-Read this before building a form with more than two fields. The library supplies controls; the form library owns state and
-validation. These rules cover structure and feedback.
+Read this before building a form with more than two fields. Build it with TanStack Form, the form library the
+`imf-web-ui-conventions` tooling topic names: it owns state and validation, and Web UI supplies the controls. These rules
+cover structure and feedback.
 
 ## Structure
 

package/src/llms/tokens.gen.json

@@ -462,6 +462,24 @@
         "value": "cubic-bezier(0, 0, 0.05, 1)"
       }
     ],
+    "focus": [
+      {
+        "name": "--imf-ui-focus-ring-color",
+        "value": "var(--imf-ui-color-fg-primary)"
+      },
+      {
+        "name": "--imf-ui-focus-ring-offset",
+        "value": "2px"
+      },
+      {
+        "name": "--imf-ui-focus-ring-offset-inset",
+        "value": "calc(var(--imf-ui-focus-ring-width) * -1)"
+      },
+      {
+        "name": "--imf-ui-focus-ring-width",
+        "value": "var(--imf-ui-border-size-2)"
+      }
+    ],
     "font": [
       {
         "name": "--imf-ui-font-family-body",
@@ -955,5 +973,5 @@
       }
     ]
   },
-  "count": 233
+  "count": 237
 }