@imfusion/web-ui 0.6.1-dev.6.g4adc5c3e → 0.6.1

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

@@ -1,157 +1,91 @@
 ---
 name: imf-web-ui-update
 description:
-  "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."
+  "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."
 argument-hint: "[--dry-run] [optional version or reason]"
 allowed-tools: Bash Read Grep
 ---
 
-# 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.
+# 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.
 
 ## Preflight
 
-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.
+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.
 
-## Base update
+## Update the base
 
-In a non-dry run, update the dependency:
+Run from the consumer package root:
 
 ```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
 ```
 
-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.
+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`.
 
-Classify paths as:
+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.
 
-- **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.
+## Verify the base update
 
-On conflict, stop. Never use `git restore`, `git reset`, `git clean`, or broad staging to hide it.
+After every mutating command, compare the status with the preflight snapshot. Stop on an unexpected path or overlapping
+change.
 
-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.
+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.
 
-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.
+Check the dependency and lockfile, skill markers, `AGENTS.md` fence, hook registrations, and final update-owned path list.
 
-## Base update report and approval
-
-Before the base commit, show this concise report:
+Report before the first commit:
 
 ```text
 @imfusion/web-ui update report
-Package      : <old> -> <new> / would update
+Package      : <old> -> <new>
 Skills       : <status>
 Hooks        : <status>
 Verification : <status>
 Update files : <paths>
 Held back    : <paths or none>
 Conflicts    : <paths or none>
-Commit       : <imperative message or not proposed>
+Commit       : <message or not proposed>
 ```
 
-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.
+Ask: **Approve these update-owned changes and commit them?** Stage only approved update paths and follow the repository's
+commit workflow.
 
-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.
+## Audit the consumer migration
 
-## Migration approval
+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.
 
-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.
+Report separately:
 
-## Commit
+- 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.
 
-For the base update, after approval:
+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.
 
-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.
+Ask whether to run `imf-web-ui-audit full`. Run it only after an explicit yes.
 
-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.
+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.

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

@@ -1,103 +1,75 @@
 ---
 name: imf-web-ui-ux
 description:
-  "UX guidance for building screens with @imfusion/web-ui when no designer is around: pick the right component for an
-  interaction, lay out common screen types, handle empty/loading/error states. Load when building or reshaping a screen,
-  flow, or feature UI — not for prop lookups (that's imf-web-ui-components)."
+  "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."
 ---
 
-# 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
+# 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`.
 
-## Experimental components
+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:
 
-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.
+- **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.
 
-## Deep dives
+## Keep custom UI native
 
-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:
+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`.
 
-- [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.
+For a screen review, read the relevant reference under `references/`: `usability-heuristics.md`, `visual-design.md`, or
+`forms.md`.

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

@@ -1,50 +1,30 @@
 # Form UX
 
-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.
+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.
 
 ## Structure
 
-- **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.
+- 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.
 
 ## Labels
 
-- **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.
+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.
 
 ## Validation and errors
 
-- **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.
+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.
 
 ## Submission
 
-- 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)).
+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

@@ -1,29 +1,16 @@
-# Usability heuristics, applied
+# Usability heuristics
 
-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.
+Use this checklist when reviewing a screen or flow. It is an application of Nielsen's ten heuristics, not a replacement for
+user research.
 
-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.
+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.

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

@@ -1,38 +1,22 @@
-# 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.
+# 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.

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.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) ) )"
+        "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) ) )"
       },
       {
         "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.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) ) )"
+        "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) ) )"
       },
       {
         "name": "--imf-ui-color-bg-warning",
@@ -285,7 +285,7 @@
       },
       {
         "name": "--imf-ui-color-status-chroma",
-        "value": "0.265"
+        "value": "0.225"
       },
       {
         "name": "--imf-ui-color-status-fg-luma-dark",
@@ -313,11 +313,11 @@
       },
       {
         "name": "--imf-ui-color-surface-bg-luma-dark",
-        "value": "0.27"
+        "value": "0.205"
       },
       {
         "name": "--imf-ui-color-surface-bg-luma-light",
-        "value": "0.97"
+        "value": "0.995"
       },
       {
         "name": "--imf-ui-color-surface-chroma",