@imfusion/web-ui 0.8.1-dev.3.g40eaad1c → 0.8.1-dev.31.g7b15b0d3

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

@@ -1,11 +1,11 @@
 ---
 name: imf-web-ui-audit
 description:
-  "Audit an existing ImFusion frontend against the @imfusion/web-ui conventions without changing files. Use this for a
-  project health check, a pre-setup review, or one named topic. Report broken and missing pieces, working deviations,
+  "Audit an existing ImFusion frontend against the @imfusion/web-ui conventions without changing project files. Use this for
+  a project health check, a pre-setup review, or one named topic. Report broken and missing pieces, working deviations,
   evidence, and an ordered plan."
 argument-hint: "[full|<topic>]"
-allowed-tools: Read Glob Grep
+allowed-tools: Read Glob Grep Skill
 ---
 
 # Audit a consumer project
@@ -21,6 +21,8 @@ it low, and do not let it crowd the sections a consumer has to act on.
 
 ## Workflow
 
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
 1. Resolve the argument. Bare means `full`; an unknown topic is an error, not a reason to widen the scope.
 2. Enter plan mode unless this audit is being called as verification by another skill or the host has no plan mode.
 3. Read the report template and existing reviewer notes, then dispatch one investigator per in-scope topic. Tell each

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

@@ -4,13 +4,15 @@ description:
   "Look up @imfusion/web-ui component APIs, compound parts, defaults, and icon glyphs without reading source. Use this
   whenever a consumer task names a Web UI component or icon and you need to choose a prop, part, default, or glyph. Do not
   use it to choose between components or bootstrap a project."
-allowed-tools: Bash
+allowed-tools: Bash Skill
 ---
 
 # Look up components
 
 Use the generated package indexes. They are smaller and more reliable than reading the library source.
 
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
 ## Component lookup
 
 1. Read the identity index first, even when you already know the component's name: it gives the docgen key and the status.

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

@@ -50,6 +50,7 @@ sections one to one — change a topic's sections and this file follows in the s
 
 - [ ] Types
 - [ ] Immutability & expressions
+- [ ] Functions
 - [ ] Naming
 
 ## Styling — `styling`

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

@@ -19,7 +19,8 @@ Use one server-backed current-user query as the identity source:
 
 - Put it in `api/auth/queries.ts` and define its key and schema with the [data.md](data.md) pattern.
 - Expose query options as `context.api.auth.getUser()`.
-- Call `ensureQueryData` in a loader or a query hook in a component.
+- Call `queryClient.query({ ...options, staleTime: "static" })` in a loader (see [data.md](data.md)) or a query hook in a
+  component.
 - Keep credentials and access tokens out of React state.
 - Do not infer authentication from local storage, decoded tokens, route flags, or permission-gated UI.
 

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

@@ -85,9 +85,11 @@ export function getDetails(options?: QueryOptions<User>) {
 }
 ```
 
-Callers choose `ensureQueryData`, `useSuspenseQuery`, or another Query API. Mutation factories likewise return
-`mutationOptions`, own their mutation key and parsing, and are passed to `useMutation`; do not inline those options at the
-call site.
+Callers choose `queryClient.query`, `useSuspenseQuery`, or another Query API. A router loader reads the cache with
+`queryClient.query({ ...options, staleTime: "static" })`, not the deprecated `ensureQueryData` or `fetchQuery`. Keep
+`"static"`: without it the factory's `staleTime` applies (default 0), so every loader run waits on the network and the page's
+`useQuery` refetches on mount. Mutation factories likewise return `mutationOptions`, own their mutation key and parsing, and
+are passed to `useMutation`; do not inline those options at the call site.
 
 ## Router context access
 

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

@@ -7,6 +7,8 @@ Use native CSS and Web UI's public seams. The library's CSS Modules and token na
 - Use CSS Modules with native nesting. Do not add Sass, CSS-in-JS, or a utility-class framework for ordinary component
   styles.
 - Nest states, pseudo-elements, and child selectors under the root.
+- Write declarations before nested rules; browsers before Chrome 130, Firefox 132, and Safari 18 move later ones above them.
+- Do not nest under a selector list whose selectors differ in specificity. The nested rule takes the highest one.
 - Lift repeated values into custom properties, especially when a state or variant changes several descendants.
 - Keep structurally different rules explicit; not every repeated value needs an abstraction.
 
@@ -85,8 +87,8 @@ Foreground roles are for text, icons, borders, and focus rings. Background roles
 
 ## Browser floor
 
-The library targets Safari 16.2 or newer. `color-mix(in oklch, …)` is available at that floor. Relative color syntax needs a
-guarded fallback for older Safari:
+The library targets Safari 17.5, Chrome 123, and Firefox 120 or newer, the first versions with native `light-dark()`.
+`color-mix(in oklch, …)` is available at that floor. Relative color syntax needs a guarded fallback for older Safari:
 
 ```css
 .subtle {

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

@@ -30,6 +30,20 @@ input. Use `toSorted` and `toReversed` instead of their mutating counterparts.
 A loop is fine when it has a real early exit or measured hot-path benefit. A long chain or a `reduce` with several jobs wants
 named intermediate values.
 
+## Functions
+
+Declare a named function with `function`, including a local helper inside a component. A callback passed inline as a prop or
+argument stays an arrow.
+
+```tsx
+function resetCaptcha() {
+  captcha.current?.reset();
+}
+
+<Button onClick={() => setOpen(true)}>Open</Button>;
+items.map(item => item.id);
+```
+
 ## Naming
 
 Name what a value is, not how it is built. Booleans read as assertions (`isOpen`, `hasAccess`, `canSubmit`). Props use `onX`;

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

@@ -15,6 +15,8 @@ working choices.
 
 ## Workflow
 
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
 1. Resolve the scope. A named topic limits the assessment to that topic. A bare invocation means `full`, unless the request
    is about one topic, in which case that topic is the scope: answer what was asked and offer the wider sweep rather than
    running it. If the argument is unknown, list the supported topics and point to `imf-web-ui-audit`.

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

@@ -5,7 +5,7 @@ description:
   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
+allowed-tools: Bash Read Grep Skill
 ---
 
 # Update Web UI
@@ -13,6 +13,22 @@ allowed-tools: Bash Read Grep
 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.
 
+## Before you start
+
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
+Open with a short orientation, before any command runs, so the person knows the route and when they will be asked:
+
+1. **Preflight**: check the project and stop on uncommitted work.
+2. **Base update**: install the new package, refresh the skills and hooks, verify, then ask to commit.
+3. **Migration check**: read what the new releases changed and report what this project needs; changes and their separate
+   commit wait for approval.
+4. **Full audit**: offer `imf-web-ui-audit full`, a read-only check of the whole project against the conventions, wider than
+   what this release changed.
+
+Name the decision points up front: `latest` or `dev` when the installed version is a prerelease, the base commit, the
+migration commit, and the audit offer. With `--dry-run`, say the run stops after preflight and changes nothing.
+
 ## Preflight
 
 1. Work from the frontend package root. In a monorepo, find the package that owns the Web UI dependency.
@@ -20,9 +36,22 @@ Never overwrite user changes or commit without fresh approval.
    if another lockfile is the active one.
 3. Record `git status --short`, the installed Web UI version, the installed skill harness(es), hooks, registrations, and
    `AGENTS.md` fence.
-4. Check for another npm process and stop on a conflict. Uncommitted work is also a conflict: report it and stop before the
-   first mutating command, even if it looks unrelated to this workflow: what the update touches is only known once it runs,
-   and the person can commit, stash, or wave it through in one reply. Never reset, clean, restore, or hide it.
+4. Check for another npm process in this package and stop on a conflict:
+
+   ```sh
+   pgrep npm                     # process IDs only
+   lsof -a -d cwd -p <pid> -Fn   # the folder a process runs in
+   ps -o args= -p <pid>          # its command, only when that folder is this package
+   ```
+
+   A running install, update, or `ci` in this package is a conflict; a long-running `npm exec` server is not. Full process
+   listings such as `pgrep -fl` or `ps aux` print every program's arguments, secrets included, so keep them out of the
+   transcript.
+
+   Uncommitted work is also a conflict: report it and stop before the first mutating command, even if it looks unrelated to
+   this workflow: what the update touches is only known once it runs, and the person can commit, stash, or wave it through in
+   one reply. Never 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.
 
@@ -87,12 +116,13 @@ Update files : <paths>
 Held back    : <paths or none>
 Conflicts    : <paths or none>
 Commit       : <message or not proposed>
+Next         : migration check, then the optional full audit
 ```
 
 Ask: **Approve these update-owned changes and commit them?** Stage only approved update paths and follow the repository's
 commit workflow.
 
-## Audit the consumer migration
+## Check the consumer migration
 
 Start this phase only after the base update commit exists. Read `node_modules/@imfusion/web-ui/CHANGELOG.md`: every release
 section after the pre-update version, up to and including the new one. Each section's highlights, migration guide, and
@@ -119,7 +149,8 @@ releases read, then report separately:
 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.
 
-Ask whether to run `imf-web-ui-audit full`. Run it only after an explicit yes.
+Offer `imf-web-ui-audit full` as the next step: the migration check covered what the releases changed, the audit checks the
+whole project against the conventions and changes nothing. Run it only after an explicit yes.
 
 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-user-profile/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: imf-web-ui-user-profile
+description:
+  "Read or create the person's profile: technical background, experience, how they want things explained, and how they like
+  to work. Invoke it first in every Web UI skill, and when the person asks to change their profile or how the agent explains
+  or paces work."
+user-invocable: false
+allowed-tools: Bash Read Write
+---
+
+# Fit the work to the person
+
+The profile records who the person is and how they learn, so every Web UI workflow explains what they need and paces the work
+the way they like. Read it once per session; later skills in the same session reuse what is already loaded.
+
+## Read the profile
+
+Resolve the profile path with the shell, then read that exact path:
+
+```sh
+printf '%s\n' "${XDG_CONFIG_HOME:-$HOME/.config}/imfusion/web-ui/consumer-profile.md"
+```
+
+The profile sits outside the project: it belongs to the person, never to the repository, so read-only promises such as the
+audit's still hold when this skill writes it.
+
+When the file exists, apply it and return to the calling workflow without comment. When it is missing, run the interview
+before the workflow starts. When the router skips companions for a small task, do the task first and offer the interview
+afterwards.
+
+## Interview
+
+Open with one question: may you ask six short questions and save the answers to the profile path, so every later workflow
+fits them and they are never asked again? Mention that they can decline any single question. On no, use the defaults below
+for this session and do not offer the interview again in it.
+
+On yes, ask one question per message, in plain prose, and wait for each answer:
+
+1. What is your name?
+2. What is your technical background: the languages and tools you work with?
+3. How much have you built for the web, for example with React, HTML, and CSS?
+4. Beyond Git, how comfortable are you with npm and the terminal?
+5. How much explanation do you want: just the results, a short gloss for new terms, or the reasoning behind each step?
+6. How do you like to work: pause after every step, pause after each finished piece, or work freely and stop only before a
+   commit?
+
+Derive the levels from the answers; ask a short follow-up only when an answer fits no level. The person can decline any
+question: its field stays out of the file, and its default applies: `some`, `comfortable`, `terms`, `slice`.
+
+## The file
+
+Show the profile below before writing it. The person can correct or remove any line, or reject the whole profile; on a
+rejection, save nothing and use the defaults for this session. After they confirm, write it and name its path so they can
+edit or delete it later:
+
+```markdown
+---
+name: <their name>
+frontend: none | some | seasoned
+tooling: new | comfortable
+explanation: results | terms | reasoning
+pace: step | slice | commit
+---
+
+## Background
+
+<their answer to question 2, in their words>
+
+## Notes
+
+- <lasting preferences learned later>
+```
+
+When the write fails, keep the answers for this session. When the person later states a lasting preference about how to work
+with them, such as a language, a term they want avoided, or a tool they already know, add it under `Notes` and tell them.
+When they ask to change their profile, run the interview again with the current answers as defaults.
+
+## Apply the profile
+
+The fields apply independently.
+
+- **Name**: address the person by name.
+- **Background**: explain by analogy to what they already know, such as a component compared to a class for a Java developer.
+- **Frontend `none` or `some`**: give a one-line gloss the first time a frontend term appears, such as component, prop,
+  design token, CSS layer, or Storybook. For `none`, also say what a finding means for the running app.
+- **Tooling `new`**: gloss tooling terms on first use, such as lockfile, dist-tag, prerelease, hook, harness, or the
+  `AGENTS.md` fence; say in one plain sentence what each command does before it runs, read-only checks included; and before
+  an approval question, say what yes changes and how to undo it.
+- **Explanation**: `results` adds nothing beyond what the experience levels call for; `terms` glosses every new term;
+  `reasoning` also says why each step happens, and after a report block, what happened and what comes next.
+- **Pace**: `step` ends the reply after each step or phase of the calling workflow and waits for a go-ahead; `slice` pauses
+  after each working piece; `commit` runs freely between the workflow's own approval points.
+
+Pace adds pauses on top of the calling workflow's approval gates and keeps every one of them. Put explanations around report
+blocks and approval questions, never inside them.

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

@@ -10,6 +10,8 @@ description:
 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`.
 
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
 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.
 

package/src/llms/tokens.gen.json

@@ -681,11 +681,11 @@
       },
       {
         "name": "--imf-ui-font-weight-medium",
-        "value": "500"
+        "value": "400"
       },
       {
         "name": "--imf-ui-font-weight-regular",
-        "value": "450"
+        "value": "300"
       },
       {
         "name": "--imf-ui-font-weight-strong",
@@ -715,7 +715,7 @@
       },
       {
         "name": "--imf-ui-inner-shadow-highlight",
-        "value": "inset calc(-0.5px * var(--imf-ui-shadow-x)) calc(-0.5px * var(--imf-ui-shadow-y)) 0 0 #fff, inset calc( 0.5px * var(--imf-ui-shadow-x)) calc( 0.5px * var(--imf-ui-shadow-y)) 0 0 #0001"
+        "value": "inset calc(-0.5px * var(--imf-ui-shadow-x)) calc(-0.5px * var(--imf-ui-shadow-y)) 0 0 light-dark(#fff, #fff1), inset calc( 0.5px * var(--imf-ui-shadow-x)) calc( 0.5px * var(--imf-ui-shadow-y)) 0 0 light-dark(#0001, #0007)"
       },
       {
         "name": "--imf-ui-inner-shadow-tint",