@imfusion/web-ui 0.6.1-dev.27.gfc6e5abb → 0.6.1-dev.3.g8b2855c3

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

@@ -1,91 +1,157 @@
 ---
 name: imf-web-ui-update
 description:
-  "Update @imfusion/web-ui in a consumer repository. Use this whenever a consumer needs a newer package, installed skills, or
-  lifecycle hooks. Refresh the base first, verify it, then audit any consumer migration separately. Preserve user work and
-  get approval before each commit."
+  "Update @imfusion/web-ui in a consumer repository: refresh the package, vendored skills, and lifecycle hooks, verify the
+  base update, then audit and optionally migrate affected or custom consumer components in a separate approved commit."
 argument-hint: "[--dry-run] [optional version or reason]"
 allowed-tools: Bash Read Grep
 ---
 
-# Update Web UI
-
-This workflow has two possible commits: the package/tooling update, then an optional consumer migration. Keep them separate.
-Never overwrite user changes or commit without fresh approval.
+# imf-web-ui-update
+
+Update a repository that consumes `@imfusion/web-ui`. Preserve existing project choices and user work. The workflow has two
+commits: the dependency/tooling update first, then an optional consumer migration. Never commit without a fresh explicit
+approval.
+
+## Rules
+
+- Work from the frontend package root. In a monorepo, inspect package manifests and `git worktree list` first, then choose
+  the frontend package in the active worktree that uses web-ui. Read repository and component instructions before changing
+  files.
+- This workflow uses npm. `package-lock.json` is the expected lockfile. Another lockfile is a conflict: stop and ask.
+- A dry run is read-only. Do not install, run the installer, format, stage, commit, reset, or clean. Report what would run.
+- Record the initial `git status --short`. Existing changes are held back, never staged or overwritten.
+- A dirty file that the workflow needs to modify is a conflict. Stop and report it. This includes package files, installed
+  skill directories, the `AGENTS.md` installer fence, hook files, and hook settings.
+- Do not hand-edit installer-owned skills, the `AGENTS.md` fenced block, or installer-owned hook files.
+- Keep the base update and consumer migration in separate commits. Do not begin the migration audit until the base update
+  commit is complete.
+- Treat the installed package version before the update as the comparison baseline. There is no assumed changelog.
+- A migration candidate is a custom consumer implementation whose behavior overlaps with a current web-ui component, or an
+  existing web-ui usage affected by changed types or documented API. Do not infer a replacement from a name alone; inspect
+  the implementation and the current component documentation/types.
 
 ## Preflight
 
-1. Work from the frontend package root. In a monorepo, find the package that owns the Web UI dependency.
-2. Read its `package.json`, lockfile, and repository instructions. npm with `package-lock.json` is the expected setup; stop
-   if another lockfile is the active one.
-3. Record `git status --short`, the installed Web UI version, the installed skill targets, hooks, registrations, and
-   `AGENTS.md` fence.
-4. Check for another npm process and stop on a conflict. A dirty file this workflow needs is also a conflict. Do not reset,
-   clean, restore, or hide it.
-5. With `--dry-run`, stop after reporting what would happen. Do not install, format, stage, commit, or ask for commit
-   approval.
+1. Select the frontend package in the active worktree and read its instructions, `package.json`, and `package-lock.json`.
+2. Check whether `@imfusion/web-ui` is already declared and record its installed/version-marker version.
+3. Record the worktree status and identify files the update would touch.
+4. Inspect `.agents/skills/`, `.claude/skills/`, the `AGENTS.md` fence, `.claude/settings.json`, and `.agents/hooks/`.
+5. Check for another npm process. Stop on any conflict or ambiguous target.
 
-## Update the base
+## Base update
 
-Run from the consumer package root:
+In a non-dry run, update the dependency:
 
 ```sh
 npm install @imfusion/web-ui
+```
+
+Pass an explicit version only when the user supplied one. Do not use `--force` or `--legacy-peer-deps` to make installation
+pass. Stop on install failure.
+
+Then refresh the existing web-ui skill target and lifecycle hooks:
+
+```sh
 npx web-ui-install
 npx web-ui-install --hooks
 ```
 
-Use `npm install @imfusion/web-ui@<version>` when the user supplied an explicit version. Stop on install failure. Preserve
-the installer's existing target. Do not use `--force` or `--legacy-peer-deps`.
+Run these from the consumer package root, the directory holding the `node_modules` that the dependency install just wrote.
+`npx` resolves `web-ui-install` from the installed `@imfusion/web-ui` there; from any other directory it cannot find the
+binary. Preserve the existing target (`.agents`, `.claude`, or both); do not silently choose a new one.
+
+Always run both installer commands after the package update. Skills and installer-owned hook scripts may have changed even
+when their existing registrations already cover session start, subagent start, prompt submit, and the stop gate. The hook
+installer refreshes those scripts wholesale, prunes retired scripts and their registrations, and merges registrations
+idempotently into both host files (`.claude/settings.json` and `.codex/hooks.json`). Stop on malformed settings or installer
+conflicts.
+
+## Verification
+
+After each mutating command, compare `git status --short` with the preflight snapshot.
 
-The installer owns the vendored skills, its `AGENTS.md` fence, and hook scripts. Run both installer commands after the
-package update even when the existing registrations look complete: they refresh scripts, prune retired registrations, and
-merge installer-owned entries idempotently into `.claude/settings.json` and `.codex/hooks.json`. Stop on malformed settings
-or installer conflicts. Read existing host registrations first and do not stack an event the project already covers.
+Classify paths as:
 
-## Verify the base update
+- **Update-owned:** package files and installer-owned files changed by this workflow.
+- **Held back:** pre-existing user changes, excluded from the commit.
+- **Conflict:** an overlapping pre-existing change, ambiguous target, or unexpected changed path.
 
-After every mutating command, compare the status with the preflight snapshot. Stop on an unexpected path or overlapping
-change.
+On conflict, stop. Never use `git restore`, `git reset`, `git clean`, or broad staging to hide it.
 
-Run the consumer's documented full verification. Read its scripts first; prefer an aggregate check, otherwise run the
-non-watch format, lint, typecheck, test, and build commands that exist.
+Run the frontend package's documented full verification after the base update. Read its `package.json` scripts and choose
+commands that cover typechecking, linting, tests, and building. Prefer one documented aggregate `verify`/`check` script when
+it covers those responsibilities; otherwise run the documented non-watch scripts for the responsibilities that exist. Do not
+invent script names or run watch/dev scripts. A type or build failure is a base-update conflict to resolve before the base
+commit, not a migration finding to defer.
 
-Check the dependency and lockfile, skill markers, `AGENTS.md` fence, hook registrations, and final update-owned path list.
+Verify the dependency/lockfile, current skill markers, the `AGENTS.md` fence, hook coverage, and the final path list. In
+dry-run mode, say that mutation-dependent checks were skipped.
 
-Report before the first commit:
+## Base update report and approval
+
+Before the base commit, show this concise report:
 
 ```text
 @imfusion/web-ui update report
-Package      : <old> -> <new>
+Package      : <old> -> <new> / would update
 Skills       : <status>
 Hooks        : <status>
 Verification : <status>
 Update files : <paths>
 Held back    : <paths or none>
 Conflicts    : <paths or none>
-Commit       : <message or not proposed>
+Commit       : <imperative message or not proposed>
 ```
 
-Ask: **Approve these update-owned changes and commit them?** Stage only approved update paths and follow the repository's
-commit workflow.
+Normal mode: ask exactly, **“Approve these update-owned changes and commit them?”** Do not commit without an affirmative
+answer. If denied, leave the changes uncommitted.
+
+Dry-run mode: state **“Dry run complete; no changes or commit were made.”** Do not mutate or ask for commit approval.
+
+## Consumer migration audit
+
+Begin this phase only after the approved base update has been committed. Record the old and new package versions from the
+pre-update and current manifests/lockfile. Use the current package's exported types, generated documentation, and component
+examples as the source of truth. Use the old version's package metadata or repository history when available to identify what
+changed; do not pretend a changelog exists.
+
+Run the same documented full verification again after the base commit. Separate findings into:
+
+- **Compatibility fixes:** existing web-ui imports, props, or usage patterns that no longer typecheck, build, lint, or pass
+  tests.
+- **Changed component usages:** existing components whose current API, behavior, or documented contract changed between the
+  two versions and may need a consumer update, even when the typecheck passes.
+- **Replacement candidates:** custom consumer components, wrappers, or field implementations that overlap with a component
+  now exported by `@imfusion/web-ui`. Inspect their code, styles, and call sites before suggesting a replacement. Include the
+  current custom implementation, the proposed web-ui component, the relevant API/type evidence, and any behavior or styling
+  that still needs to be preserved.
+
+Report these findings separately from the base update. Ask whether to apply the proposed migration. If the user declines,
+leave the consumer code unchanged. If accepted, make only the approved migration changes, run the documented full
+verification again, and show a second report with the migration paths, held-back paths, conflicts, and verification result.
+
+If no findings exist, report that the installed update has no detected compatibility fixes, changed usages, or replacement
+candidates. Do not create an empty migration commit.
 
-## Audit the consumer migration
+Whatever the migration outcome, close the phase by asking whether to run `imf-web-ui-audit full`: an update can shift the
+baseline (new components, hooks, conventions), and the audit shows where the project now stands against it. Run it only on an
+explicit yes.
 
-Start this phase only after the base update commit exists. Use the pre-update package metadata as the comparison baseline;
-don't assume a changelog exists. Compare the old and new package metadata, current generated docs, types, and examples. Run
-the full verification again.
+## Migration approval
 
-Report separately:
+Ask exactly, **“Approve these consumer migration changes and commit them separately?”** Do not commit without an affirmative
+answer. The migration approval is not implied by approval of the base update.
 
-- compatibility fixes required by changed imports or types;
-- existing uses affected by a changed API or documented behavior;
-- custom components that overlap with a current Web UI primitive, with evidence and any behavior to preserve.
+## Commit
 
-Do not infer a replacement from a name. Inspect the implementation, styles, and call sites. If there are no findings, say so
-and do not make an empty migration commit.
+For the base update, after approval:
 
-Ask whether to run `imf-web-ui-audit full`. Run it only after an explicit yes.
+1. Recheck status and exclude held-back paths.
+2. Stage base update-owned paths selectively. Never use `git add .` or `git add -A`.
+3. Run the repository's commit workflow if it has one, including its required verification and documentation audit. Otherwise
+   run documented verification and follow the repository's commit convention.
+4. Commit with a concise imperative message and confirm the commit and final status.
 
-For approved migration work, ask: **Approve these consumer migration changes and commit them separately?** Then stage only
-the approved paths, verify again, and use a separate imperative commit message.
+For an approved migration, repeat the same selective staging and documented commit workflow with a separate imperative
+message. Never bypass hooks or amend an unrelated commit after a hook failure.

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

@@ -1,75 +1,103 @@
 ---
 name: imf-web-ui-ux
 description:
-  "Help shape screens and flows with @imfusion/web-ui. Use this whenever a task chooses between components, defines layout,
-  or needs empty/loading/error states, even when the user asks only for an implementation. Do not use it for a prop lookup."
+  "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)."
 ---
 
-# 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-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-conventions`; project wiring lives in the `library-setup` topic of `imf-web-ui-conventions`.
+
+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-conventions`.
 
-The identity index marks components as stable or experimental. Experimental components are usable, but prefer wrapping one
-when it is used across many call sites so API movement stays local.
-
-## Ask only what matters
-
-If the request is vague and a human can answer, ask these questions one at a time and stop once the choice is clear:
-
-1. Who uses the screen, and how often?
-2. What is its one primary action?
-3. What data does it show, and roughly how much?
-4. What should users see when it is empty, loading, or failing?
-5. Is it a full page or part of another flow?
-
-If the prompt already answers a question, do not ask it again. If nobody can answer, 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.
-
-## Choose between similar controls
-
-- `Button` performs an action, `ChipLink` goes somewhere, and `Chip` labels something.
-- 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.
-
-## Build the hierarchy
-
-- Frame an application with `AppShell`.
-- Compose `Stack` and `Row` for spacing and arrangement. Use `Separator` for a real division.
-- Use `Typo` for text hierarchy instead of styling raw headings beside it.
-- 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.
-
-## Cover the states
-
-Plan these states with the loaded view:
+## Experimental components
 
-- **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.
-- **Loaded**: the normal view.
+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-conventions`) so a breaking change lands in one file,
+not forty call sites.
 
-## Keep custom UI native
+## Deep dives
 
-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`.
+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:
 
-For a screen review, read the relevant reference under `references/`: `usability-heuristics.md`, `visual-design.md`, or
-`forms.md`.
+- [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.

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

@@ -1,30 +1,50 @@
 # 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.
+The 80/20 of forms, distilled from NN/g's form-design and error-guidelines articles
+([form design](https://www.nngroup.com/articles/web-form-design/),
+[errors](https://www.nngroup.com/articles/errors-forms-design-guidelines/)). Forms are where inexperienced UI work loses the
+most users — a cited CHI study found guideline-compliant forms hit 78% one-try error-free submission vs. 42% for
+non-compliant ones. Read before building any form beyond two fields.
+
+The library ships the controls (`Input`, `Select`, `Checkbox`, `Switch`, `Slider`) but no form or field wrapper, so labels,
+grouping, and where errors appear are composed by you. That's exactly where these rules apply. Composing the markup is not
+the same as owning the state: form state and validation belong to a form library (see `imf-web-ui-conventions`), and these
+rules govern how its errors get presented.
 
 ## 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.
-- Match a field's size to the value it expects.
+- **Cut every cuttable field.** Each field that can be derived, deferred, or omitted costs completions. Optional fields:
+  first try to eliminate them; keep at most 1–2 and mark _them_ explicitly with "(optional)" — don't asterisk the required
+  majority.
+- **Single column.** Multiple columns break the vertical momentum of filling a form. The one exception: short, logically
+  inseparable fields (city / postal code) may share a `Row`.
+- **Group by topic.** Related fields sit tight in a `Stack`; groups separate with larger whitespace (proximity is grouping —
+  see [visual-design.md](visual-design.md)). Keep groups accessible: a labeled `fieldset` or heading per group.
+- **Match field size to expected input.** A two-letter field shouldn't be full-width; a free-text reason shouldn't be one
+  line.
 
 ## Labels
 
-Use a visible `<label>` close to the control, usually above it. Do not use placeholder text as the only label. Put format
-hints near the field before the user starts typing.
+- **Real `<label>` elements, outside the field, close to it.** Above the field is the default (works on mobile, scans fast).
+- **Never placeholder text as the label.** It vanishes on input, so users can't review what a filled field means or check
+  errors. Persistent hints (format examples) go outside the field, stated _before_ the user types, not revealed by the error
+  afterward.
 
 ## Validation and errors
 
-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.
+- **Validate when the user finishes a field, not while typing.** Premature validation — flagging a field as wrong while it's
+  still being filled — reads as hostile. Live feedback is only for cases where it genuinely helps as the user types (e.g. a
+  password-requirements checklist).
+- **Errors sit next to the offending field**, with multiple cues — outline plus message, never color alone. Never rely solely
+  on a summary at the top of the form.
+- **Error text is precise, human, and constructive**: what's wrong, and what to do — "Date must be in the future", not
+  "Invalid input". A form-level failure (server rejected) gets a `Callout` above the actions; field-level problems stay at
+  their fields.
+- **Preserve the user's input.** An error never empties the field, and there is no Reset/Clear button — its main use is being
+  clicked by accident.
 
 ## Submission
 
-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.
+- One primary submit `Button`, labeled with the action's outcome ("Create project", not "Submit"). While submitting: the
+  button shows progress and the form stays visible — on failure the user must see their input plus the error, not a blank
+  form (see also heuristic 9 in [usability-heuristics.md](usability-heuristics.md)).

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

@@ -1,16 +1,29 @@
-# Usability heuristics
+# Usability heuristics, applied
 
-Use this checklist when reviewing a screen or flow. It is an application of Nielsen's ten heuristics, not a replacement for
-user research.
+Nielsen's ten usability heuristics ([source](https://www.nngroup.com/articles/ten-usability-heuristics/)) are the highest
+80/20 leverage in interaction design — most usability problems in a screen violate one of these. Walk them as a checklist
+when reviewing or reworking a flow. Each entry: the rule, then what it means in a web-ui app.
 
-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.
-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.
+1. **Visibility of system status** — always show what's happening via timely feedback. In practice: every async action gets a
+   `Spinner` or disabled-with-progress state; every mutation confirms visibly near its trigger; never leave a button that
+   "did nothing" for two seconds.
+2. **Match the system to the real world** — use the users' words, not internal jargon; order information the way the domain
+   thinks. Label buttons and `Table` columns in the vocabulary of the people from the interview, not the API's field names.
+3. **User control and freedom** — clearly marked exits. Every `Drawer` and `Popover` is dismissable (Esc, backdrop, visible
+   close); destructive actions get an undo or a confirm step — never both missing.
+4. **Consistency and standards** — the same action looks the same everywhere; users' expectations come from every other
+   product they use (Jakob's Law). Using the library's components with their default semantics _is_ this heuristic; a second
+   hand-rolled pattern for something a component already does is a violation.
+5. **Error prevention** — constraints and good defaults beat good error messages. Prefer `Select` over free text when options
+   are known; disable invalid actions instead of explaining them after the click; confirm before irreversible commitment.
+6. **Recognition rather than recall** — keep options and context visible; don't force users to remember values across
+   screens. If step 2 needs a value from step 1, show it; that's what `Collapsible` summaries and persistent `Chip` labels
+   are for.
+7. **Flexibility and efficiency of use** — accelerators for experts that novices never see. The interview's power-user answer
+   decides this: daily-use screens earn keyboard shortcuts and dense `Table` defaults.
+8. **Aesthetic and minimalist design** — every extra element competes with the relevant ones. If a screen element doesn't
+   serve the primary action or the data, cut it — this is the design-side twin of "compose, don't configure."
+9. **Help users recognize, diagnose, and recover from errors** — plain-language messages that state the problem precisely and
+   suggest the fix, in a `Callout` next to where it went wrong. "Something went wrong" is a violation, not a message.
+10. **Help and documentation** — best if unneeded; when needed, contextual and task-focused. Prefer a one-line hint near the
+    control (not a `Tooltip` hiding essential information) over a help page.

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

@@ -1,22 +1,38 @@
-# Visual design
-
-Use this when a screen works but still looks wrong. Decide the hierarchy before choosing styles.
-
-## Hierarchy
-
-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.
-
-## 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.
-
-Similarity helps related elements stay recognisable across a layout. It supports proximity; it does not replace it.
-
-## Whitespace
-
-Space around an element gives it attention. Shrink or blur a screenshot as a quick check: the title and primary action should
-still stand out. If the screen becomes one grey mass, its contrast and spacing are too even.
+# Visual design fundamentals
+
+The 80/20 of making a functionally complete screen _look right_, distilled from NN/g's visual-hierarchy and Gestalt articles
+([hierarchy](https://www.nngroup.com/articles/visual-hierarchy-ux-definition/),
+[proximity](https://www.nngroup.com/articles/gestalt-proximity/),
+[similarity](https://www.nngroup.com/articles/gestalt-similarity/)). Read when a screen works but looks wrong and you can't
+say why — the answer is almost always in here.
+
+## Hierarchy: decide the eye's order first
+
+Visual hierarchy means the eye consumes elements in order of intended importance. Before styling anything, write down the
+order: what should be seen first, second, third? Then make the styling agree. If you can't rank the elements, the screen has
+an information-architecture problem, not a styling problem — go back to the interview's "one primary action."
+
+- **Contrast creates hierarchy, not hue.** What advances is what contrasts with its context. The primary `Button` variant is
+  the contrast peak of the screen — which is why there's only one. Reserve warm, saturated signals (red) for errors/warnings,
+  never decoration.
+- **Scale = importance.** The most important element is the biggest; keep at most two genuinely large elements per screen.
+- **Limit variation, or nothing stands out.** At most ~3 contrast treatments and 3 type sizes per screen. `Typo`'s role
+  levels are this rule made concrete — if you're reaching past them, you're adding a fourth size that dilutes the other
+  three.
+
+## Grouping: proximity beats everything
+
+- **Proximity is grouping.** Elements close together read as one unit — this overpowers color and shape cues. Tight gap
+  between a label and its control, larger gap between one group and the next. Use `Stack` gap steps for exactly this: small
+  within groups, large between them. Never equidistant spacing — it says nothing.
+- **Common region.** A shared container (`Card`, a bordered region) makes enclosed items read as related. Powerful, and
+  clutter when overused — if `Stack` spacing already groups it, the border adds nothing.
+- **Similarity.** Shared color/shape/size signals relatedness across distance — all `Chip`s of one meaning look the same
+  everywhere. Weaker than proximity, but it survives layout changes.
+
+## Whitespace and the squint test
+
+More space around an element gives it more attention — whitespace is an active tool, not leftover room. Verify with the
+squint test: blur your eyes (or downscale a screenshot); the primary action and the screen's title should still dominate. If
+everything blurs into one gray mass, contrast and spacing are too uniform — pick the one thing that matters and make the
+styling say so.

package/src/llms/tokens.gen.json

@@ -153,7 +153,7 @@
       },
       {
         "name": "--imf-ui-color-bg-minor",
-        "value": "light-dark( oklch( calc(var(--imf-ui-color-surface-bg-luma-light) - 0.04) var(--imf-ui-color-surface-chroma) var(--imf-ui-color-surface-minor-hue) ), oklch( calc(var(--imf-ui-color-surface-bg-luma-dark) + 0.04) var(--imf-ui-color-surface-chroma) var(--imf-ui-color-surface-minor-hue) ) )"
+        "value": "light-dark( oklch( calc(var(--imf-ui-color-surface-bg-luma-light) - 0.075) var(--imf-ui-color-surface-chroma) var(--imf-ui-color-surface-minor-hue) ), oklch( calc(var(--imf-ui-color-surface-bg-luma-dark) + 0.075) var(--imf-ui-color-surface-chroma) var(--imf-ui-color-surface-minor-hue) ) )"
       },
       {
         "name": "--imf-ui-color-bg-negative",
@@ -177,7 +177,7 @@
       },
       {
         "name": "--imf-ui-color-bg-support",
-        "value": "light-dark( oklch( calc(var(--imf-ui-color-surface-bg-luma-light) - 0.02) var(--imf-ui-color-surface-chroma) var(--imf-ui-color-surface-support-hue) ), oklch( calc(var(--imf-ui-color-surface-bg-luma-dark) + 0.02) var(--imf-ui-color-surface-chroma) var(--imf-ui-color-surface-support-hue) ) )"
+        "value": "light-dark( oklch( calc(var(--imf-ui-color-surface-bg-luma-light) - 0.025) var(--imf-ui-color-surface-chroma) var(--imf-ui-color-surface-support-hue) ), oklch( calc(var(--imf-ui-color-surface-bg-luma-dark) + 0.025) var(--imf-ui-color-surface-chroma) var(--imf-ui-color-surface-support-hue) ) )"
       },
       {
         "name": "--imf-ui-color-bg-warning",
@@ -285,7 +285,7 @@
       },
       {
         "name": "--imf-ui-color-status-chroma",
-        "value": "0.225"
+        "value": "0.265"
       },
       {
         "name": "--imf-ui-color-status-fg-luma-dark",
@@ -313,11 +313,11 @@
       },
       {
         "name": "--imf-ui-color-surface-bg-luma-dark",
-        "value": "0.205"
+        "value": "0.27"
       },
       {
         "name": "--imf-ui-color-surface-bg-luma-light",
-        "value": "0.995"
+        "value": "0.97"
       },
       {
         "name": "--imf-ui-color-surface-chroma",

package/dist/codegen/gen-code-highlight-theme.d.ts

@@ -1 +0,0 @@
-export declare function writeCodeHighlightTheme(): void;

package/dist/components/toast/index.d.ts

@@ -1,2 +0,0 @@
-export * as Toast from './toast';
-export { toastMeta } from './toast.meta';