@imfusion/web-ui 0.5.1-dev.5.gb4de52d7 → 0.5.1-dev.51.gad24cd6e

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

@@ -1,201 +0,0 @@
----
-name: imf-web-ui-imfusion-frontend-setup
-description:
-  "Set up or audit an ImFusion frontend's project tooling: the stack, package.json scripts, formatting, linting, typecheck,
-  staged-file and pre-commit hooks, verification scopes, dependency pinning, tsconfig, folder structure. House conventions,
-  not industry standards. Load when starting a new ImFusion frontend, or when asked what an existing one's setup is missing.
-  Not for adding one config file on request — that's just the edit. Not for wiring the library itself (imf-web-ui-setup)."
----
-
-# imf-web-ui-imfusion-frontend-setup
-
-ImFusion house conventions, **not** industry standards. Report as "missing against the ImFusion baseline", never "against
-best practice". Only apply to an ImFusion frontend.
-
-Two modes, same list:
-
-- **New project** — work down the list and set each piece up.
-- **Existing project** — audit. Read the repo (don't ask what it has), report present / missing / broken, change nothing
-  until the human picks. An established repo is where a forgotten piece hides.
-
-**The project wins.** Where the repo already decided, that stands. Report what's _absent_; a working convention you'd have
-chosen differently is not a finding.
-
-## The stack
-
-| Concern      | Tool                                                      | Notes                                                                               |
-| ------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| Format       | [Prettier](https://prettier.io)                           | Values below are shared across repos                                                |
-| Lint         | [ESLint](https://eslint.org) flat config                  | `--cache --max-warnings=0`                                                          |
-| Types        | `tsc --noEmit`                                            | Own script, own CI step                                                             |
-| Staged files | [lint-staged](https://github.com/lint-staged/lint-staged) | [nano-staged](https://github.com/usmanyunusov/nano-staged) is a drop-in alternative |
-| Routing      | [TanStack Router](https://tanstack.com/router)            | File-based, `src/routes/`                                                           |
-| Server state | [TanStack Query](https://tanstack.com/query)              | Query keys colocated per API topic                                                  |
-| Client state | [TanStack Store](https://tanstack.com/store)              | Only for state that isn't URL- or server-owned                                      |
-| Styling      | CSS Modules                                               | Colocated `<component>.module.css`                                                  |
-| Dead code    | [knip](https://knipjs.dev)                                | Needs per-repo config                                                               |
-| Build        | [Vite](https://vite.dev)                                  |                                                                                     |
-| Test         | [Vitest](https://vitest.dev)                              |                                                                                     |
-
-Either staged-file runner is fine; lint-staged is the larger project and the safer default when one misbehaves.
-
-### Devtools come with the library
-
-Every TanStack library that ships a devtools package gets it as a dev dependency alongside the library itself, mounted in
-development only. Router is a given in any ImFusion frontend, so `@tanstack/react-router-devtools` is a given too; Query's
-goes in when Query does, and so on. Look for a `-devtools` sibling whenever you add a TanStack dependency rather than working
-from a fixed list — the set grows, and not every library has one yet (Store doesn't). Once a project has several,
-`@tanstack/devtools` hosts them in one panel.
-
-## package.json
-
-`"type": "module"`, `"private": true`. Scripts — these names, in every repo:
-
-| Script             | Runs                                                     |
-| ------------------ | -------------------------------------------------------- |
-| `dev`              | dev server                                               |
-| `build`            | production build                                         |
-| `verify:lint`      | `eslint . --cache --max-warnings=0`                      |
-| `verify:format`    | `prettier --check .`                                     |
-| `verify:typecheck` | `tsc --noEmit`                                           |
-| `verify:tests`     | `vitest run`                                             |
-| `verify:staged`    | staged-file subset, called by the pre-commit hook        |
-| `verify:full`      | every check above plus the build; what CI runs           |
-| `format`           | `prettier --write .`                                     |
-| `lint:fix`         | `eslint . --cache --fix`                                 |
-| `git:config`       | `git config core.hooksPath …` + `pull.rebase`/`merge.ff` |
-
-**Every check is `verify:*`.** One namespace, so "what can I run to check this?" is answered by tab-completion. Write-mode
-scripts keep tool names — `format` and `lint:fix` change files, which isn't verifying. Same name, same meaning, every repo.
-
-**Git config is an explicit command.** `git:config` holds the real command, greppable and run by hand after cloning, and the
-README's setup steps name it. `ignore-scripts=true` disables the root package's own lifecycle scripts alongside its
-dependencies', so setup that matters is a command someone runs, not a hook that fires on install.
-
-**Dependencies pinned exactly.** No `^`, `~`, or `latest`, in `dependencies` and `devDependencies` alike. A check script in
-the verify chain enforces it, but that only catches drift after it lands — `save-exact=true` in `.npmrc` stops `npm install`
-reintroducing ranges in the first place.
-
-## Config
-
-**Prettier** — config file shape is free (`.prettierrc`, `prettier.config.ts`); the values are not:
-
-```
-printWidth: 125   tabWidth: 2   useTabs: false   trailingComma: "none"
-arrowParens: "avoid"   semi: true   singleQuote: false   proseWrap: "always"
-```
-
-No config file at all means Prettier runs on defaults — flag it, the values silently differ.
-
-**ESLint** — flat config (`eslint.config.ts`), `strictTypeChecked` + `stylisticTypeChecked` with `projectService: true`, `as`
-and `!` banned outside tests, and `.gitignore` as the ignore source (`includeIgnoreFile` from `@eslint/compat`) so ignores
-aren't maintained twice.
-
-**tsconfig** — defaults:
-
-```jsonc
-{
-  "compilerOptions": {
-    "strict": true,
-    "moduleResolution": "bundler",
-    "verbatimModuleSyntax": true, // import type stays import type
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true,
-    "skipLibCheck": true,
-    "paths": { "#/*": ["./src/*"] }
-  }
-}
-```
-
-The alias is always `#/` → `src/`. `#` is Node's own subpath-import prefix, so it resolves without a bundler-specific
-convention, and it can't collide with an npm scope the way `@/` does.
-
-**Staged files** — runner config applying eslint `--fix` and prettier `--write` to staged files only.
-
-**Pre-commit** — the hook installs itself via `prepare` → `git:config`, which sets `core.hooksPath` to a tracked directory
-plus `pull.rebase true` and `merge.ff only`, so history strategy doesn't depend on personal git config. Two silent failure
-modes: no `prepare` at all (hooks exist only on the machine that ran `git config` by hand), and `core.hooksPath` pointing at
-a directory that doesn't exist. Check 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** — optional 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 name like
-`preflight` needs explaining and invites a second, near-identical script beside it. Two of those drift, and the drift reads
-as "passes locally, fails in CI".
-
-**Node pinning** — `.nvmrc` or `engines.node`. Not a personal version manager's config; that pins it for you alone.
-
-## Folder structure
-
-```
-src/
-  routes/                    # TanStack Router file-based routes; nothing but routing
-  api/<topic>/               # one folder per API topic
-    <topic>.ts               #   queries/mutations
-    query-key.ts             #   key factory
-    types.ts                 #   request/response types
-  components/                # see below
-  http/                      # client, error normalisation — the only transport-aware place
-  lib/                       # framework-free helpers
-```
-
-Everything is kebab-case, folders and files alike.
-
-**Inside `components/`, group by what kind of component it is** — `layouts/`, `primitives/`, `forms/`, or a domain name. Not
-a hard rule: a handful of components reads fine flat, and the grouping should follow what the project actually has rather
-than a structure imposed up front. But most codebases grow past flat, and a clear layout component belongs under `layouts/`
-rather than beside a domain widget.
-
-```
-components/
-  page-header/               # flat is fine
-  layouts/
-    page-shell/
-  data-table/                # a component with sub-component files
-    data-table.tsx
-    data-table-row.tsx
-    data-table.module.css
-    index.ts
-```
-
-A component gets a folder when it has more than one file — sub-components, styles, tests. Single-file components can stay
-single files. The folder's `index.ts` only re-exports, so imports read `#/components/data-table` and the inside can be
-restructured without touching call sites.
-
-Routes stay thin: they compose, they don't fetch inline. `api/<topic>/` holds the query and its key factory together so a key
-is never spelled out at a call site. Anything transport-level (base client, error normalisation) lives in `http/` and nowhere
-else.
-
-## Styling
-
-CSS Modules by default, colocated as `<component>.module.css` next to the component. No CSS-in-JS, no utility-class
-framework.
-
-On a project using `@imfusion/web-ui`, style through the sanctioned seams — `--imf-ui-*` tokens and `data-imf-ui-component`
-attributes, never the library's generated class names. `imf-web-ui-frontend-patterns` covers that contract.
-
-If more than one tool compiles the CSS (app build plus Storybook), the generated class-name pattern must be defined **once**
-and imported by both, or the same source file gets different class names in each and styles silently don't apply.
-`build/css-modules-config.ts` in web-ui is the reference shape; pick your own prefix.
-
-## Optional
-
-Recommend when the shape calls for it; absence is not a finding.
-
-- **knip** — once several people delete things independently.
-- **`ignore-scripts=true` in `.npmrc`** — blocks most supply-chain worm payloads; costs an explicit `npm rebuild` for native
-  deps.
-- **`eslint-plugin-jsx-a11y`** — anything user-facing.
-
-Out of scope, project-specific: CI, env and secrets, error tracking, deploy, dependency updates.
-
-## Not this skill
-
-- Library wiring (styles import, provider) → `imf-web-ui-setup`
-- Code conventions (TypeScript, naming, testing) → `imf-web-ui-frontend-patterns`, `references/code-conventions.md`