@imfusion/web-ui 0.6.1-dev.12.ge86ac0a1 → 0.6.1-dev.14.g8fac1dfb

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

@@ -1,44 +1,42 @@
 # Project structure
 
-Kebab-case throughout, folders and files alike; exported symbols stay PascalCase — only the filename is kebab.
+Use kebab-case for folders and files. Exported symbols use PascalCase.
 
 ## Layout
 
-```
+```text
 src/
-  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
+  routes/
+    __root.tsx
+    _public/route.tsx
+    _app/route.tsx
+  api/
+  http/
+  lib/
+  components/
 ```
 
-- Each subtree's rules live with its topic: [data.md](data.md) for `api/` and `http/`, [components.md](components.md) for
-  `components/`.
+`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).
 
 ## Application boundary
 
-- 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.
+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.
 
 ## Imports
 
-- `#/` 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.
+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.

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

@@ -1,90 +1,52 @@
 # React
 
-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.
+Keep data flow one-way and components focused. Pages decide how data is loaded; presentational components decide how it
+looks.
 
 ## Composition: pages (smart containers), partials, dumb components
 
-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).
+- **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.
 
 ```tsx
-// Dumb — renders what it's given
-function UserCard({ name, role, onEdit }: { name: string; role: string; onEdit: () => void }) {
+function UserCard({ name, onEdit }: { name: string; onEdit: () => void }) {
   return (
     <Card.Root>
-      <Card.Content>
-        <Typo>{name}</Typo>
-        <Chip>{role}</Chip>
-      </Card.Content>
-      <Card.Footer>
-        <Button onClick={onEdit}>Edit</Button>
-      </Card.Footer>
+      <Typo.P>{name}</Typo.P>
+      <Button onClick={onEdit}>Edit</Button>
     </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
 
-- 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.
+Compose small parts instead of making one component configurable through many boolean props. Lift shared state to the nearest
+common parent.
 
 ## Put state where its truth lives
 
-Work down this list; stop at the first match:
+Choose the first suitable level:
 
-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.
+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`.
 
-- 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.
+Shape state so it is not redundant or duplicated. Validate a form draft when it becomes a submitted domain value.
 
 ## Effects: last resort, and named
 
-- 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:
+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:
 
 ```tsx
 useEffect(
@@ -95,15 +57,7 @@ useEffect(
 );
 ```
 
-- 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:
+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.
 
-- [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
+Read the React documentation when a decomposition or effect decision is unclear.

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

@@ -1,88 +1,91 @@
 # Styling
 
-How app CSS is written and how it meets `@imfusion/web-ui`.
+Use native CSS and Web UI's public seams. The library's CSS Modules and token names are not consumer implementation details.
 
 ## CSS authoring
 
-- **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:
+- 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
-  .root {
-    transition: clip-path var(--ease);
+```css
+.root {
+  transition: opacity var(--imf-ui-duration-quick-2) var(--imf-ui-ease-2);
 
-    &:focus-visible {
-      outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-support);
-    }
-
-    &[data-disabled] {
-      opacity: 0.5;
-    }
+  &:focus-visible {
+    outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-primary);
   }
-  ```
 
-- 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.
+  &[data-disabled] {
+    opacity: 0.5;
+  }
+}
+```
 
 ## Build custom UI from tokens
 
-- 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.
+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.
+
+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.
 
 ## 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` — 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);
-  }
-  ```
+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);
+}
+```
 
 ## The color system
 
-- 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:
+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.
 
-  ```css
-  :root {
-    --imf-ui-color-primary-hue: 30; /* every primary semantic token follows */
-  }
-  ```
+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
 
-- **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.
+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);
+  }
+}
+```
 
 ## 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 (why sizing is variables, not a `width` prop):
+Override component variables inside your own media queries:
 
-  ```css
-  @media (min-width: 768px) {
-    .my-shell {
-      --imf-ui-appshell-navbar-width: 22rem;
-    }
+```css
+@media (min-width: 768px) {
+  .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.
+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.

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

@@ -1,25 +1,23 @@
 # Testing
 
-Test the **decisions**, not the rendering.
+Test decisions and user behavior, not framework behavior.
 
 ## Naming
 
-- Colocated tests use `.test.ts` / `.test.tsx` (e.g. `login-url.test.ts`) — not `.spec.*` or plural `.tests.*`.
+Colocate tests and name them `*.test.ts` or `*.test.tsx`.
 
 ## What gets a test
 
-- **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.
+- 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.
 
 ## Layer-specific recipes
 
-- 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).
+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.

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

@@ -1,7 +1,12 @@
 # Tokens
 
-## Token index
+Use the generated token index when choosing a Web UI token.
 
-- `@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.
+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.

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

@@ -1,50 +1,44 @@
 # Tooling
 
-Dependency and configuration baseline for an ImFusion frontend; check before adding a dependency and before writing its
-config.
+Read this topic before adding a dependency or configuring a tool. Use the tool's current documentation rather than memory.
 
 ## Topic-to-tool map
 
-- Use the mapped tool for each topic; prefer typed config (`.ts` over `.json`) where the tool supports it.
-
-| 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)                                                                       |
-| Lint                  | [ESLint](https://eslint.org) flat config                                                              |
-| 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) via `verify:knip` — needs per-repo config                                  |
+| Need                  | Default                                      |
+| --------------------- | -------------------------------------------- |
+| Build                 | Vite                                         |
+| Routing and URL state | TanStack Router                              |
+| Server state          | TanStack Query                               |
+| Forms                 | TanStack Form                                |
+| Data grids            | TanStack Table plus Web UI `Table` parts     |
+| App-wide client state | TanStack Store, after URL/server/local state |
+| Schema validation     | Zod at the boundary                          |
+| Tests                 | Vitest                                       |
+| Format                | Prettier                                     |
+| Lint                  | ESLint flat config                           |
+| Types                 | `tsc --noEmit`                               |
+| Staged files          | lint-staged or nano-staged                   |
+| Dead code             | Knip via `verify:knip`                       |
 
 ## When a library owns a layer
 
-- Adopt the library once you're rebuilding what it does — validation timing and cross-field rules (Form), caching and
-  refetching (Query), URL as source of truth (Router), sorting/pagination over rows (Table): adding it mid-project is cheap,
-  unpicking a hand-rolled version later is not.
+Use the library that already owns the problem. Adopt Form for form rules, Query for caching and refetching, Router for URL
+state, and Table for sorting and pagination instead of rebuilding those layers. Keep an existing project choice when it
+works.
 
 ## Devtools
 
-- Every TanStack library with a devtools package gets it as a dev dependency, mounted in development only — Router's
-  `@tanstack/react-router-devtools` is a given; Query's goes in when Query does.
-- Check for a `-devtools` sibling on every new TanStack dependency — not every library has one yet.
-- Once several are in, host them in one panel via `@tanstack/devtools`.
+Add the devtools package for a TanStack library when one exists, mount it only in development, and check for a matching
+devtools package whenever a new TanStack dependency is added.
 
 ## Docs over memory
 
-- `npx @tanstack/cli` for TanStack docs — never work from memory.
-- Where `@tanstack/intent` is wired up, use it to reach and read the Agent Skills the TanStack dependencies ship.
+Use `npx @tanstack/cli` for TanStack documentation. If TanStack Intent is configured, use it for the Agent Skills the
+TanStack package provides.
 
 ## Prettier
 
-- Config file shape is free (`.prettierrc`, `prettier.config.ts`); the values are not:
+Use a config file. The repo's values are:
 
 ```ts
 import type { Config } from "prettier";
@@ -59,58 +53,36 @@ const config: Config = {
   singleQuote: false,
   proseWrap: "always"
 };
-```
 
-- Never omit the config file — no file means defaults, and the values silently differ.
-
-## ESLint
-
-Flat config (`eslint.config.ts`):
-
-- `strictTypeChecked` + `stylisticTypeChecked`, `projectService: true`
-- `as` and `!` banned outside tests (`consistent-type-assertions`)
-- `.gitignore` as the ignore source (`includeIgnoreFile` from `@eslint/compat`)
-- `#/` alias enforced via `no-restricted-imports` banning `../*` — parent-relative paths error, siblings (`./`) stay relative
-  ([project-structure.md](project-structure.md))
-
-## tsconfig
-
-```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/*"] }
-  }
-}
+export default config;
 ```
 
-- `#/` → `src/` alias rationale: [project-structure.md](project-structure.md).
+## ESLint and TypeScript
+
+Use flat ESLint config with type-aware rules and the repo's ignore file. The baseline bans `as` and non-null `!` outside
+tests, requires the `#/` alias instead of parent-relative imports, and uses project-service type information.
+
+Use strict TypeScript with bundler module resolution, `verbatimModuleSyntax`, unused-value checks, and `#/` paths. Keep
+`import type` for type-only imports.
 
 ## Staged files
 
-- Runner config (lint-staged or nano-staged) applies eslint `--fix` and prettier `--write` to staged files only.
-- The pre-commit runner also invokes `verify:knip` when staged source or project config can change the reachability graph.
+The staged-file runner applies ESLint fixes and Prettier writes only to staged files. It also runs the relevant project
+checks when source or config can affect the dependency graph.
 
 ## CSS class names
 
-- Generated CSS Module class names are readable in the DOM, `{prefix}-{file}-{local}`, never the default hash: a legible DOM
-  is what makes devtools and browser automation usable.
-- The library ships the plugin; pass a short, app-scoped prefix:
+Register Web UI's `readableCssModuleNames` plugin in every compiler that processes the app's CSS, including development,
+Storybook, and production:
 
 ```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
 import { readableCssModuleNames } from "@imfusion/web-ui/build/vite-css-module-names";
 
 export default defineConfig({
-  plugins: [react(), readableCssModuleNames({ prefix: "acme" })]
+  plugins: [react(), readableCssModuleNames({ prefix: "app" })]
 });
 ```
 
-- One pattern for dev, Storybook, and production: register the plugin in **every** tool that compiles the CSS — a compiler
-  left out generates different names for the same source, and its styles silently don't apply.
+A compiler left out of the plugin produces different class names and styles that appear to work only in some environments.