@imfusion/web-ui 0.6.1-dev.12.ge86ac0a1 → 0.6.1-dev.14.g8fac1dfb

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.