@imfusion/web-ui 0.5.1-dev.2.g0a349a2a → 0.5.1-dev.20.g9170acaf

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

@@ -0,0 +1,196 @@
+# Data
+
+How data enters, moves through, and leaves an ImFusion frontend. This is the in-house pattern **for TanStack Query + Router**
+— the default stack ([stack.md](stack.md)). A project on a different data layer keeps the boundary principles (validate at
+the edge, errors as values) but not necessarily this file layout.
+
+## The shape
+
+```
+src/
+  api/<topic>/       # one folder per API topic
+    <topic>.ts       #   queryOptions / mutationOptions
+    query-key.ts     #   key factory, topic as the first segment
+    types.ts         #   Zod schemas + z.infer types
+  http/              # transport: client, error normalisation — the only transport-aware place
+```
+
+A query lives next to its key factory and its schemas, so a query key is never spelled out at a call site. Anything
+transport-level (base client, error normalisation) lives in `http/` and nowhere else.
+
+## The network boundary validates
+
+The network is the only place untyped data enters the app, so it is the only place that validates. Everything a backend sends
+is parsed against a Zod schema at that edge; the TypeScript types are derived from the schemas with `z.infer`, never
+hand-written. A hand-written response type is a claim about the backend that nothing checks.
+
+The transport in `http/` is deliberately untyped: it returns `unknown` and leaves the parse to the caller, so no call site
+can accidentally skip validation.
+
+## Errors are values
+
+A failed request becomes an `ApiError` carrying a machine-readable code — it crosses the boundary the same way values do, not
+as an exception caught ad hoc. The frontend owns the mapping from codes to what the user reads.
+
+## The pattern, end to end
+
+The key factory — topic as the first segment, one function per key shape:
+
+```ts
+// api/user/query-key.ts
+const TOPIC = "user" as const;
+
+export const userKeys = {
+  all: [TOPIC] as const,
+  me: () => [TOPIC, "me"] as const,
+  detail: (id: string) => [TOPIC, "detail", id] as const
+};
+```
+
+Query options — key from the factory, parse at the boundary:
+
+```ts
+// api/user/user.ts
+import { queryOptions } from "@tanstack/react-query";
+
+import { bffClient } from "#/http/bff-client";
+import { userKeys } from "./query-key";
+import { userSchema } from "./types";
+
+export const userQueryOptions = () =>
+  queryOptions({
+    queryKey: userKeys.me(),
+    queryFn: async () => userSchema.parse(await bffClient("/me"))
+  });
+```
+
+Components consume query options directly with `useSuspenseQuery` (prefetched routes) or `useQuery` (secondary data). No
+wrapper hooks — the options function is the reusable unit.
+
+Mutations follow the same shape with `mutationOptions`, the dirtied topic first in the `mutationKey`:
+
+```ts
+// api/user/user.ts
+export const updateUserMutationOptions = () =>
+  mutationOptions({
+    mutationKey: [...userKeys.all, "update"],
+    mutationFn: async (patch: UserPatch) => userSchema.parse(await bffClient("/me", { method: "PATCH", body: patch }))
+  });
+```
+
+The root route types the router context so every loader can reach the query client via DI:
+
+```ts
+// routes/__root.tsx
+import { Outlet, createRootRouteWithContext } from "@tanstack/react-router";
+import type { QueryClient } from "@tanstack/react-query";
+
+interface RouterContext {
+  queryClient: QueryClient;
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: () => <Outlet />
+});
+```
+
+The router is created with that context filled in:
+
+```ts
+// router.ts
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+import { createQueryClient } from "./query-client";
+
+const queryClient = createQueryClient();
+
+export const router = createRouter({
+  routeTree,
+  context: { queryClient }
+});
+```
+
+A route prefetches in the `loader`, reads with `useSuspenseQuery`, and provides a `pendingComponent`; errors bubble to the
+nearest `errorComponent`:
+
+```tsx
+// routes/me.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+import { userQueryOptions } from "#/api/user/user";
+
+export const Route = createFileRoute("/me")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(userQueryOptions()),
+  pendingComponent: () => <p>Loading…</p>,
+  component: MePage
+});
+
+function MePage() {
+  const { data: user } = useSuspenseQuery(userQueryOptions());
+  return <h1>{user.name}</h1>;
+}
+```
+
+Mutations use `useMutation` with the options factory. Manual invalidation is unnecessary when automatic invalidation is on
+(see below):
+
+```tsx
+// components/user-settings.tsx
+import { useMutation } from "@tanstack/react-query";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+import { userQueryOptions, updateUserMutationOptions } from "#/api/user/user";
+
+function UserSettings() {
+  const { data: user } = useSuspenseQuery(userQueryOptions());
+  const updateUser = useMutation(updateUserMutationOptions());
+
+  return (
+    <form
+      onSubmit={e => {
+        e.preventDefault();
+        updateUser.mutate({ name: "New Name" });
+      }}
+    >
+      <input defaultValue={user.name} />
+    </form>
+  );
+}
+```
+
+## Automatic invalidation
+
+Mutations don't invalidate by hand at every call site — the query client does it centrally, keyed off the mutation's topic. A
+`MutationCache` `onSuccess` invalidates `mutationKey[0]`, on by default via `meta.autoInvalidate`; that's why every
+mutation's key leads with the topic it dirties:
+
+```ts
+// query-client.ts
+export function createQueryClient() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      mutations: { meta: { autoInvalidate: true } }
+    },
+    mutationCache: new MutationCache({
+      onSuccess: async (_data, _variables, _context, mutation) => {
+        if (!mutation.meta?.autoInvalidate) return;
+        const topic = mutation.options.mutationKey?.[0];
+        if (topic !== undefined) await queryClient.invalidateQueries({ queryKey: [topic] });
+      }
+    })
+  });
+  return queryClient;
+}
+```
+
+Opt out per mutation with `meta: { autoInvalidate: false }` when a coarse topic-wide refetch is wrong (a huge list, a
+targeted optimistic update), and invalidate precisely through the key factory instead. Background reading:
+[query invalidation](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation) and
+[automatic invalidation after mutations](https://tkdodo.eu/blog/automatic-query-invalidation-after-mutations).
+
+## Testing the data layer
+
+Stub the network at the `fetch` boundary and let the real query client run: the test then exercises the same parse and error
+path production does. Schemas, clients, and query options are where behaviour worth asserting lives — the general philosophy
+is [testing.md](testing.md).

package/src/llms/skills/imf-web-ui-frontend-conventions/references/docs-structure.md

@@ -0,0 +1,44 @@
+# Documentation structure
+
+What a repo documents, where, and how it's written. `imf-web-ui-frontend-setup` scaffolds this shape from its `templates/`
+and audits it.
+
+## The shape
+
+```
+<app>/
+  README.md            # humans: what the app is, setup, scripts
+  AGENTS.md            # agents: stack, pointers into docs/ — restates nothing
+  docs/
+    index.md           # registers every doc with a one-line "covers" summary
+    <topic>.md         # repo-unique content only
+```
+
+## Repo docs hold only what is unique to the repo
+
+The litmus, applied sentence by sentence: **would this be true in every ImFusion frontend? Then it's baseline — it lives in
+the installed skill references, don't restate it.** The baseline is already in the repo, vendored under
+`.agents/skills/imf-web-ui-frontend-conventions/`, human-readable and versioned.
+
+Where the repo deviates from the baseline, the doc says so as a **named deviation** — what the baseline prescribes, what this
+repo does instead, and why. A deviation written as freestanding convention gets copied into the next repo as if it were house
+style.
+
+## How docs are written
+
+- **Docs explain concepts; code is the source of truth for facts.** A doc captures the why — invariants, rationale,
+  decisions. It never restates a fact that lives in code (a script definition, a type shape, a config value): point at the
+  file instead. A copied fact rots the moment the code changes.
+- **State what is — no decision residue.** Positive, present-tense statements about the current state. Never narrate the
+  delta from a past decision or refute alternatives nobody raised ("there is no X mode", "Y was dropped") — that history
+  belongs in commits and tickets. A negation earns its place only as a guardrail or to preempt a wrong assumption a present
+  reader would actually arrive at.
+- **Boy Scout rule.** Discovered rot — a stale pointer, a doc contradicting the code — is always your responsibility: fix it
+  in place if trivial, otherwise report it. The two failure modes are equal: stepping over rot, and cramming unrelated
+  cleanup into an unrelated change.
+
+## Staleness at commit time
+
+Docs are checked when they can go stale: at the commit. A staged change that invalidates a doc — a renamed script, a moved
+folder, a changed flow — updates that doc **in the same commit**, not in a follow-up. Pre-commit carries the advisory
+staleness checks (vendored baseline, docs) — the mechanics are in [git.md](git.md).

package/src/llms/skills/imf-web-ui-frontend-conventions/references/git.md

@@ -0,0 +1,33 @@
+# Git
+
+## git:config
+
+One script holds the repo's git configuration, run by hand once per clone (the README names it):
+
+```
+git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only
+```
+
+Hooks live in a tracked directory; history strategy doesn't depend on personal git config. Two silent failure modes to check
+for: `git:config` never run (hooks exist only on the machine that configured by hand), and `core.hooksPath` pointing at a
+directory that doesn't exist. Config **and** directory.
+
+## Verify scopes
+
+Two blocking, one advisory:
+
+- **staged** — `verify:staged`, called by the pre-commit hook: lint, format, restage. Fast; a passing commit is not CI green.
+- **full** — `verify:full`: the build plus every `verify:*` check. What CI runs.
+- **files** — post-edit agent hook. Advisory, never exits non-zero, so a mid-flight refactor can't trap the agent.
+
+One script owns each scope's step list; npm scripts and hooks only launch them. Name by depth, not by occasion — a
+`preflight` needs explaining and invites a near-identical sibling, and two of those drift into "passes locally, fails in CI".
+
+## Staleness at commit time
+
+Pre-commit also runs the advisory staleness checks — warn, never block:
+
+- **Vendored baseline** — `.agents/hooks/imf-web-ui/baseline-staleness.sh` compares the installed `imf-web-ui-*` skill
+  markers against the installed package version; the fix it names is `npx web-ui-install`.
+- **Docs** — a staged change that invalidates a doc updates that doc in the same commit
+  ([docs-structure.md](docs-structure.md)). Where the repo has an agent commit workflow, a staged docs audit belongs in it.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/library-boundary.md

@@ -0,0 +1,37 @@
+# Library boundary
+
+The contract between an app and `@imfusion/web-ui`.
+
+## Stay behind the library
+
+Never import Base UI (or any other upstream the library wraps) directly — no upstream stylesheets, no upstream components,
+even when upstream docs show it that way. Everything a component needs ships in `@imfusion/web-ui`. If the library is missing
+something upstream has, report the gap (see `imf-web-ui-components`); don't reach around it.
+
+## Wrap primitives when the app has a reason to
+
+When the app keeps repeating something around a primitive — default props, a styling override, a composition, an
+accessibility refinement, a restriction of the API — wrap it once in an app-level dumb component and use that. The wrapper
+derives its props from the primitive (`React.ComponentProps<typeof Button>`, narrowed or extended), lives in `components/`
+like any other dumb component ([components.md](components.md)), and styles itself through the sanctioned seams — it never
+reaches into the library's internals.
+
+Two rules keep wrappers honest:
+
+- Wrap for a reason — any repeated adaptation counts. A wrapper that only renames a primitive is indirection with no payoff.
+- Components marked `experimental` in the identity index get wrapped **always**, even with nothing added yet — a breaking
+  upstream change then lands in one file instead of every call site.
+
+## Derive types, don't import them
+
+Prop types come from the components themselves: `React.ComponentProps<typeof Button>`. The library deliberately exports no
+`Props` types — don't look for them, and don't re-declare prop shapes by hand.
+
+## Integrations own their peers
+
+Components under `@imfusion/web-ui/integrations/*` depend on optional peers (e.g. `@tanstack/highlight` for `CodeHighlight`).
+Add the peer explicitly to the consumer's `package.json` — never rely on hoisting.
+
+## Styling crosses the boundary through seams
+
+Tokens in, sanctioned selectors at the edge, never the library's internals — the full contract is [styling.md](styling.md).

package/src/llms/skills/imf-web-ui-frontend-conventions/references/npm-project.md

@@ -0,0 +1,57 @@
+# npm project
+
+How the npm side of an ImFusion frontend is structured: `package.json`, scripts, dependencies. `imf-web-ui-frontend-setup`
+audits against this file.
+
+## package.json
+
+The exemplary shape:
+
+```jsonc
+{
+  "name": "@imfusion/scan-review",
+  "type": "module",
+  "private": true, // only when the package is not meant to be published
+  "engines": { "node": ">=22" },
+  "imports": { "#/*": "./src/*" }
+}
+```
+
+- `"type": "module"` always.
+- `"private": true` for apps that never publish; a publishable package drops it.
+- Node pinned via `engines.node` or `.nvmrc` — not a personal version manager's config.
+- The `#/` alias wired through `imports` ([project-structure.md](project-structure.md)).
+
+## Scripts
+
+Same name, same meaning, every repo — "what can I run to check this?" is answered by tab-completing `verify:`.
+
+| Script             | Runs                                                                  |
+| ------------------ | --------------------------------------------------------------------- |
+| `dev`              | dev server                                                            |
+| `build`            | production build                                                      |
+| `verify:deps`      | exact-pin check over `dependencies` and `devDependencies`             |
+| `verify:format`    | `prettier --check .`                                                  |
+| `verify:lint`      | `eslint . --cache --max-warnings=0`                                   |
+| `verify:typecheck` | `tsc --noEmit` (or `tsc -b --noEmit` in a project-references setup)   |
+| `verify:tests`     | `vitest run`                                                          |
+| `verify:staged`    | staged-file subset, called by the pre-commit hook                     |
+| `verify:full`      | every `verify:*` check plus the build; what CI runs                   |
+| `format`           | `prettier --write .`                                                  |
+| `lint`             | `eslint . --cache --fix`                                              |
+| `git:config`       | see [git.md](git.md); run by hand once per clone, named in the README |
+
+Two rules generate the names:
+
+- **Every check is `verify:*`.** One namespace for everything that reads and reports.
+- **Write-mode scripts keep the tool name.** `format` and `lint` change files, which isn't verifying — no prefix, no `:fix`
+  suffix.
+
+`verify:staged` is fast and partial; a passing commit is not CI green. `verify:full` is the CI gate.
+
+## Dependencies
+
+- **Pinned exactly.** No `^`, `~`, or `latest`, in `dependencies` and `devDependencies` alike. `verify:deps` catches drift;
+  `save-exact=true` in `.npmrc` prevents it.
+- **`ignore-scripts=true` in `.npmrc`.** Blocks lifecycle scripts on install (the supply-chain vector). Setup that matters is
+  a command someone runs, not a hook that fires on install.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/project-structure.md

@@ -0,0 +1,21 @@
+# Project structure
+
+Kebab-case throughout, folders and files alike. Exported symbols stay PascalCase — only the filename is kebab.
+
+```
+src/
+  routes/          # TanStack Router file-based routes; routing only — they compose, they don't fetch inline
+  api/             # one folder per API topic — layout and behaviour in data.md
+  components/      # grouped by kind — anatomy in components.md
+  http/            # transport: client, error normalisation — the only transport-aware place (data.md)
+  lib/             # framework-free helpers
+```
+
+Each subtree's own rules live with its topic: [data.md](data.md) for `api/` and `http/`, [components.md](components.md) for
+`components/`.
+
+## Imports
+
+The `#/` alias for anything outside the current folder, plain `./` for siblings. The alias is always `#/` → `src/` — `#` is
+Node's own subpath-import prefix, so it can't collide with an npm scope. Wire it once, through `package.json`'s `imports`
+field where the toolchain resolves it natively, with a matching tsconfig `paths` entry.

package/src/llms/skills/{imf-web-ui-frontend-patterns/references/react-patterns.md → imf-web-ui-frontend-conventions/references/react.md}

@@ -1,4 +1,4 @@
-# React patterns
+# React
 
 The house defaults for the React code around `@imfusion/web-ui`, in full. The links throughout are for **you, the agent**:
 consult them while building — they are the authoritative source when a case here is ambiguous. Hand them to the human only if
@@ -43,9 +43,8 @@ function UserCardContainer({ userId }: { userId: string }) {
 ```
 
 Why it matters here: dumb components are the layer where `@imfusion/web-ui` lives. Keeping them free of logic keeps every
-screen restylable, testable with plain props, and resilient to library updates. The one web-ui-specific addition: wrap
-`experimental` components (marked in the identity index) in a dumb component once per app even if you add nothing yet — a
-breaking upstream change then lands in one file instead of every call site.
+screen restylable, testable with plain props, and resilient to library updates. When and how to wrap the library's primitives
+in app-level dumb components is [library-boundary.md](library-boundary.md).
 
 ## Compose, don't configure
 
@@ -56,15 +55,18 @@ components. When state must be shared between siblings, lift it to the nearest c
 
 ## Put state where its truth lives
 
-Work down this list and stop at the first match:
+State comes in kinds, and each kind has an owner. Work down this list and stop at the first match:
 
-1. **Shareable via URL?** (filters, sort, pagination, active tab) → router search params. Back button and copied links are UX
-   features you get for free.
-2. **Comes from an API?** → the data-fetching layer's cache (e.g. TanStack Query). Never copy server data into `useState` —
-   that's how stale-UI bugs are born.
-3. **Scoped to a subtree, resets on leave?** (wizard progress) → React context.
-4. **App-wide and persistent?** → a client store, and only now.
-5. **Local to one component?** (input value, open/closed) → `useState`.
+1. **URL state** — shareable via the address bar (filters, sort, pagination, active tab) → TanStack Router search params.
+   Back button and copied links are UX features you get for free.
+2. **Server state** — comes from an API → TanStack Query's cache ([data.md](data.md)). Never copy server data into `useState`
+   — that's how stale-UI bugs are born.
+3. **Subtree state** — scoped to a subtree, resets on leave (wizard progress) → React context.
+4. **Client state** — app-wide and persistent → TanStack Store, and only now.
+5. **Local state** — one component's own (input value, open/closed) → `useState`.
+
+`useState` is the right tool for local UI state, and most state is local: whether a panel is open, which tab is active, a
+draft value being typed, a hover flag. Keep those in the component and don't reach for a library.
 
 Most frontends need far less of tier 4 than they think; tiers 1–2 usually dissolve the "we need a store" instinct. For
 structuring the state itself, [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) is the
@@ -82,6 +84,18 @@ When an effect is genuinely needed, extract it into a custom hook named for its
 hook isolates the dependency array, and the component body stays declarative. Pattern reference:
 [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks).
 
+The naming rule holds even for the rare effect that stays inline: give the callback a name, so the intent survives without a
+comment —
+
+```tsx
+useEffect(
+  function syncDocumentTitle() {
+    document.title = title;
+  },
+  [title]
+);
+```
+
 ## Reading list
 
 Consult while building; each is the authority for its topic:

package/src/llms/skills/imf-web-ui-frontend-conventions/references/stack.md

@@ -0,0 +1,39 @@
+# Stack
+
+The topic→tool map for an ImFusion frontend. Check this before adding a dependency; check the TanStack suite before adding a
+non-TanStack one.
+
+| Topic                 | Tool                                                                                                  |
+| --------------------- | ----------------------------------------------------------------------------------------------------- |
+| Build                 | [Vite](https://vite.dev)                                                                              |
+| Routing, URL state    | [TanStack Router](https://tanstack.com/router) — file-based, type-safe search params                  |
+| Server state          | [TanStack Query](https://tanstack.com/query) — the pattern around it is [data.md](data.md)            |
+| Forms                 | [TanStack Form](https://tanstack.com/form)                                                            |
+| Data grids            | [TanStack Table](https://tanstack.com/table) + web-ui's styled `Table` parts                          |
+| App-wide client state | [TanStack Store](https://tanstack.com/store) — last resort in the state ladder ([react.md](react.md)) |
+| Schema validation     | [Zod](https://zod.dev) — at the network boundary ([data.md](data.md))                                 |
+| Styling               | CSS Modules ([styling.md](styling.md))                                                                |
+| Test                  | [Vitest](https://vitest.dev)                                                                          |
+| Format                | [Prettier](https://prettier.io) — values in [tooling.md](tooling.md)                                  |
+| Lint                  | [ESLint](https://eslint.org) flat config ([tooling.md](tooling.md))                                   |
+| Types                 | `tsc --noEmit` — own script, own CI step                                                              |
+| Staged files          | [lint-staged](https://github.com/lint-staged/lint-staged) (or nano-staged, drop-in)                   |
+| Dead code             | [knip](https://knipjs.dev) — needs per-repo config                                                    |
+
+## Devtools come with the library
+
+Every TanStack library that ships a devtools package gets it as a dev dependency, mounted in development only. Router is a
+given, so `@tanstack/react-router-devtools` is a given too; Query's goes in when Query does. Look for a `-devtools` sibling
+whenever you add a TanStack dependency — the set grows, and not every library has one yet. Once a project has several,
+`@tanstack/devtools` hosts them in one panel.
+
+## When a library owns a layer
+
+A library owns the layer once you find yourself rebuilding what it does: validation timing and cross-field rules (Form),
+caching and refetching (Query), URL as the source of truth (Router), sorting and pagination over rows (Table). Adding the
+library mid-project is normal and cheap; unpicking a hand-rolled version later is not.
+
+## Docs over memory
+
+`npx @tanstack/cli` for TanStack docs — never work from memory. Where a project has wired up `@tanstack/intent`, use it to
+reach the Agent Skills its TanStack dependencies ship, and read those too.

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

@@ -0,0 +1,91 @@
+# Styling
+
+**CSS Modules with native CSS by default** — nesting and custom properties are the DRY mechanism; no Sass, no CSS-in-JS, no
+utility-class framework. Where the stylesheet lives and who owns one is [components.md](components.md).
+
+- **Nest pseudo-elements, states, and child selectors under the root** so a selector prefix is written once:
+
+  ```css
+  .root {
+    transition: clip-path var(--ease);
+    &:focus-visible {
+      outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-support);
+    }
+    &[data-disabled] {
+      opacity: 0.5;
+    }
+  }
+  ```
+
+- **Lift a repeated literal into a custom property** (an easing, a colour-math result) and reference it. Custom properties
+  also carry per-state/per-variant values down the tree — the parameterisation a mixin would provide, done natively.
+- Don't "merge" rules that only look similar. Structurally different output (three distinct `clip-path` polygons) isn't
+  repetition a mixin can remove. Keep it explicit.
+
+## Build custom UI from tokens
+
+Anything you build that the library doesn't cover — a stat widget, a custom panel — uses `--imf-ui-*` variables for color,
+spacing, radius, and type instead of hardcoded values. That's what makes custom UI look native next to library components,
+and what keeps it correct when the theme changes. A hex code or a magic `px` next to a concept the tokens already name is a
+defect.
+
+Geometry that can't be a token (a clip-path percentage, a hairline `1px`) lives in a named custom property at the top of the
+stylesheet, with the invariant written next to it. Don't silently approximate to the nearest token.
+
+## Override through the sanctioned seams
+
+All library styles live in the `imf-ui.components` CSS layer, so **any plain selector you write wins** — that's the whole
+override contract:
+
+- Target the stable hooks: `data-imf-ui-component` attributes and your own classes/wrappers.
+- Never target the library's internal class names — they are generated and change without notice.
+- Never `!important` — if you think you need it, you're targeting the wrong thing.
+- **Style against state via data attributes** (`[data-checked]`, `[data-disabled]`, `[data-popup-open]`) — components expose
+  their state there, so you never maintain your own state classes. `className` is purely a styling surface:
+
+  ```css
+  [data-imf-ui-component="Switch"][data-checked] {
+    outline: 2px solid var(--imf-ui-color-bg-positive);
+  }
+  ```
+
+## The color system
+
+The color roles you can name: **surfaces** (`main` the canvas, `support` panels, `minor` popovers), **brand** (identity, full
+saturation) vs **primary** (contrast-tuned, CTAs — distinct roles on purpose), **status** (`negative`, `warning`, `positive`,
+`info`), and three **accent** slots.
+
+Two layers:
+
+- **Controls** are the 80/20 customization surface — override one and every derived token shifts:
+
+  ```css
+  :root {
+    --imf-ui-color-primary-hue: 30; /* every primary semantic token follows */
+  }
+  ```
+
+- **Semantic tokens** are what you consume in your own CSS: `--imf-ui-color-bg-{name}` per role, a flat
+  `--imf-ui-color-fg-{main|support|minor|oncolor|…}` ladder for text. Borders and rings draw from the `fg-*` space.
+
+Rules of thumb: if you push a hue control into a pale corner, you own overriding the matching `fg-*` token; the color scheme
+is `<html data-imf-ui-color-scheme="light|dark">` (the provider sets it) — scheme-specific styling selects via that
+attribute.
+
+## Responsive styling
+
+- **Tune components per breakpoint by overriding their `--imf-ui-*` variables inside your own media queries** — custom
+  properties cross the `@media` boundary, props don't. That's why components expose sizing as variables instead of a `width`
+  prop:
+
+  ```css
+  @media (min-width: 768px) {
+    .my-shell {
+      --imf-ui-appshell-navbar-width: 22rem;
+    }
+  }
+  ```
+
+- **Write literal breakpoint values.** The library's `@custom-media` aliases are build-internal and don't ship.
+- **JS only for behaviour** (render a burger menu on mobile): `useMediaQuery(minWidth("md"))`. Never for styling CSS can do.
+- **No responsive props.** `size={{ sm: … }}` objects are deliberately not offered — write the media query.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/testing.md

@@ -0,0 +1,16 @@
+# Testing
+
+Test the **decisions**, not the rendering.
+
+- **Pure logic gets unit tests** — pricing, permissions, date math, parsing, reducers. These are cheap, fast, and the place
+  bugs actually hide.
+- **Presentational components generally don't.** A component that maps props onto web-ui primitives has no logic of its own;
+  asserting that it rendered a `<Button>` tests React, not your code.
+- **Behaviour a user performs gets an interaction test** — a form that validates, a flow with steps. Test it through the
+  interface the user has (roles, labels, visible text), not through internals.
+- **Extract the decision out of a hook and test that.** A hook whose interesting part is a plain function is easier to test
+  as a plain function than through a render harness. A hook that only wraps a browser API has no decision to extract.
+
+The data layer has its own recipe — stub `fetch`, run the real query client — in [data.md](data.md).
+
+The measure isn't coverage percentage. It's whether a test failing tells you something you didn't already know.