@imfusion/web-ui 0.6.1-dev.27.gfc6e5abb → 0.6.1-dev.3.g5b432448

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

@@ -1,30 +1,26 @@
 # Library setup
 
-Wire `@imfusion/web-ui` at the app entry point. The setup skill can propose a fix; the audit skill can check it.
+Library wiring (styles import + `WebUIProvider`) for anyone using `@imfusion/web-ui` — `imf-web-ui-setup library-setup`
+proposes a bootstrap change, `imf-web-ui-audit library-setup` is the read-only health check.
 
 ## Entry-point wiring
 
-Import the stylesheet before the components and mount `WebUIProvider` once around the app:
+- Every consumer entry point has exactly two lines, in this order:
 
-```tsx
-import "@imfusion/web-ui/styles.css";
-import { Button, WebUIProvider } from "@imfusion/web-ui";
+  ```tsx
+  import "@imfusion/web-ui/styles.css";
+  import { WebUIProvider, Button } from "@imfusion/web-ui";
+  ```
 
-export function App() {
-  return (
-    <WebUIProvider>
-      <Button>Save</Button>
-    </WebUIProvider>
-  );
-}
-```
-
-Components outside the provider do not receive the library's provider context. Keep upstream imports behind the library; see
-[library-boundary.md](library-boundary.md).
+- Wrap the app root in `<WebUIProvider>` once — components rendered outside it lack the theme and CSS-variable context they
+  expect.
+- Never import a Base UI (or other upstream) stylesheet or component directly — everything a web-ui component needs is inside
+  `styles.css` and the package's own exports. What may be reached for when the library lacks a component:
+  [library boundary](library-boundary.md).
 
 ## Symptoms of broken setup
 
-- Unstyled components usually mean the `styles.css` import is missing.
-- Wrong colors or unresolved variables usually mean the component is outside `WebUIProvider`.
-- An integration import error usually means its optional peer is missing. Check the component entry in
-  `imf-web-ui-components` for the package to install.
+- Components render but look unstyled → the `styles.css` import is missing from the entry point.
+- Components render but ignore the theme (wrong colors, CSS variables not resolving) → mounted outside `<WebUIProvider>`.
+- An integration component throws on import → its optional peer dependency is not installed; check the component's
+  description in the docgen index (`imf-web-ui-components`) for which peer to add to `package.json`.

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

@@ -1,39 +1,53 @@
 # npm project
 
-Keep project metadata, scripts, and dependency policy in `package.json` and the lockfile.
+The npm side of an ImFusion frontend: `package.json`, scripts, dependencies. `imf-web-ui-setup` audits against this file.
 
 ## package.json
 
-- Use ESM with `"type": "module"`.
-- Set the Node floor with `engines.node` or `.nvmrc`.
-- Use the `#/` source alias when the project has one, and wire it through the package `imports` field.
-- Set `private: true` only for packages that are never published.
+```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` only for apps that never publish.
+- Pin Node via `engines.node` or `.nvmrc` — never a personal version manager's config.
+- Wire the `#/` alias through `imports` ([project-structure.md](project-structure.md)).
 
 ## Scripts
 
-Use the same names for the same checks where the project supports them:
-
-| Script             | Purpose                                 |
-| ------------------ | --------------------------------------- |
-| `dev`              | Start local development.                |
-| `build`            | Create a production build.              |
-| `verify:format`    | Check Prettier.                         |
-| `verify:lint`      | Check ESLint.                           |
-| `verify:typecheck` | Run TypeScript without emitting.        |
-| `verify:tests`     | Run tests once.                         |
-| `verify:knip`      | Check dead code and unused exports.     |
-| `verify:staged`    | Run the pre-commit scope.               |
-| `verify:full`      | Run the CI scope.                       |
-| `format`           | Rewrite formatting.                     |
-| `lint`             | Rewrite fixable lint issues.            |
-| `git:config`       | Apply the repository Git configuration. |
-
-Read the repository's actual `package.json` before running a command. A project may not have every script in the table.
+Same name, same meaning, every repo — "what can I run to check this?" is 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:knip`      | `knip` — dead-code and unused-export check                            |
+| `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 |
+
+- **Every check is `verify:*`** — one namespace for everything that reads and reports.
+- **Write-mode scripts keep the tool name** (`format`, `lint`): changing files isn't verifying — no prefix, no `:fix` suffix.
+- `verify:staged` is fast and partial: staged-file format/lint plus the relevant project-wide checks for staged source or
+  config changes, including `verify:knip` — a passing commit is not CI green.
+- `verify:full` is the CI gate.
 
 ## Dependencies
 
-Pin dependencies exactly. Avoid `^`, `~`, and `latest` in runtime and development dependencies. Set `save-exact=true` in
-`.npmrc` so new installs follow the same rule.
-
-Use `ignore-scripts=true` in `.npmrc` when the project relies on explicit setup commands rather than install-time lifecycle
-scripts.
+- **Pin 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-conventions/topics/project-structure.md

@@ -1,42 +1,44 @@
 # Project structure
 
-Use kebab-case for folders and files. Exported symbols use PascalCase.
+Kebab-case throughout, folders and files alike; exported symbols stay PascalCase — only the filename is kebab.
 
 ## Layout
 
-```text
+```
 src/
-  main.tsx
-  routes/
-    __root.tsx
-    _public/route.tsx
-    _app/route.tsx
-  api/
-  http/
-  lib/
-  components/
+  main.tsx         # providers and router bootstrap; one WebUIProvider at the app root
+  routes/          # TanStack Router file-based routes; routing only — they compose, they don't fetch inline
+    __root.tsx     # document-wide error/not-found boundary and Outlet
+    _public/       # anonymous route group; resolves the current user when public pages need it
+      route.tsx
+    _app/          # pathless authenticated route group; guards the subtree before children render
+      route.tsx
+  api/             # one folder per API topic — layout and behaviour in data.md
+    auth/           # one current-user query plus server-owned login/logout URL helpers
+  components/      # grouped by kind — anatomy in components.md
+    app-shell/     # optional persistent authenticated chrome: brand, navigation, and session action
+  http/            # transport: client, error normalisation — the only transport-aware place (data.md)
+  lib/             # framework-free helpers, each with a colocated .test.ts when it has decisions to test
+    auth/
+      login-url.ts
+      login-url.test.ts
 ```
 
-`main.tsx` owns providers and router setup. Routes compose pages and their route data; API topics own data options and
-schemas; `http/` owns transport; `lib/` holds framework-free helpers; `components/` holds UI.
-
-The authenticated route group may contain the persistent `AppShell`. The full data layout is in [data.md](data.md), and
-component folders are in [components.md](components.md).
+- Each subtree's rules live with its topic: [data.md](data.md) for `api/` and `http/`, [components.md](components.md) for
+  `components/`.
 
 ## Application boundary
 
-Create the root providers, current-user boundary, and pathless `_public/` and `_app/` groups before adding feature routes. A
-new app starts `_app/` with a minimal `AppShell` unless it has no persistent authenticated navigation. An established app
-keeps its working shell choice.
+- Start every frontend with the root providers, a current-user query, and pathless `_public/` and `_app/` route groups —
+  contract in [authentication.md](authentication.md); add feature routes only after that boundary exists.
+- Greenfield: `_app/` starts with a minimal `AppShell` — ImFusion logo, route navigation, and a stable session-action area
+  around the route `Outlet`.
+- Omit the shell only when the human explicitly says the product has no persistent authenticated navigation; the `_app/`
+  guard stays.
+- An established project preserves its working choice; public pages can use a small branded header instead.
 
 ## Imports
 
-Use `./` for siblings and `#/` for imports elsewhere in `src/`:
-
-```ts
-import { Button } from "#/components/button";
-import { formatDate } from "./format-date";
-```
-
-Wire `#/` once through `package.json`'s `imports` field and the matching TypeScript paths. It uses Node's `#` subpath prefix,
-so it cannot conflict with an npm package scope.
+- `#/` 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 (toolchain-native), with a matching tsconfig `paths` entry.

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

@@ -1,52 +1,90 @@
 # React
 
-Keep data flow one-way and components focused. Pages decide how data is loaded; presentational components decide how it
-looks.
+House defaults for React around `@imfusion/web-ui`. Links are for you, the agent — authoritative when a case here is
+ambiguous; hand them to the human only if asked.
 
 ## Composition: pages (smart containers), partials, dumb components
 
-- **Pages** live in `routes/`. They load data, read URL state, coordinate actions, and compose the view. They do not own
-  component CSS.
-- **Partials** are reusable compositions extracted because they read as a unit. They have light logic and no styling of their
-  own.
-- **Layout components** arrange content with `Stack`, `Row`, grids, and token gaps.
-- **Dumb components** receive data and callbacks, render UI, and own their styles. They do not fetch, route, or contain
-  business rules.
+The architecture principle, top-down — rooted in Dan Abramov's
+[Presentational and Container Components](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) and
+[Thinking in React](https://react.dev/learn/thinking-in-react). Styling lives exclusively in dumb and layout components,
+nowhere else:
+
+- **Pages are the smart containers.** The route component in `routes/` is the container — don't go looking for `*Container`
+  files. It owns how things _work_: loaders prefetch, the component fetches data, orchestrates, composes partials and passes
+  data down. Zero styling — a page wanting CSS (two panels side by side) means a layout component, not an inline style. A
+  standalone container earns its place only off-route (a modal fetching its own data).
+- **Partials** are pure composition: reusable units of dumb and layout components with light logic and zero styling of their
+  own, extracted because they read as a unit. A partial with a CSS file is a red flag — the styled element wants to be its
+  own dumb component, or the wrapper wants to be a layout component.
+- **Layout components** own _arrangement_ and nothing else: `Stack`-/`Row`-based wrappers with token gaps, a page grid, a
+  section frame.
+- **Dumb components** own how things _look_: style and compose library primitives, take plain data and callbacks as props; no
+  fetching, routing, or business logic. All non-layout styling lives here and only here — logic-free dumb components (the
+  `@imfusion/web-ui` layer) keep screens restylable, testable with plain props, resilient to library updates.
+- Wrapping library primitives in app-level dumb components: [library-boundary.md](library-boundary.md).
 
 ```tsx
-function UserCard({ name, onEdit }: { name: string; onEdit: () => void }) {
+// Dumb — renders what it's given
+function UserCard({ name, role, onEdit }: { name: string; role: string; onEdit: () => void }) {
   return (
     <Card.Root>
-      <Typo.P>{name}</Typo.P>
-      <Button onClick={onEdit}>Edit</Button>
+      <Card.Content>
+        <Typo>{name}</Typo>
+        <Chip>{role}</Chip>
+      </Card.Content>
+      <Card.Footer>
+        <Button onClick={onEdit}>Edit</Button>
+      </Card.Footer>
     </Card.Root>
   );
 }
 ```
 
+```tsx
+// Smart — knows where data comes from, renders the dumb component
+function UserCardContainer({ userId }: { userId: string }) {
+  const user = useUserQuery(userId);
+  const openEditor = useEditorNavigation(userId);
+  return <UserCard name={user.data.name} role={user.data.role} onEdit={openEditor} />;
+}
+```
+
 ## Compose, don't configure
 
-Compose small parts instead of making one component configurable through many boolean props. Lift shared state to the nearest
-common parent.
+- Build screen-level pieces by composing primitives (`Stack`, `Row`, `Card`, dumb components), not one component with a dozen
+  boolean props — a prop list that reads like a settings page wanted to be two or three components.
+- Lift state shared between siblings to the nearest common parent
+  ([Sharing State Between Components](https://react.dev/learn/sharing-state-between-components)); never sync copies.
 
 ## Put state where its truth lives
 
-Choose the first suitable level:
+Work down this list; stop at the first match:
 
-1. **URL state**: filters, sort, pagination, and active tab. Use TanStack Router search params and validate them.
-2. **Server state**: API data. Use TanStack Query; do not copy it into `useState`.
-3. **Subtree state**: state shared by a subtree and reset when it leaves. Use React context.
-4. **Client state**: app-wide persistent state. Use TanStack Store only when the earlier levels do not fit.
-5. **Local state**: one component's open state, draft, or input value. Use `useState`.
+1. **URL state** — shareable via the address bar (filters, sort, pagination, active tab) → TanStack Router search params;
+   back button and copied links come free. These cross an external boundary — parse per [validation.md](validation.md).
+2. **Server state** — from an API → TanStack Query's cache ([data.md](data.md)); never copy it into `useState` — that's how
+   stale-UI bugs are born.
+3. **Subtree state** — resets on leave (wizard progress) → React context.
+4. **Client state** — app-wide and persistent → TanStack Store, and only now: tiers 1–2 usually dissolve the "we need a
+   store" instinct.
+5. **Local state** — one component's own (input value, open/closed, a draft, a hover flag) → `useState`. Most state is local;
+   keep it in the component, no library.
 
-Shape state so it is not redundant or duplicated. Validate a form draft when it becomes a submitted domain value.
+- A form turning drafts into a submitted domain value validates that boundary per [validation.md](validation.md).
+- Shape the state itself per [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) —
+  especially its rules on redundant and duplicated state.
 
 ## Effects: last resort, and named
 
-Use `useEffect` only to synchronize with something outside React. Do not use it for derived values, event responses, or
-server sync.
-
-A genuine effect belongs in a named custom hook. If it stays inline, name the callback:
+- No `useEffect` for: derived values (render or `useMemo`), responses to user actions (the event handler), server sync (the
+  data-fetching layer). Effects only synchronize with systems _outside_ React.
+- Read [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) — the definitive misuse catalog —
+  before every effect you're tempted to write.
+- Extract a genuine effect into a custom hook named for its purpose (`useSyncedScroll`, `useDocumentTitle`, `useHotkey`),
+  never an anonymous inline `useEffect`: the name documents intent, the hook isolates the dependency array. Pattern:
+  [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks).
+- The rare effect that stays inline still names its callback, so intent survives without a comment:
 
 ```tsx
 useEffect(
@@ -57,7 +95,15 @@ useEffect(
 );
 ```
 
-Destructure a primitive before putting it in an effect dependency array. Keep the returned query or route object intact
-elsewhere so its namespace remains visible.
+- A dependency sourced from a hook or query return: destructure the primitive first — [typescript.md](typescript.md#naming).
+
+## Reading list
+
+Consult while building; each is the authority for its topic:
 
-Read the React documentation when a decomposition or effect decision is unclear.
+- [Thinking in React](https://react.dev/learn/thinking-in-react) — decomposition and one-way data flow
+- [Keeping Components Pure](https://react.dev/learn/keeping-components-pure) — why dumb components stay dumb
+- [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) — shaping state without duplication
+- [Sharing State Between Components](https://react.dev/learn/sharing-state-between-components) — lifting state
+- [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) — the effect misuse catalog
+- [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) — named effects live here

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

@@ -1,91 +1,88 @@
 # Styling
 
-Use native CSS and Web UI's public seams. The library's CSS Modules and token names are not consumer implementation details.
+How app CSS is written and how it meets `@imfusion/web-ui`.
 
 ## CSS authoring
 
-- 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.
-- 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.
+- **CSS Modules with native CSS only** — no Sass, no CSS-in-JS, no utility-class framework: nesting and custom properties
+  already cover DRY. Stylesheet location and ownership: [components.md](components.md).
+- Nest pseudo-elements, states, and child selectors under the root so the prefix is written once:
 
-```css
-.root {
-  transition: opacity var(--imf-ui-duration-quick-2) var(--imf-ui-ease-2);
+  ```css
+  .root {
+    transition: clip-path var(--ease);
 
-  &:focus-visible {
-    outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-primary);
-  }
+    &:focus-visible {
+      outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-support);
+    }
 
-  &[data-disabled] {
-    opacity: 0.5;
+    &[data-disabled] {
+      opacity: 0.5;
+    }
   }
-}
-```
+  ```
 
-## Build custom UI from tokens
+- Lift a repeated literal (an easing, a colour-math result) into a custom property; custom properties also carry
+  per-state/per-variant values down the tree — native parameterisation, no mixin needed.
+- Don't merge rules that only look similar — structurally different output (three distinct `clip-path` polygons) isn't
+  repetition; keep it explicit.
 
-Use names from the shipped token index for colors, type, size, radius, and shadow. A literal beside a tokenized concept is a
-defect. Keep a literal only when no token represents it, such as a hairline or a clip-path percentage; give that literal a
-named custom property when it is part of the component's design.
+## Build custom UI from tokens
 
-Read exact token names from `node_modules/@imfusion/web-ui/src/llms/tokens.gen.json`. Do not invent or copy a token list into
-a consumer project.
+- Custom UI the library doesn't cover (a stat widget, a custom panel) uses names from the shipped token index
+  ([tokens.md](tokens.md)) for color, size, radius, and type — that's what makes it look native and survive 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`) → named custom property at the top of the
+  stylesheet, invariant written next to it. Don't silently approximate to the nearest token.
 
 ## Override through the sanctioned seams
 
-Library component styles are in `@layer imf-ui.components`. Consumer CSS outside a layer wins. Target:
-
-- your own class or wrapper;
-- `data-imf-ui-component` for component identity;
-- the component's documented state attributes.
-
-Do not target generated CSS Module class names and do not use `!important` to fight the cascade. `className` is a styling
-hook, not a state flag.
-
-```css
-[data-imf-ui-component="Switch"][data-checked] {
-  outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-positive);
-}
-```
+- 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` — needing it means you're targeting the wrong thing.
+- Style against state via data attributes (`[data-checked]`, `[data-disabled]`, `[data-popup-open]`) — components expose
+  state there, so 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
 
-Use surface roles (`main`, `support`, `minor`), the separate `brand` and `primary` roles, status roles, and the three accent
-slots. Override a high-level control when a whole family should change; consume a semantic token in a component.
-
-Foreground roles are for text, icons, borders, and focus rings. Background roles are for fills. The provider sets
-`data-imf-ui-color-scheme="light" | "dark"` on `<html>`.
-
-## Browser floor
+- Roles: **surfaces** (`main` canvas, `support` panels, `minor` popovers); **brand** (identity, full saturation) vs
+  **primary** (contrast-tuned, CTAs) — distinct roles on purpose; **status** (`negative`, `warning`, `positive`, `info`);
+  three **accent** slots.
+- **Controls** are the 80/20 customization surface — override one and every derived token shifts:
 
-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:
-
-```css
-.subtle {
-  background: color-mix(in oklch, var(--chip-bg) 15%, transparent);
-}
-
-@supports (color: oklch(from red l c h)) {
-  .subtle {
-    background: oklch(from var(--chip-bg) l c h / 0.15);
+  ```css
+  :root {
+    --imf-ui-color-primary-hue: 30; /* every primary semantic token follows */
   }
-}
-```
+  ```
+
+- **Semantic tokens** are what you consume: `--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 `fg-*`.
+- Push a hue control into a pale corner → you own overriding the matching `fg-*` token.
+- Color scheme is `<html data-imf-ui-color-scheme="light|dark">`, set by the provider; scheme-specific styling selects via
+  that attribute.
 
 ## Responsive styling
 
-Override component variables inside your own media queries:
+- Tune components per breakpoint by overriding their `--imf-ui-*` variables inside your own media queries — custom properties
+  cross the `@media` boundary, props don't (why sizing is variables, not a `width` prop):
 
-```css
-@media (min-width: 768px) {
-  .shell {
-    --imf-ui-appshell-navbar-width: 22rem;
+  ```css
+  @media (min-width: 768px) {
+    .my-shell {
+      --imf-ui-appshell-navbar-width: 22rem;
+    }
   }
-}
-```
+  ```
 
-Use literal breakpoint values in consumer CSS; the library's `@custom-media` aliases are build-time only. Use
-`useMediaQuery(minWidth("md"))` for JavaScript behavior, not for styling.
+- 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-conventions/topics/testing.md

@@ -1,23 +1,25 @@
 # Testing
 
-Test decisions and user behavior, not framework behavior.
+Test the **decisions**, not the rendering.
 
 ## Naming
 
-Colocate tests and name them `*.test.ts` or `*.test.tsx`.
+- Colocated tests use `.test.ts` / `.test.tsx` (e.g. `login-url.test.ts`) — not `.spec.*` or plural `.tests.*`.
 
 ## What gets a test
 
-- Unit-test pure logic such as parsing, permissions, reducers, and date or token calculations.
-- Use an interaction test for behavior a user performs and a static story cannot show.
-- Do not test a presentational component that only maps props onto Web UI or HTML.
-- Extract a hook's decision into a pure function and test that function. A hook that only wraps a browser API has no decision
-  to test.
-
-A useful test answers something a reader could not know just by reading the implementation. Coverage percentage is not the
-goal.
+- **Pure logic gets unit tests** — pricing, permissions, date math, parsing, reducers: cheap, fast, and where bugs actually
+  hide.
+- **Presentational components generally don't**: a component mapping props onto web-ui primitives has no logic of its own —
+  asserting a `<Button>` rendered tests React, not your code.
+- **Behaviour a user performs gets an interaction test** — a validating form, a stepped flow — through the interface the user
+  has (roles, labels, visible text), not through internals.
+- **Extract the decision out of a hook and test it as a plain function** — easier than a render harness; a hook that only
+  wraps a browser API has no decision to extract.
+- The measure isn't coverage percentage — it's whether a failing test tells you something you didn't already know.
 
 ## Layer-specific recipes
 
-For the data layer, stub `fetch` at the transport boundary and run the real query client. For schemas, test accepted,
-rejected, and transformed values when the schema encodes product behavior. Keep both tests next to their source.
+- Data layer: stub `fetch`, run the real query client — the recipe is in [data.md](data.md).
+- A schema whose constraints or transforms encode product behavior gets focused accepted, rejected, and transformed cases:
+  [validation.md](validation.md).

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

@@ -1,12 +1,7 @@
 # Tokens
 
-Use the generated token index when choosing a Web UI token.
+## Token index
 
-Read:
-
-```text
-node_modules/@imfusion/web-ui/src/llms/tokens.gen.json
-```
-
-It contains the shipped token names and authored defaults. Look up the exact entry instead of guessing a plausible
-`--imf-ui-*` name or copying a token list into the project.
+- `@imfusion/web-ui` ships the generated token index at `node_modules/@imfusion/web-ui/src/llms/tokens.gen.json` — the only
+  source for consumer token names and authored default values.
+- Look up the exact entry there; never invent, recall, or duplicate a plausible `--imf-ui-*` name.