@imfusion/web-ui 0.5.1-dev.18.g81350f83 → 0.5.1-dev.2.g0a349a2a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +43 -122
  2. package/bin/install-skill.js +180 -0
  3. package/dist/components/logo/logo.d.ts +1 -1
  4. package/dist/index.js +2 -4
  5. package/dist/style.css +1 -1
  6. package/package.json +24 -34
  7. package/src/docgen/doc.gen.json +1 -1
  8. package/src/llms/skills/imf-web-ui/SKILL.md +11 -15
  9. package/src/llms/skills/imf-web-ui-components/SKILL.md +1 -1
  10. package/src/llms/skills/imf-web-ui-frontend-patterns/SKILL.md +93 -0
  11. package/src/llms/skills/imf-web-ui-frontend-patterns/references/code-conventions.md +133 -0
  12. package/src/llms/skills/{imf-web-ui-frontend-conventions/references/react.md → imf-web-ui-frontend-patterns/references/react-patterns.md} +12 -26
  13. package/src/llms/skills/imf-web-ui-imfusion-frontend-setup/SKILL.md +201 -0
  14. package/src/llms/skills/imf-web-ui-setup/SKILL.md +57 -0
  15. package/src/llms/skills/imf-web-ui-ux/SKILL.md +4 -4
  16. package/src/llms/skills/imf-web-ui-ux/references/forms.md +1 -1
  17. package/bin/install.js +0 -319
  18. package/bin/install.test.ts +0 -139
  19. package/dist/build/vite-css-module-names/index.d.ts +0 -20
  20. package/dist/build/vite-css-module-names.js +0 -17
  21. package/src/llms/skills/imf-web-ui-agent-setup/SKILL.md +0 -71
  22. package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/baseline-staleness.sh +0 -17
  23. package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/post-tool-use.sh +0 -21
  24. package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/session-start.sh +0 -4
  25. package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/user-prompt-submit.sh +0 -4
  26. package/src/llms/skills/imf-web-ui-agent-setup/templates/settings.json +0 -37
  27. package/src/llms/skills/imf-web-ui-frontend-conventions/SKILL.md +0 -45
  28. package/src/llms/skills/imf-web-ui-frontend-conventions/references/assets.md +0 -23
  29. package/src/llms/skills/imf-web-ui-frontend-conventions/references/class-names.md +0 -42
  30. package/src/llms/skills/imf-web-ui-frontend-conventions/references/components.md +0 -63
  31. package/src/llms/skills/imf-web-ui-frontend-conventions/references/data.md +0 -130
  32. package/src/llms/skills/imf-web-ui-frontend-conventions/references/docs-structure.md +0 -44
  33. package/src/llms/skills/imf-web-ui-frontend-conventions/references/git.md +0 -33
  34. package/src/llms/skills/imf-web-ui-frontend-conventions/references/library-boundary.md +0 -37
  35. package/src/llms/skills/imf-web-ui-frontend-conventions/references/npm-project.md +0 -57
  36. package/src/llms/skills/imf-web-ui-frontend-conventions/references/project-structure.md +0 -21
  37. package/src/llms/skills/imf-web-ui-frontend-conventions/references/stack.md +0 -39
  38. package/src/llms/skills/imf-web-ui-frontend-conventions/references/styling.md +0 -91
  39. package/src/llms/skills/imf-web-ui-frontend-conventions/references/testing.md +0 -16
  40. package/src/llms/skills/imf-web-ui-frontend-conventions/references/tooling.md +0 -76
  41. package/src/llms/skills/imf-web-ui-frontend-conventions/references/typescript.md +0 -45
  42. package/src/llms/skills/imf-web-ui-frontend-setup/SKILL.md +0 -89
  43. package/src/llms/skills/imf-web-ui-frontend-setup/templates/AGENTS.md +0 -34
  44. package/src/llms/skills/imf-web-ui-frontend-setup/templates/README.md +0 -27
  45. package/src/llms/skills/imf-web-ui-library-setup/SKILL.md +0 -36
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@imfusion/web-ui",
3
- "version": "0.5.1-dev.18.g81350f83",
3
+ "version": "0.5.1-dev.2.g0a349a2a",
4
4
  "description": "The official Web UI component library for ImFusion web apps",
5
5
  "author": "ImFusion GmbH",
6
6
  "license": "UNLICENSED",
@@ -9,17 +9,10 @@
9
9
  "access": "restricted"
10
10
  },
11
11
  "type": "module",
12
- "engines": {
13
- "node": ">=24"
14
- },
15
- "imports": {
16
- "#/*": "./src/*",
17
- "#/storybook/*": "./.storybook/*"
18
- },
19
12
  "module": "./dist/index.js",
20
13
  "types": "./dist/index.d.ts",
21
14
  "bin": {
22
- "web-ui-install": "bin/install.js"
15
+ "web-ui-install-skills": "./bin/install-skill.js"
23
16
  },
24
17
  "exports": {
25
18
  ".": {
@@ -30,10 +23,6 @@
30
23
  "types": "./dist/integrations/*/index.d.ts",
31
24
  "import": "./dist/integrations/*.js"
32
25
  },
33
- "./build/*": {
34
- "types": "./dist/build/*/index.d.ts",
35
- "import": "./dist/build/*.js"
36
- },
37
26
  "./styles.css": "./dist/style.css",
38
27
  "./docgen.json": "./src/docgen/doc.gen.json",
39
28
  "./llms.txt": "./src/llms/llms.gen.txt",
@@ -47,35 +36,37 @@
47
36
  "bin"
48
37
  ],
49
38
  "scripts": {
39
+ "codegen:docgen": "tsx src/docgen/gen-docgen.ts",
40
+ "codegen:llms": "tsx src/llms/gen-llms.ts",
41
+ "codegen:watch": "tsx watch src/codegen/run.ts",
42
+ "codegen:storybook": "tsx src/codegen/run.ts --storybook",
43
+ "codegen": "tsx src/codegen/run.ts",
44
+ "build": "npm run codegen && rm -rf dist && vite build && npm run codegen:docgen && npm run codegen:llms",
50
45
  "dev": "tsx scripts/dev.ts",
51
46
  "dev:host": "tsx scripts/dev.ts --host",
52
47
  "dev:lib": "concurrently -n codegen,lib -c yellow,blue \"npm run codegen:watch\" \"vite build --watch\"",
53
- "build": "npm run codegen && rm -rf dist && vite build && npm run codegen:docgen && npm run codegen:llms",
54
- "build:storybook": "npm run codegen:storybook && storybook build",
55
- "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open",
56
- "storybook:free-ports": "tsx scripts/free-storybook-ports.ts",
57
- "codegen": "tsx src/codegen/run.ts",
58
- "codegen:watch": "tsx watch src/codegen/run.ts",
59
- "codegen:storybook": "tsx src/codegen/run.ts --storybook",
60
- "codegen:docgen": "tsx src/docgen/gen-docgen.ts",
61
- "codegen:llms": "tsx src/llms/gen-llms.ts",
62
- "verify:format": "prettier --check .",
63
- "verify:lint": "eslint . --cache --max-warnings=0",
64
- "verify:typecheck": "npm run codegen && tsc -p tsconfig.lib.json --noEmit && tsc -p .storybook/tsconfig.json --noEmit",
65
- "verify:tests": "vitest run",
66
- "verify:deps": "tsx scripts/check-pinned-dependencies.ts",
67
- "verify:staged": "tsx scripts/verify/staged.ts",
68
- "verify:full": "tsx scripts/verify/full.ts && npm run verify:tests",
48
+ "typecheck": "npm run codegen && tsc -p tsconfig.lib.json --noEmit && tsc -p .storybook/tsconfig.json --noEmit",
69
49
  "format": "prettier --write .",
70
- "lint": "eslint . --cache --fix",
50
+ "format:check": "prettier --check .",
51
+ "lint": "eslint . --cache --max-warnings=0",
52
+ "lint:fix": "eslint . --cache --fix",
71
53
  "lint:inspect": "npx @eslint/config-inspector@latest",
72
- "test:unit": "vitest run --project unit",
73
- "test:stories": "vitest run --project storybook",
74
- "test:watch": "vitest",
75
54
  "skills:eval": "node src/llms/evals/run.mjs",
76
55
  "skills:eval:dev": "WEB_UI_SKILL_EVAL_ROOT=/private/tmp/web-ui-dev-skill-evals WEB_UI_SKILL_EVAL_RESULTS_DIR=.agents/evals/results WEB_UI_SKILL_EVAL_REPORT_PATH=.agents/evals/REPORT.md WEB_UI_SKILL_EVAL_SKILL_FAMILY=web-ui-dev WEB_UI_SKILL_EVAL_WORKSPACE_LABEL='development repository' node src/llms/evals/run.mjs --scenarios-dir .agents/evals/scenarios --setup .agents/evals/setup-env.sh",
77
56
  "skills:eval:compare": "node src/llms/evals/compare.mjs",
78
57
  "skills:eval:report": "node src/llms/evals/report.mjs",
58
+ "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open",
59
+ "storybook:free-ports": "tsx scripts/free-storybook-ports.ts",
60
+ "build:storybook": "npm run codegen:storybook && storybook build",
61
+ "test": "vitest run",
62
+ "test:unit": "vitest run --project unit",
63
+ "test:stories": "vitest run --project storybook",
64
+ "test:watch": "vitest",
65
+ "verify:preflight": "tsx scripts/verify/full.ts",
66
+ "verify:full": "npm run verify:preflight && npm run test",
67
+ "worktree:create": "tsx scripts/worktrees.ts create",
68
+ "worktree:close": "tsx scripts/worktrees.ts close",
69
+ "worktree:discard": "tsx scripts/worktrees.ts discard",
79
70
  "knip": "knip",
80
71
  "git:config": "git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only"
81
72
  },
@@ -133,7 +124,6 @@
133
124
  "globals": "15.15.0",
134
125
  "jiti": "2.7.0",
135
126
  "knip": "6.14.2",
136
- "lightningcss": "1.32.0",
137
127
  "nano-staged": "1.0.2",
138
128
  "playwright": "1.60.0",
139
129
  "prettier": "3.8.3",
@@ -1281,7 +1281,7 @@
1281
1281
  {
1282
1282
  "name": "variant",
1283
1283
  "required": false,
1284
- "type": "| \"inherit\"\n| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"oncolor\"\n| null",
1284
+ "type": "| \"inherit\"\n| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| null",
1285
1285
  "defaultValue": "brand",
1286
1286
  "description": ""
1287
1287
  }
@@ -2,8 +2,8 @@
2
2
  name: imf-web-ui
3
3
  description:
4
4
  "Entry point for UI work in a project that depends on @imfusion/web-ui. Decides whether guidance is needed at all, then
5
- routes to the right companion skill — component reference, UX guidance, or frontend conventions. Load when adding or
6
- editing UI in a consumer repo."
5
+ routes to the right companion skill — component reference, UX guidance, or frontend patterns. Load when adding or editing
6
+ UI in a consumer repo."
7
7
  ---
8
8
 
9
9
  # imf-web-ui
@@ -24,17 +24,16 @@ Guidance skills exist to fill gaps, not to add ceremony to clear tasks.
24
24
 
25
25
  ## Routing
26
26
 
27
- | The task at hand | Open |
28
- | --------------------------------------------------------------------------------------------------------- | --------------------------------- |
29
- | Using a specific component; checking props, sub-components, or defaults | `imf-web-ui-components` |
30
- | First-time setup, adding a library dependency, or components rendering unstyled/broken | `imf-web-ui-library-setup` |
31
- | Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states | `imf-web-ui-ux` |
32
- | Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing | `imf-web-ui-frontend-conventions` |
33
- | Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure | `imf-web-ui-frontend-setup` |
34
- | Setting up or refreshing agent tooling: vendored skills, lifecycle hooks, dependency-shipped Agent Skills | `imf-web-ui-agent-setup` |
27
+ | The task at hand | Open |
28
+ | ----------------------------------------------------------------------------------------------------- | ------------------------------------ |
29
+ | Using a specific component; checking props, sub-components, or defaults | `imf-web-ui-components` |
30
+ | First-time setup, adding a library dependency, or components rendering unstyled/broken | `imf-web-ui-setup` |
31
+ | Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states | `imf-web-ui-ux` |
32
+ | Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing | `imf-web-ui-frontend-patterns` |
33
+ | Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure | `imf-web-ui-imfusion-frontend-setup` |
35
34
 
36
- The two setup rows are narrow on purpose. They're for "what is this project missing?" — a question about the repo as a whole.
37
- Being asked to add one config file is just that edit; make it, and don't open a skill to do so.
35
+ The last row is narrow on purpose. It's for "what is this project missing?" — a question about the repo as a whole. Being
36
+ asked to add one config file is just that edit; make it, and don't open a skill to do so.
38
37
 
39
38
  Tasks routinely span two: building a screen usually means `imf-web-ui-ux` for the shape and `imf-web-ui-components` for the
40
39
  APIs. That's normal — open both, in that order.
@@ -44,9 +43,6 @@ APIs. That's normal — open both, in that order.
44
43
  TanStack is the recommended tooling library — routing, server state, forms, tables. When a task needs one of those and the
45
44
  project has no incumbent, propose it, and read the library's own docs (`npx @tanstack/cli`) rather than working from memory.
46
45
 
47
- Much of the suite also ships Agent Skills inside the package, reachable via TanStack Intent. Wiring that up is
48
- `imf-web-ui-agent-setup`.
49
-
50
46
  ## When to interview the human
51
47
 
52
48
  `imf-web-ui-ux` contains a short per-feature interview. Run it **only** when both hold:
@@ -3,7 +3,7 @@ name: imf-web-ui-components
3
3
  description:
4
4
  "Look up @imfusion/web-ui component APIs without reading their source: the two-hop lookup (identity index -> prop data),
5
5
  compound components, and integrations. Load when you need the props, sub-components, or defaults of a specific component —
6
- not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-library-setup)."
6
+ not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-setup)."
7
7
  ---
8
8
 
9
9
  # imf-web-ui-components
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: imf-web-ui-frontend-patterns
3
+ description:
4
+ "Raise the quality of frontend code written around @imfusion/web-ui — including quickly vibe-coded frontends. Library
5
+ boundary contract (tokens, CSS layers, type derivation), component roles, state placement, effects discipline, code
6
+ conventions (TypeScript, naming, file organisation, testing), and stack defaults. Load when writing wrapper components,
7
+ custom UI, styling beyond the defaults, adding new files to a consumer app, or choosing a routing, data-fetching, form, or
8
+ table library."
9
+ ---
10
+
11
+ # imf-web-ui-frontend-patterns
12
+
13
+ One guard, once: **if the host project already has a convention — a styling system, a state library, a folder shape — the
14
+ project wins.** These defaults fill vacuums. They are not a license to refactor a consumer codebase toward this document.
15
+
16
+ Everything else below is how to build.
17
+
18
+ ## Stay behind the library
19
+
20
+ Never import Base UI (or any other upstream this library wraps) directly — no upstream stylesheets, no upstream components,
21
+ even when upstream docs show it that way. Everything a component needs ships in `@imfusion/web-ui`. If the library is missing
22
+ something upstream has, report the gap (see `imf-web-ui-components`); don't reach around it.
23
+
24
+ ## Style through the sanctioned seams
25
+
26
+ All library styles live in the `imf-ui.components` CSS layer, so **any plain selector you write wins** — that's the whole
27
+ override contract:
28
+
29
+ - Target the stable hooks: `data-imf-ui-component` attributes and your own classes/wrappers.
30
+ - Never target the library's internal class names — they are generated and change without notice.
31
+ - Never `!important` — if you think you need it, you're targeting the wrong thing.
32
+
33
+ ## Build custom UI from tokens
34
+
35
+ Anything you build that the library doesn't cover — a stat widget, a custom panel — uses `--imf-ui-*` variables for color,
36
+ spacing, radius, and type instead of hardcoded values. That's what makes custom UI look native next to library components,
37
+ 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
38
+ defect.
39
+
40
+ ## Derive types, don't import them
41
+
42
+ Prop types come from the components themselves: `React.ComponentProps<typeof Button>`. The library deliberately exports no
43
+ `Props` types — don't look for them, and don't re-declare prop shapes by hand.
44
+
45
+ ## Integrations own their peers
46
+
47
+ Components under `@imfusion/web-ui/integrations/*` depend on optional peers (e.g. `@tanstack/highlight` for `CodeHighlight`).
48
+ Add the peer explicitly to the consumer's `package.json` — never rely on hoisting.
49
+
50
+ ## React patterns
51
+
52
+ The full treatment — component roles with an example, state placement, effects discipline, and the react.dev sources to
53
+ consult while building — lives in [references/react-patterns.md](references/react-patterns.md). Read it before writing new
54
+ screens or wrappers. The core in one breath:
55
+
56
+ - **Three roles.** Dumb components own how things look, layout components own arrangement, smart containers own data and
57
+ logic. Styling never lives in containers.
58
+ - **State lives where its truth lives.** URL → query cache → context → store → local state; walk the list, stop at the first
59
+ match.
60
+ - **Effects are a last resort**, and always extracted into purpose-named hooks.
61
+ - **Compose, don't configure.** If a component's prop list reads like a settings page, it wanted to be two or three
62
+ components.
63
+
64
+ ## Everything else about the code
65
+
66
+ TypeScript, naming, where files go, and what's worth testing live in
67
+ [references/code-conventions.md](references/code-conventions.md). Read it when you're adding files rather than editing
68
+ existing ones — that's when these choices get made and then inherited by everything after.
69
+
70
+ The split between the two references: `react-patterns.md` covers **writing React** — component roles, where state lives,
71
+ effects discipline, composition. `code-conventions.md` covers **the code around it** — TypeScript, JS style, naming, file
72
+ layout, testing. Starting a new feature usually wants both.
73
+
74
+ ## Stack defaults
75
+
76
+ TanStack is the default for the tooling around web-ui, whether the app is greenfield or you're adding one screen to something
77
+ that already exists. The ones you'll reach for most: **Router** (URL state, type-safe search params), **Query** (server
78
+ state), **Form** (form state), and **Table** for data grids, which you pair with web-ui's styled `Table` parts
79
+ (`Table.SortableHeaderCell` carries the sort glue). The suite goes wider than those four — check what exists before adding a
80
+ non-TanStack dependency. This is the stack the state ladder assumes.
81
+
82
+ `useState` is the right tool for local UI state, and most of it is local: whether a panel is open, which tab is active, a
83
+ draft value being typed, a hover flag. Keep those in the component and don't reach for a library.
84
+
85
+ The line is what the state is _for_, not how much of it there is. A library owns the layer once you find yourself rebuilding
86
+ what it does: validation timing and cross-field rules (**Form**), caching and refetching (**Query**), URL as the source of
87
+ truth (**Router**), sorting and pagination over rows (**Table**). web-ui ships none of that logic, and that absence is not an
88
+ argument for writing it yourself. Adding the library mid-project is normal and cheap; unpicking a hand-rolled version of it
89
+ later is not.
90
+
91
+ For best practices and patterns within any of these libraries, go to the library's own guidance rather than working from
92
+ memory: `npx @tanstack/cli` for docs. Where a project has wired up `@tanstack/intent`, use it to reach the Agent Skills its
93
+ TanStack dependencies ship, and read those too.
@@ -0,0 +1,133 @@
1
+ # Code conventions
2
+
3
+ The ImFusion defaults for everyday code around `@imfusion/web-ui` — the parts that aren't React-specific. TypeScript, file
4
+ organisation, naming, and testing. React component structure lives in [react-patterns.md](react-patterns.md); the two are
5
+ read together when starting new code.
6
+
7
+ These fill vacuums. Where the host project has already decided, the project wins.
8
+
9
+ ## TypeScript
10
+
11
+ - **`any` is forbidden.** `unknown` at a boundary you genuinely can't type, narrowed before use. An `any` that silences an
12
+ error moves the failure from compile time to runtime, which is the opposite of the trade you wanted.
13
+ - **Lean on inference for locals; annotate the contract.** Restating a type the compiler already knows inside a function body
14
+ is a second thing to keep in sync. An **explicit return type on an exported function is worth writing**: it's the promise
15
+ the module makes, it stops an internal refactor silently widening the public shape, and it makes the error surface at the
16
+ function rather than at every call site.
17
+ - **No temporal coupling.** Don't initialise to `null` and fill the value in later — model the states instead, so "not loaded
18
+ yet" and "loaded, empty" aren't the same value.
19
+ - **Avoid `as`.** A type assertion tells the compiler to stop checking exactly where checking is worth most. Fix the type.
20
+ Assertions at an untyped third-party boundary are the honest exception; keep them at the boundary, not spread through call
21
+ sites.
22
+
23
+ **Derive types, don't duplicate them.** One source of truth, everything else follows from it:
24
+
25
+ ```ts
26
+ const sizes = ["sm", "md", "lg"] as const;
27
+ type Size = (typeof sizes)[number];
28
+
29
+ const labels: Record<Size, string> = { sm: "S", md: "M", lg: "L" }; // compiler breaks if `sizes` changes
30
+ ```
31
+
32
+ The same rule crosses the library boundary: prop types come from the components themselves
33
+ (`React.ComponentProps<typeof Button>`), never re-declared by hand.
34
+
35
+ **Function signatures.** One or two positional arguments read fine. At three or more, take a single object and destructure —
36
+ call sites stop depending on argument order, and adding a parameter stops being a breaking change.
37
+
38
+ ## Expressions over statements
39
+
40
+ Reach for the array methods before the loop. `map`, `filter`, `find`, `some`, `every`, `flatMap`, `reduce` — each names what
41
+ it's doing, where a `for` loop makes you read the body to find out.
42
+
43
+ ```ts
44
+ // The name is the documentation
45
+ const activeNames = users.filter(u => u.isActive).map(u => u.name);
46
+
47
+ // vs. a loop you have to read to understand
48
+ const activeNames = [];
49
+ for (const u of users) {
50
+ if (u.isActive) activeNames.push(u.name);
51
+ }
52
+ ```
53
+
54
+ The deeper reason is mutation: the method chain produces a new value, so nothing else can observe a half-built array. Prefer
55
+ spreads and `structuredClone` over in-place edits, and `toSorted`/`toReversed` over `sort`/`reverse`, which mutate their
56
+ receiver and have surprised everyone at least once.
57
+
58
+ Two honest exceptions: a genuine early exit (`for` with `break` beats `find` returning a sentinel) and a hot loop over
59
+ thousands of items where the intermediate arrays actually measure. Neither is the common case, so reach for the method first
60
+ and justify the loop.
61
+
62
+ Keep the chain flat. Three or four steps read well; ten want intermediate named constants, and a `reduce` doing four things
63
+ at once wants to be a loop after all.
64
+
65
+ ## Naming
66
+
67
+ - Say what it is, not what it is made of. `useUserQuery`, not `useUserHook`. `retryDelay`, not `num`.
68
+ - Booleans read as assertions: `isOpen`, `hasAccess`, `canSubmit`. A boolean called `status` will end up holding a string.
69
+ - Handlers are `onX` as props, `handleX` as implementations — the prop names the event, the function names the response.
70
+ - Match the vocabulary the product and the API already use. Inventing a synonym for a term the backend already named costs a
71
+ translation step on every read.
72
+
73
+ ## File and folder organisation
74
+
75
+ Kebab-case throughout, folders and files.
76
+
77
+ ```
78
+ src/
79
+ routes/ # TanStack Router file-based routes; routing only
80
+ api/<topic>/ # <topic>.ts (queries/mutations), query-key.ts, types.ts
81
+ components/ # grouped by kind of component — layouts/, primitives/, or a domain name
82
+ http/ # client, error normalisation
83
+ lib/ # framework-free helpers
84
+ ```
85
+
86
+ `api/` groups by topic: a query lives next to its key factory and its types, so a query key is never spelled out at a call
87
+ site. Routes compose and don't fetch inline. Transport concerns live in `http/` and nowhere else.
88
+
89
+ `components/` groups by kind — a layout component under `layouts/`, not beside a domain widget. Flat is fine while there are
90
+ few; let the grouping follow what the project has rather than imposing it up front. The kinds worth separating are the
91
+ component roles in [react-patterns.md](react-patterns.md): dumb components, layout components, smart containers.
92
+
93
+ A component gets a folder once it has more than one file, with an `index.ts` that only re-exports:
94
+
95
+ ```
96
+ components/data-table/
97
+ data-table.tsx
98
+ data-table-row.tsx
99
+ data-table.module.css
100
+ index.ts
101
+ ```
102
+
103
+ Colocate tests, styles, and types with their subject. A file you have to hunt for in a parallel tree gets edited less
104
+ carefully.
105
+
106
+ ## Styling
107
+
108
+ **CSS Modules by default**, colocated as `<component>.module.css`. No CSS-in-JS, no utility-class framework. Compose from
109
+ `--imf-ui-*` tokens so custom UI stays consistent with library components and follows the theme; the override contract (CSS
110
+ layers, `data-imf-ui-component`, never the library's generated class names) is in the parent skill.
111
+
112
+ `imf-web-ui-imfusion-frontend-setup` sets up or audits this structure on an ImFusion project.
113
+
114
+ ## Testing
115
+
116
+ Test the **decisions**, not the rendering.
117
+
118
+ - **Pure logic gets unit tests** — pricing, permissions, date math, parsing, reducers. These are cheap, fast, and the place
119
+ bugs actually hide.
120
+ - **Presentational components generally don't.** A component that maps props onto web-ui primitives has no logic of its own;
121
+ asserting that it rendered a `<Button>` tests React, not your code.
122
+ - **Behaviour a user performs gets an interaction test** — a form that validates, a flow with steps. Test it through the
123
+ interface the user has (roles, labels, visible text), not through internals.
124
+ - **Extract the decision out of a hook and test that.** A hook whose interesting part is a plain function is easier to test
125
+ as a plain function than through a render harness. A hook that only wraps a browser API has no decision to extract.
126
+
127
+ The measure isn't coverage percentage. It's whether a test failing tells you something you didn't already know.
128
+
129
+ ## Formatting and linting
130
+
131
+ Don't argue about it in review — the tooling decides, and it runs before the commit lands. A formatter, a linter, and a
132
+ pre-commit hook wired so none of them is optional. On an ImFusion project, `imf-web-ui-imfusion-frontend-setup` carries the
133
+ baseline and the setup steps.
@@ -1,4 +1,4 @@
1
- # React
1
+ # React patterns
2
2
 
3
3
  The house defaults for the React code around `@imfusion/web-ui`, in full. The links throughout are for **you, the agent**:
4
4
  consult them while building — they are the authoritative source when a case here is ambiguous. Hand them to the human only if
@@ -43,8 +43,9 @@ function UserCardContainer({ userId }: { userId: string }) {
43
43
  ```
44
44
 
45
45
  Why it matters here: dumb components are the layer where `@imfusion/web-ui` lives. Keeping them free of logic keeps every
46
- screen restylable, testable with plain props, and resilient to library updates. When and how to wrap the library's primitives
47
- in app-level dumb components is [library-boundary.md](library-boundary.md).
46
+ screen restylable, testable with plain props, and resilient to library updates. The one web-ui-specific addition: wrap
47
+ `experimental` components (marked in the identity index) in a dumb component once per app even if you add nothing yet — a
48
+ breaking upstream change then lands in one file instead of every call site.
48
49
 
49
50
  ## Compose, don't configure
50
51
 
@@ -55,18 +56,15 @@ components. When state must be shared between siblings, lift it to the nearest c
55
56
 
56
57
  ## Put state where its truth lives
57
58
 
58
- State comes in kinds, and each kind has an owner. Work down this list and stop at the first match:
59
+ Work down this list and stop at the first match:
59
60
 
60
- 1. **URL state** — shareable via the address bar (filters, sort, pagination, active tab) → TanStack Router search params.
61
- Back button and copied links are UX features you get for free.
62
- 2. **Server state** — comes from an API → TanStack Query's cache ([data.md](data.md)). Never copy server data into `useState`
63
- — that's how stale-UI bugs are born.
64
- 3. **Subtree state** — scoped to a subtree, resets on leave (wizard progress) → React context.
65
- 4. **Client state** — app-wide and persistent → TanStack Store, and only now.
66
- 5. **Local state** — one component's own (input value, open/closed) → `useState`.
67
-
68
- `useState` is the right tool for local UI state, and most state is local: whether a panel is open, which tab is active, a
69
- draft value being typed, a hover flag. Keep those in the component and don't reach for a library.
61
+ 1. **Shareable via URL?** (filters, sort, pagination, active tab) → router search params. Back button and copied links are UX
62
+ features you get for free.
63
+ 2. **Comes from an API?** → the data-fetching layer's cache (e.g. TanStack Query). Never copy server data into `useState` —
64
+ that's how stale-UI bugs are born.
65
+ 3. **Scoped to a subtree, resets on leave?** (wizard progress) → React context.
66
+ 4. **App-wide and persistent?** → a client store, and only now.
67
+ 5. **Local to one component?** (input value, open/closed) → `useState`.
70
68
 
71
69
  Most frontends need far less of tier 4 than they think; tiers 1–2 usually dissolve the "we need a store" instinct. For
72
70
  structuring the state itself, [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) is the
@@ -84,18 +82,6 @@ When an effect is genuinely needed, extract it into a custom hook named for its
84
82
  hook isolates the dependency array, and the component body stays declarative. Pattern reference:
85
83
  [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks).
86
84
 
87
- The naming rule holds even for the rare effect that stays inline: give the callback a name, so the intent survives without a
88
- comment —
89
-
90
- ```tsx
91
- useEffect(
92
- function syncDocumentTitle() {
93
- document.title = title;
94
- },
95
- [title]
96
- );
97
- ```
98
-
99
85
  ## Reading list
100
86
 
101
87
  Consult while building; each is the authority for its topic: