@imfusion/web-ui 0.10.1-dev.6.gf715361a → 0.10.1-dev.60.g7891a716

package/src/llms/install-templates/hooks/baseline-staleness.sh

@@ -4,6 +4,8 @@
 # and warns on drift. Always exits 0 — staleness never blocks a commit.
 PKG=node_modules/@imfusion/web-ui/package.json
 [ -f "$PKG" ] || exit 0
+# A symlinked checkout reports its own dev version.
+[ -L node_modules/@imfusion/web-ui ] && exit 0
 CURRENT=$(node -p "require('./$PKG').version" 2>/dev/null) || exit 0
 
 # .claude/skills may be a symlink to .agents/skills; skip markers already read.

package/src/llms/install-templates/hooks/stop.sh

@@ -10,9 +10,14 @@ git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
 [ -n "$(git status --porcelain -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.css' 2>/dev/null)" ] || exit 0
 # Gate only turns that actually edited files — a tree left dirty by an earlier
 # session must not block a question-answering turn. Edit evidence: Write/Edit
-# tool calls (Claude transcript) or apply_patch calls (Codex rollout).
+# tool calls (Claude transcript) or apply_patch calls (Codex rollout), searched
+# only after the turn's opening entry: the last real user prompt (not a tool
+# result or injected meta message) or the last Codex task_started event. Claude
+# matches only tool_use calls: its transcript also stores the tool definitions,
+# whose "name":"Edit" entries are not edits.
 TRANSCRIPT=$(printf '%s' "$PAYLOAD" | sed -n 's/.*"transcript_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)
 [ -f "$TRANSCRIPT" ] || exit 0
-grep -q '"name":"Write"\|"name":"Edit"\|"name":"MultiEdit"\|"name":"NotebookEdit"\|apply_patch' "$TRANSCRIPT" || exit 0
+TURN_START=$(grep -En '"type":"user"|"type":"task_started"' "$TRANSCRIPT" | grep -Ev '"type":"tool_result"|"isMeta":true' | tail -n 1 | cut -d: -f1)
+tail -n +$(( ${TURN_START:-0} + 1 )) "$TRANSCRIPT" | grep -Eq '"type":"tool_use","id":"[^"]*","name":"(Write|Edit|MultiEdit|NotebookEdit)"|"name":"apply_patch"' || exit 0
 printf '{"decision":"block","reason":"web-ui stop gate: this turn changed source files. Run the project verification (verify:typecheck, verify:lint, and verify:format at minimum), fix what it reports, then finish. If it already ran after the last change, say so and finish."}\n'
 exit 0

package/src/llms/llms.gen.txt

@@ -11,7 +11,7 @@ props, which always live in the docgen file above.
 
 ## AccountCard
 - category: Display, status: experimental
-Card linking to the signed-in person's account: avatar, a large name or email, a quiet line under it, and organization and role at its foot, with a trailing action such as Log out. Also called an ID card or user row; for a bare person badge, use Avatar.
+The signed-in person's account row: the avatar in a lead column, the name or email, a quiet line under it, and organization and role below, with a trailing action such as Log out. Also called an ID card or user row; for a bare person badge, use Avatar.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .account-card (jq: jq '.account-card' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## AppShell
@@ -73,11 +73,22 @@ Show-and-hide region for secondary content such as FAQs, settings, or details. A
 - 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
 
+## ColorSchemeToggle
+- category: Inputs, status: experimental
+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)
+
 ## 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.
 - 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)
 
+## Dialog
+- category: Layout, status: experimental
+Modal window over a dimmed page for focused tasks, forms, confirmations, or viewers. Also called a modal; use Drawer for a panel from the screen edge and Popover for content anchored to a trigger.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .dialog (jq: jq '.dialog' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/dialog.md
+
 ## Drawer
 - category: Layout, status: stable
 Off-canvas panel that slides in from a screen edge for navigation, settings, filters, or focused tasks. Also called a sidebar, side panel, or sheet.
@@ -173,6 +184,12 @@ Link as a whole row: optional leading icon, label, optional description line, an
 Horizontal layout primitive for spacing, aligning, and wrapping children. Also called a horizontal stack or 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)
 
+## ScrollArea
+- category: Layout, status: experimental
+Scrollable region with the library's overlay scrollbar and edge fades, for lists, panels, and dialog bodies. Also called a scroll container; use it instead of a bare overflow: auto.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .scroll-area (jq: jq '.scroll-area' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/scroll-area.md
+
 ## Select
 - category: Inputs, status: stable
 Dropdown for choosing a value from a known list. Also called a picker; use it for a labeled, keyboard-accessible option list.

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

@@ -23,15 +23,20 @@ it low, and do not let it crowd the sections a consumer has to act on.
 
 Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
 
-1. Resolve the argument. Bare means `full`; an unknown topic is an error, not a reason to widen the scope.
+1. Resolve the argument. Bare means `full`; an unknown topic is an error, not a reason to widen the scope. Then check that
+   `node_modules/@imfusion/web-ui/package.json` exists. Without it, token, installed-version, and installed-type checks can
+   only come back Unverified, so tell the human before dispatch and ask whether to install dependencies first or continue
+   with those checks unverified.
 2. Enter plan mode unless this audit is being called as verification by another skill or the host has no plan mode.
 3. Read the report template and existing reviewer notes, then dispatch one investigator per in-scope topic. Tell each
-   investigator to use only `Read`, `Glob`, and `Grep`, with no shell commands or writes. An investigator checks every
-   section in that topic and writes nothing. Once dispatch starts, the host performs no repository inspection: the returned
-   reports are the evidence, and the host merges them without reading or searching the files again. Gathering the evidence
-   twice spends context on the second pass and reports what the host still remembers. Inspect a topic inline only after its
-   dispatch has been tried and refused, and say which attempt failed. A `full` audit also dispatches one marker investigator;
-   a named-topic audit gives that search to the topic's investigator. See [Deferred-work markers](#deferred-work-markers).
+   investigator to inspect statically: `Read` plus the host's file search (`Glob` and `Grep`, or a read-only search tool when
+   the host has no `Glob` or `Grep`), with no shell commands or writes. An investigator checks every section in that topic
+   across the whole frontend tree and writes nothing; one without any search tool says so and stops instead of auditing only
+   the paths it already knows. Once dispatch starts, the host performs no repository inspection: the returned reports are the
+   evidence, and the host merges them without reading or searching the files again. Gathering the evidence twice spends
+   context on the second pass and reports what the host still remembers. Inspect a topic inline only after its dispatch has
+   been tried and refused, and say which attempt failed. A `full` audit also dispatches one marker investigator; a
+   named-topic audit gives that search to the topic's investigator. See [Deferred-work markers](#deferred-work-markers).
 4. Merge the evidence into the shared report format in
    [`templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md). Before presenting or writing it, check that every
    Broken, Missing, Deviation, and Unverified entry has a severity, evidence, impact, and next action; do not compact
@@ -55,7 +60,15 @@ Classify every result as one of these:
 
 Use the report contract's severity, `path:line` evidence, concrete impact, and smallest next action. Unverified entries use
 that same structure: unavailable runtime evidence, the impact of the unknown, and the check that resolves it. Do not promote
-an optional tool or a working alternative to a missing finding.
+an optional tool or a working alternative to a missing finding. A `vite.config.ts` without `localWebUILink()` registered from
+`@imfusion/web-ui/vite` is Missing. A `tsconfig.json` without the `paths` block from the `tooling` topic is Missing too. Each
+next action is the add from that topic. A Vite config that reads tsconfig `paths` (`resolve.tsconfigPaths` or
+`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-local file that the inline rule in the `project-structure`
+topic says belongs in its route file is a Deviation, and so is a route file over 250 lines that inlines parts the rule would
+keep in its `-` folder. Report the line counts, with the move as the fix.
 
 ## Topics
 
@@ -90,6 +103,6 @@ text; do not run installers or hooks.
 
 ## Safety
 
-Use only `Read`, `Glob`, `Grep`, and equivalent static inspection. Do not run Git, shells, Node, npm, npx, package scripts,
-linters, tests, builds, hooks, or imported config. Report runtime state as unverified. Investigators inherit this
-restriction.
+Use only `Read`, the host's read-only file search, and equivalent static inspection. Do not run Git, shells, Node, npm, npx,
+package scripts, linters, tests, builds, hooks, or imported config. Report runtime state as unverified. Investigators inherit
+this restriction.

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

@@ -14,7 +14,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Stay behind the library
 - [ ] Wrap primitives when the app has a reason to
 - [ ] Lock a field: read-only or disabled
-- [ ] Derive types, don't import them
+- [ ] Derive types, don't copy them
 - [ ] Integrations own their peers
 - [ ] Styling crosses the boundary through seams
 
@@ -89,6 +89,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Topic registry and key factory
 - [ ] Options factories and naming
 - [ ] Router context access
+- [ ] Loading states
 - [ ] Automatic invalidation
 - [ ] Testing the data layer
 
@@ -108,7 +109,8 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Oxfmt
 - [ ] Oxlint and TypeScript
 - [ ] Pre-commit checks
-- [ ] Vite plugins
+- [ ] Vite plugins, including `localWebUILink()`
+- [ ] Aligned runtime packages
 
 ## npm project — `npm-project`
 

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

@@ -70,8 +70,10 @@ Cross-topic invalidation can then use `keys.topic` instead of rebuilding a prefi
 
 ## Options factories and naming
 
-Queries use `get*` names such as `getAll`, `getById`, and `getDetails`. Mutations use bare verbs such as `update` or
-`delete`. Do not add a topic prefix or `Options` suffix; `context.api.user.getDetails()` already supplies the context.
+Queries use `get*` names such as `getAll`, `getById`, and `getDetails`. Mutations use verbs such as `update` or `delete`. A
+name never repeats its topic or adds an `Options` suffix; `context.api.user.getDetails()` already supplies the context. When
+a topic has more than one mutation target, add the sub-resource to the verb: `api.projects.removeMember(projectId)` and
+`api.projects.setMemberPermissions(projectId)`, where a bare `remove` would read as deleting the project.
 
 A query factory owns its key and parsing:
 
@@ -102,6 +104,19 @@ not inline those options at the call site.
 Put the API object and `QueryClient` in router context. Loaders use `context.api.<topic>.<fn>()`; route components read the
 same context with `Route.useRouteContext()`. Direct imports are for plain utilities and tests outside the route tree.
 
+## Loading states
+
+Pick the Skeleton part by how the data loads:
+
+- Data read with `useSuspenseQuery` inside a Suspense boundary uses `Skeleton.Suspense`, with the bones as its `fallback`.
+  Content fades in when the fallback showed; cached data mounts without a fade.
+- Secondary data read with `useQuery` that may arrive later uses `Skeleton.Root` with `loading={isPending}` around the real
+  content, which cross-fades when the data lands.
+- A route whose loader blocks navigation until the data is cached shows its `pendingComponent`. The router unmounts it, so
+  nothing reveals.
+
+A layout that reads suspending data needs its own boundary. Otherwise a suspension blanks the whole layout.
+
 ## Automatic invalidation
 
 Mutation keys start with the topic they change. The shared `MutationCache` invalidates that topic after success by default.

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

@@ -7,12 +7,15 @@ Use the repository's tracked configuration and keep verification scopes clear.
 Run once in a clone:
 
 ```sh
-git config core.hooksPath .githooks
+git config core.hooksPath .vite-hooks/_
+vp config --no-agent
 git config pull.rebase true
 git config merge.ff only
 ```
 
-The hooks are tracked in `.githooks/`. Check both the Git setting and the directory; a missing hook path fails silently.
+Vite+ manages the hooks. The hook scripts are tracked in `.vite-hooks/`; `vp config` installs the dispatcher into the
+git-ignored `.vite-hooks/_/`. `vp config` leaves a `core.hooksPath` that points elsewhere alone, so set it first. Every clone
+and worktree needs its own dispatcher. Check both with `vp hooks status`; a missing dispatcher skips the hooks silently.
 
 ## Verify scopes
 

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

@@ -29,6 +29,9 @@ instead, so component colors cannot resolve against the opposite scheme:
 <WebUIProvider colorScheme="dark">
 ```
 
+To let the user pick Light, System, or Dark, place a `ColorSchemeToggle`. It stores the choice and works only while the
+provider's `colorScheme` is unset.
+
 ## Symptoms of broken setup
 
 - Unstyled components usually mean the `styles.css` import is missing.

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

@@ -35,8 +35,11 @@ A route file holds its search schema and `validateSearch`, its loaders, and its
 Route-local code that outgrows small in-file components (views, forms, hooks, tests) goes in a sibling folder named `-` plus
 the route file's name: `route.tsx` gets `-route/`, `products.tsx` gets `-products/`. TanStack Router ignores files and
 folders with a leading `-` when it builds the route tree, so the folder never becomes a route. The folder holds the route's
-views with their props types, hooks, `.module.css` files, and tests. A component small enough to sit in the route file stays
-there.
+views with their props types, hooks, `.module.css` files, and tests.
+
+A part used by one route file is inlined into it when it is a component under 50 lines, calls no `use*` hook, has no
+stylesheet or test of its own, and leaves that route file under 250 lines. Every other single-route part goes in the `-`
+folder. The thresholds keep tiny wrappers out of their own files without letting a route file grow into a page of views.
 
 `partials/` holds only parts that more than one route uses.
 

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

@@ -9,7 +9,9 @@ Use native CSS and Web UI's public seams. The library's CSS Modules and token na
 - Nest states, pseudo-elements, and child selectors under the root.
 - Write declarations before nested rules; browsers before Chrome 130, Firefox 132, and Safari 18 move later ones above them.
 - Do not nest under a selector list whose selectors differ in specificity. The nested rule takes the highest one.
-- Lift repeated values into custom properties, especially when a state or variant changes several descendants.
+- Lift a value into a custom property on the component's root when it repeats within that stylesheet, or when a state or
+  variant changes several descendants. A value that only recurs across files stays a literal in each; when those files show
+  one design element, a shared component owns it. Never define component values on `:root`.
 - Keep structurally different rules explicit; not every repeated value needs an abstraction.
 
 ```css

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

@@ -49,7 +49,7 @@ from `vite-plus/test`. It needs Node `^22.22.1 || ^24.11 || >=26` and Git 2.32 o
 `vp <command>` is a built-in; `vp run <script>` runs a package script.
 
 Move an existing Vite, Vitest, ESLint, or Prettier project with `vp migrate --no-hooks` (`vp help migrate` lists its
-options), then check the result against this topic. The hook lives in `.githooks/`, as `git.md` describes.
+options), then check the result against this topic. The hook lives in `.vite-hooks/`, as `git.md` describes.
 
 ## Oxfmt
 
@@ -101,12 +101,19 @@ export default defineConfig({
 });
 ```
 
-Use strict TypeScript with bundler module resolution, `verbatimModuleSyntax`, unused-value checks, and `#/` paths. Keep
-`import type` for type-only imports.
+Use strict TypeScript with bundler module resolution, `verbatimModuleSyntax`, unused-value checks, and `import type` for
+type-only imports. The `#/` alias is a subpath import in `package.json`, which Vite and TypeScript both read without a
+plugin:
+
+```json
+"imports": {
+  "#/*": "./src/*"
+}
+```
 
 ## Pre-commit checks
 
-`.githooks/pre-commit` runs `vp staged --hide-unstaged --fail-on-changes --revert --diff-filter=ACMRD` with `set -e`. Those
+`.vite-hooks/pre-commit` runs `vp staged --hide-unstaged --fail-on-changes --revert --diff-filter=ACMRD` with `set -e`. Those
 flags make the checks see only the staged state, include deletion-only commits, fail the commit when a check would change a
 file, and restore the tree afterwards, so the hook never rewrites or stages files. The `staged` block in `vite.config.ts` is
 a function returning path-free commands such as `npm run --silent verify:lint`, so each project-wide check runs once. Use
@@ -119,10 +126,10 @@ Register Web UI's Vite plugins in the application configuration:
 ```ts
 import { defineConfig } from "vite-plus";
 import react from "@vitejs/plugin-react";
-import { imfusionBrandAssets, readableCssModuleNames } from "@imfusion/web-ui/vite";
+import { imfusionBrandAssets, localWebUILink, readableCssModuleNames } from "@imfusion/web-ui/vite";
 
 export default defineConfig({
-  plugins: [react(), imfusionBrandAssets(), readableCssModuleNames({ prefix: "app" })]
+  plugins: [react(), imfusionBrandAssets(), readableCssModuleNames({ prefix: "app" }), localWebUILink()]
 });
 ```
 
@@ -130,5 +137,37 @@ export default defineConfig({
 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.
 
-`localWebUILink` dedupes the library's peer dependencies when `@imfusion/web-ui` is linked from a local checkout
-(`file:../web-ui`), so the app loads one React. It does nothing for an installed package and does not cover server rendering.
+## Aligned runtime packages
+
+Web UI and the app run the same versions of these packages. The `peerDependencies` of
+`node_modules/@imfusion/web-ui/package.json` give the accepted ranges, and its `devDependencies` give the version Web UI
+builds and tests with. A matching major and minor is the rule; a patch difference is fine.
+
+- `react`, `react-dom`
+- `@types/react`, `@types/react-dom`
+- `@base-ui/react`, which brings `@floating-ui/*` with it
+- `vite-plus`
+- `vite`, the `npm:@voidzero-dev/vite-plus-core` alias that `vite-plus` provides
+
+## Version drift
+
+Aligned versions are the primary fix. The plugin and the `paths` block below catch the drift that slips through.
+
+`localWebUILink` stays registered for good. It does nothing for an installed package. When `@imfusion/web-ui` is a symlinked
+checkout, it keeps one React in dev, build, and Vitest.
+
+Add this to `compilerOptions` in `tsconfig.json`, merged by hand into an existing `paths`. For a symlinked checkout it keeps
+one set of React and Vite types for `tsc`:
+
+```json
+"paths": {
+  "react": ["./node_modules/@types/react"],
+  "react/*": ["./node_modules/@types/react/*"],
+  "vite": ["./node_modules/vite"]
+}
+```
+
+Only TypeScript reads these `paths`. Never let Vite read them: leave `resolve.tsconfigPaths` off and do not add
+`vite-tsconfig-paths`. Either one applies the `react` mapping at runtime, loads the types package as React, and breaks the
+build and tests once `@imfusion/web-ui` is installed from the registry. A symlinked checkout hides the break, because
+`localWebUILink()` dedupes React first.

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

@@ -6,6 +6,8 @@ Prefer pure functions, immutable values, and side effects at the edges.
 
 - Do not use `any`. Accept `unknown` at an untrusted boundary and narrow it.
 - Infer local values; give exported functions explicit return types.
+  - TanStack options factories (`queryOptions`, `mutationOptions`, and similar) return their helper's inferred type. Spelling
+    it out loses the typed query key (`DataTag`) or repeats the helper's own generics.
 - Model states directly instead of filling a nullable value later.
 - Derive types from their source. Use `z.infer` for schemas and `React.ComponentProps` for Web UI components.
 - Avoid `as`. Keep an assertion only at an untyped third-party boundary where it is the honest boundary.

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

@@ -45,10 +45,19 @@ Include these pieces unless the existing project already has them or the user re
 - one server-backed current-user query at the route boundary;
 - a minimal `AppShell` in `_app/`, unless the user says the product has no persistent authenticated navigation;
 - an API topic folder for data shown by the first screen;
-- the root provider and library wiring.
+- the root provider and library wiring;
+- the Vite plugins below.
 
 The plan describes the exact starter files. It does not copy a generic starter project.
 
+## Vite plugins
+
+Propose a `vite.config.ts` that registers `imfusionBrandAssets()`, `readableCssModuleNames()`, and `localWebUILink()` from
+`@imfusion/web-ui/vite`, next to the plugins the project already has. Register `localWebUILink()` in every project: without a
+symlinked checkout it does nothing. Also propose the `tsconfig.json` `paths` block. Both keep one React and one set of types
+when the package is a symlinked checkout. Vite must not read those `paths`: never propose `resolve.tsconfigPaths` or
+`vite-tsconfig-paths`, and give the `#/` alias through `imports` in `package.json`. The `tooling` topic has the exact config.
+
 ## Installer steps
 
 For `agent-tooling`, list the `npx web-ui install` commands as steps for the human. Read existing registrations first and do

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

@@ -96,6 +96,13 @@ changed. A diff shows what moved, not the step order you continue under, so it d
 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.
 
+## Align the runtime packages
+
+After the install, compare the app's installed versions of the packages listed under Aligned runtime packages in the
+`tooling` topic with Web UI's own `package.json` in `node_modules/@imfusion/web-ui`. Report every major or minor mismatch and
+propose `npm install <package>@<Web UI's version>` for each. Make the change as its own commit, in this same update, after
+the base commit and with its own approval.
+
 ## Verify the base update
 
 After every mutating command, compare the status with the preflight snapshot. Stop on an unexpected path or overlapping

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

@@ -7,8 +7,8 @@ description:
 
 # Shape the screen
 
-Use this skill for screen-level decisions. Verify component APIs with `imf-web-ui-components`; put code and styling rules in
-`imf-web-ui-conventions`.
+Use this skill for screen-level decisions. The patterns below name no components: check which component fits a pattern, and
+its API, in `imf-web-ui-components`. Put code and styling rules in `imf-web-ui-conventions`.
 
 Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
 
@@ -34,33 +34,31 @@ unanswered, make the conservative choice and state the assumption.
 ## Choose a surface
 
 - Use a full page by default.
-- Use `Drawer` for a focused task that keeps the current page in context.
-- Use `Popover` for small contextual content or a light form.
-- Use `Tooltip` for a hint only. It must not contain required or interactive information.
-- Use `Collapsible` for secondary content inside the page.
-- Use `Tabs` for parallel views of one subject. If users must complete every section, use a flow instead.
-
-The library has no modal `Dialog` or `Toast`. Raise those gaps rather than hand-rolling a replacement without a product
-reason.
+- Use a side panel for a focused task that keeps the current page in context.
+- Use a floating panel anchored to its trigger for small contextual content or a light form.
+- Use a hover or focus hint for a short label only. It must not contain required or interactive information.
+- Use a collapsible region for secondary content inside the page.
+- Use tabs for parallel views of one subject. If users must complete every section, use a flow instead.
+- Use a modal dialog for a decision that must be settled before the page continues, such as a destructive action. If no
+  component fits a pattern, raise the gap rather than hand-rolling a replacement without a product reason.
 
 ## Choose between similar controls
 
-- `Button` performs an action, `ChipLink` goes somewhere, and `Chip` labels something.
-- Use `ChipLink` for a link inside text or a row of chips, and `RichLink` for a link that fills its own row, such as a list
-  of resources.
-- Use plain `Table` parts for static small data. Pair them with a headless table library for sorting, pagination, or column
-  logic. TanStack Table is the recommended choice.
-- Use `Callout` for persistent in-place status. Put transient confirmation near the action until a toast pattern exists.
-- Use `Switch` for an immediate setting and `Checkbox` for a submitted choice.
-- Use `Select` for a known list, and consider a different control when the list is very short or very large.
-- Use `Slider` when relative position matters more than typing an exact value.
+- An action is a button, navigation is a link, and a label is a chip.
+- Use an inline link inside text or in a row of chips, and a full-row link for a list of resources.
+- Use a plain table for static small data. Pair it with a headless table library for sorting, pagination, or column logic.
+  TanStack Table is the recommended choice.
+- Use an in-place status message for persistent status. Keep transient confirmation near the action it confirms.
+- Use a switch for an immediate setting and a checkbox for a submitted choice.
+- Use a select for a known list, and consider a different control when the list is very short or very large.
+- Use a slider when relative position matters more than typing an exact value.
 
 ## Build the hierarchy
 
-- Frame an application with `AppShell`.
-- Compose `Stack` and `Row` for spacing and arrangement, and wrap long-form text in `Prose`. Use `Separator` for a real
+- Frame an application with the library's app shell.
+- Arrange content with stack and row layouts, wrap long-form text in a prose container, and use a separator for a real
   division.
-- Use `Typo` for text hierarchy instead of styling raw headings beside it.
+- Use the library's typography components for text hierarchy instead of styling raw headings beside them.
 - Give a view one primary action. Make other actions quieter.
 - Choose density from the user's frequency and data volume: frequent work and large data need compact layouts; occasional
   work benefits from more explanation and space.
@@ -70,14 +68,37 @@ reason.
 Plan these states with the loaded view:
 
 - **Empty**: say what belongs here and what the user can do next.
-- **Loading**: use `Spinner` or a stable skeleton; keep the frame from jumping.
-- **Error**: explain what failed and the next action in a `Callout` near the problem.
+- **Loading**: use a spinner or a stable skeleton; keep the frame from jumping. The `imf-web-ui-conventions` data topic says
+  which skeleton part fits each way the data loads.
+- **Error**: explain what failed and the next action in an in-place status message near the problem.
 - **Loaded**: the normal view.
 
 ## Keep custom UI native
 
-When the library does not cover a piece, compose its primitives and use `--imf-ui-*` tokens. The implementation details are
-in `imf-web-ui-conventions`.
+When no component covers a piece, compose its primitives and use `--imf-ui-*` tokens. The implementation details are in
+`imf-web-ui-conventions`.
 
 For a screen review, read the relevant reference under `references/`: `usability-heuristics.md`, `visual-design.md`, or
 `forms.md`.
+
+## Public backdrop handover
+
+Public pages share a backdrop with the Keycloak login page: a light column with an animated line mesh, and a brand-colored
+panel. Both sides draw the same geometry, so the cross-origin navigation between them looks seamless. Read the geometry from
+these tokens and never from literals:
+
+- `--imf-ui-size-backdrop-edge`: where the brand panel starts on wide landscape screens.
+- `--imf-ui-size-backdrop-band-height`: the height of the light band on top of narrow or portrait screens, with the panel
+  below it.
+
+The switch between the two layouts is a media query, which a token cannot carry. Use the same breakpoint as the reference
+implementations.
+
+The backdrop also paints before React mounts, so the first frame already matches. Put the same two columns on `body` as a
+hard-stop `linear-gradient`, with `min-block-size: 100dvh`. In a single-page app, a marker on `html`
+(`data-backdrop-pending`), set by an inline script in `index.html` for the routes that show the backdrop, gates that
+gradient. The backdrop component removes the marker when it mounts. Generate that script's route list at build time from the
+router's own source, never as a hand-written copy: with TanStack file routes, a small Vite plugin (`transformIndexHtml`)
+reads the folder of backdrop routes and fills a placeholder in `index.html`, so a new route gets the pre-paint without anyone
+touching the script. The ImFusion Portal's public backdrop component and the Keycloak login theme's copy of it are the
+reference implementations.

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

@@ -6,9 +6,9 @@ validation. These rules cover structure and feedback.
 ## Structure
 
 - Remove fields that can be derived or asked later.
-- Use one column by default. Put short, inseparable values such as city and postal code in a `Row`.
-- Group related fields in a `Stack` and separate groups with more space.
-- Use a labeled `Fieldset` or heading for each group.
+- Use one column by default. Put short, inseparable values such as city and postal code on one row.
+- Group related fields with tight spacing and separate groups with more space.
+- Use a labeled fieldset or heading for each group.
 - Match a field's size to the value it expects.
 
 ## Labels
@@ -21,10 +21,10 @@ hints near the field before the user starts typing.
 Validate when the user finishes a field, except where live feedback genuinely helps, such as password requirements. Keep the
 error next to the field and use more than color to show it.
 
-An error says what is wrong and how to fix it. Keep the user's input. A server or form-level failure belongs in a `Callout`
-near the actions; field-level failures stay with their fields.
+An error says what is wrong and how to fix it. Keep the user's input. A server or form-level failure belongs in an in-place
+status message near the actions; field-level failures stay with their fields.
 
 ## Submission
 
-Use one primary `Button` whose label names the result, such as `Create project`. While submitting, keep the form visible and
+Use one primary button whose label names the result, such as `Create project`. While submitting, keep the form visible and
 show progress. A failed submission must leave the user's input on screen.

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

@@ -5,12 +5,12 @@ user research.
 
 1. **Show system status.** Give async actions visible progress and confirmation.
 2. **Use the user's language.** Labels and ordering should match the domain, not an API's private names.
-3. **Provide an exit.** Drawers and popovers need clear dismissal; destructive actions need confirmation or undo.
+3. **Provide an exit.** Side panels and floating panels need clear dismissal; destructive actions need confirmation or undo.
 4. **Be consistent.** Reuse the library's established components and semantics.
 5. **Prevent errors.** Constrain known choices and disable actions that cannot work.
 6. **Support recognition.** Keep relevant options and context visible instead of making users remember them.
 7. **Support frequent users.** Add keyboard shortcuts or dense layouts when the task is frequent and data-heavy.
 8. **Remove decoration without a job.** Every element should support the action or the data.
 9. **Make errors recoverable.** Say what failed and what to do next, near the problem.
-10. **Keep help contextual.** Prefer a short hint beside a control to essential information hidden in a tooltip or separate
-    page.
+10. **Keep help contextual.** Prefer a short hint beside a control to essential information hidden in a hover hint or
+    separate page.

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

@@ -7,12 +7,12 @@ Use this when a screen works but still looks wrong. Decide the hierarchy before
 Write the intended order of attention: title, primary action, content, and supporting details. Use contrast and scale to make
 that order visible. Keep variation limited; if everything is loud, nothing leads.
 
-Reserve saturated status colors for meaning. The primary `Button` should be the strongest action treatment on the screen.
+Reserve saturated status colors for meaning. The primary button should be the strongest action treatment on the screen.
 
 ## Grouping
 
-Use proximity first: tight gaps inside a group, larger gaps between groups. `Stack` gap values encode this relationship. Use
-a shared `Card` or bordered region only when spacing alone does not make the relationship clear.
+Use proximity first: tight gaps inside a group, larger gaps between groups. Spacing values encode this relationship. Use a
+shared card or bordered region only when spacing alone does not make the relationship clear.
 
 Similarity helps related elements stay recognisable across a layout. It supports proximity; it does not replace it.
 

package/src/llms/tokens.gen.json

@@ -477,7 +477,7 @@
       },
       {
         "name": "--imf-ui-font-family-mono",
-        "value": "\"CoFo Sans Mono\", ui-monospace, monospace"
+        "value": "\"Paper Mono\", ui-monospace, monospace"
       },
       {
         "name": "--imf-ui-font-family-sans",
@@ -493,7 +493,7 @@
       },
       {
         "name": "--imf-ui-font-letterspacing-brand",
-        "value": "-0.02em"
+        "value": "clamp(-0.035rem, -0.0081rem - 0.0224vw, -0.0131rem)"
       },
       {
         "name": "--imf-ui-font-letterspacing-display",
@@ -501,7 +501,7 @@
       },
       {
         "name": "--imf-ui-font-letterspacing-hero",
-        "value": "-0.04em"
+        "value": "clamp(-0.225rem, -0.0312rem - 0.1615vw, -0.0675rem)"
       },
       {
         "name": "--imf-ui-font-letterspacing-loose",
@@ -689,7 +689,7 @@
       },
       {
         "name": "--imf-ui-font-weight-strong",
-        "value": "600"
+        "value": "500"
       }
     ],
     "inner-*": [
@@ -913,6 +913,14 @@
         "name": "--imf-ui-size-9",
         "value": "4rem"
       },
+      {
+        "name": "--imf-ui-size-backdrop-band-height",
+        "value": "30dvh"
+      },
+      {
+        "name": "--imf-ui-size-backdrop-edge",
+        "value": "38%"
+      },
       {
         "name": "--imf-ui-size-content-1",
         "value": "20ch"
@@ -947,5 +955,5 @@
       }
     ]
   },
-  "count": 231
+  "count": 233
 }