@imfusion/web-ui 0.5.0

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

@@ -0,0 +1,48 @@
+# 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 — labels,
+grouping, and validation display are composed by you, which is exactly where these rules apply.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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)).

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

@@ -0,0 +1,29 @@
+# Usability heuristics, applied
+
+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. **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

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