@imfusion/web-ui 0.5.1-dev.33.gadde98d1 → 0.5.1-dev.39.gfc64049e

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

@@ -1,110 +0,0 @@
-# React
-
-The house defaults for the React code around `@imfusion/web-ui`, in full. The links throughout are for **you, the agent**:
-consult them while building — they are the authoritative source when a case here is ambiguous. Hand them to the human only if
-asked.
-
-## Component roles
-
-Dumb/smart separation is standard React practice (it traces back to Dan Abramov's
-["Presentational and Container Components"](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) and
-survives in [Thinking in React](https://react.dev/learn/thinking-in-react)). The house version has three roles:
-
-- **Dumb components** own how things _look_. They style and compose library primitives, receive plain data and callbacks as
-  props, and know nothing about fetching, routing, or business logic. All non-layout styling lives here — and only here.
-- **Layout components** own _arrangement_ — and nothing else. `Stack`- and `Row`-based wrappers with token gaps, a page grid,
-  a section frame. They exist because smart containers are styleless: when a container needs two panels side by side, that
-  arrangement is a layout component, not an inline style.
-- **Smart containers** own how things _work_. Routes (or explicit container components) fetch data, hold orchestration logic,
-  and wire the other two together. Zero styling — the moment a container wants CSS, extract a layout component.
-
-```tsx
-// Dumb — renders what it's given
-function UserCard({ name, role, onEdit }: { name: string; role: 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>
-    </Card.Root>
-  );
-}
-
-// Smart — knows where data comes from, renders the dumb component
-function UserCardContainer({ userId }: { userId: string }) {
-  const { data } = useUserQuery(userId);
-  const openEditor = useEditorNavigation(userId);
-  return <UserCard name={data.name} role={data.role} onEdit={openEditor} />;
-}
-```
-
-Why it matters here: dumb components are the layer where `@imfusion/web-ui` lives. Keeping them free of logic keeps every
-screen restylable, testable with plain props, and resilient to library updates. When and how to wrap the library's primitives
-in app-level dumb components is [library-boundary.md](library-boundary.md).
-
-## Compose, don't configure
-
-Build screen-level pieces by composing primitives (`Stack`, `Row`, `Card`, your dumb components) rather than growing one
-component with a dozen boolean props. If a component's prop list reads like a settings page, it wanted to be two or three
-components. When state must be shared between siblings, lift it to the nearest common parent —
-[Sharing State Between Components](https://react.dev/learn/sharing-state-between-components) — rather than syncing copies.
-
-## Put state where its truth lives
-
-State comes in kinds, and each kind has an owner. Work down this list and stop at the first match:
-
-1. **URL state** — shareable via the address bar (filters, sort, pagination, active tab) → TanStack Router search params.
-   Back button and copied links are UX features you get for free. URL values cross an external boundary; parse them according
-   to [validation.md](validation.md).
-2. **Server state** — comes from an API → TanStack Query's cache ([data.md](data.md)). Never copy server data into `useState`
-   — that's how stale-UI bugs are born.
-3. **Subtree state** — scoped to a subtree, resets on leave (wizard progress) → React context.
-4. **Client state** — app-wide and persistent → TanStack Store, and only now.
-5. **Local state** — one component's own (input value, open/closed) → `useState`.
-
-`useState` is the right tool for local UI state, and most state is local: whether a panel is open, which tab is active, a
-draft value being typed, a hover flag. Keep those in the component and don't reach for a library. When a form turns drafts
-into a submitted domain value, validate that boundary as described in [validation.md](validation.md).
-
-Most frontends need far less of tier 4 than they think; tiers 1–2 usually dissolve the "we need a store" instinct. For
-structuring the state itself, [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) is the
-reference — especially its rules on avoiding redundant and duplicated state.
-
-## Effects: last resort, and named
-
-Before writing `useEffect`, check: derived values belong in render (or `useMemo`), responses to user actions belong in the
-event handler, and server synchronization belongs in the data-fetching layer. Effects are for synchronizing with systems
-_outside_ React. The definitive catalog of effect misuses — read it before every effect you're tempted to write — is
-[You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect).
-
-When an effect is genuinely needed, extract it into a custom hook named for its purpose — `useSyncedScroll`,
-`useDocumentTitle`, `useHotkey` — never an anonymous `useEffect` block inline in a component. The name documents intent, the
-hook isolates the dependency array, and the component body stays declarative. Pattern reference:
-[Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks).
-
-The naming rule holds even for the rare effect that stays inline: give the callback a name, so the intent survives without a
-comment —
-
-```tsx
-useEffect(
-  function syncDocumentTitle() {
-    document.title = title;
-  },
-  [title]
-);
-```
-
-## Reading list
-
-Consult while building; each is the authority for its topic:
-
-- [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-frontend-conventions/references/stack.md

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

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

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

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

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

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

@@ -1,76 +0,0 @@
-# Tooling config
-
-The config baselines for the tools in [stack.md](stack.md). Prefer typed config (`.ts` over `.json`) where the tool supports
-it.
-
-## Prettier
-
-Config file shape is free (`.prettierrc`, `prettier.config.ts`); the values are not:
-
-```ts
-import type { Config } from "prettier";
-
-const config: Config = {
-  printWidth: 125,
-  tabWidth: 2,
-  useTabs: false,
-  trailingComma: "none",
-  arrowParens: "avoid",
-  semi: true,
-  singleQuote: false,
-  proseWrap: "always"
-};
-```
-
-No config file means Prettier runs on defaults — 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`) — ignores aren't maintained twice
-- The `#/` alias enforced via `no-restricted-imports` banning the `../*` pattern — 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/*"] }
-  }
-}
-```
-
-The `#/` → `src/` alias and its rationale: [project-structure.md](project-structure.md).
-
-## Staged files
-
-Runner config (lint-staged or nano-staged) applying eslint `--fix` and prettier `--write` to staged files only.
-
-## 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 that produces them; pass your own short,
-app-scoped prefix:
-
-```ts
-import { readableCssModuleNames } from "@imfusion/web-ui/build/vite-css-module-names";
-
-export default defineConfig({
-  plugins: [react(), readableCssModuleNames({ prefix: "acme" })]
-});
-```
-
-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 file, and its styles silently don't apply.

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

@@ -1,88 +0,0 @@
-# Validation
-
-Runtime validation belongs where data crosses from an untrusted representation into frontend-owned values. The schema is the
-single source of truth for both the runtime check and the TypeScript type.
-
-## Boundaries
-
-Validate once, at the edge:
-
-- network responses when they enter the frontend;
-- URL path and search parameters before business logic uses them;
-- persisted browser data when it is read;
-- user input when it becomes a submitted domain value or request value.
-
-Code inside that boundary receives parsed values and does not repeat defensive shape checks. An outgoing request built from
-an already parsed domain value is serialized, not validated a second time. A typed client returning a handwritten generic is
-not validation: it only asserts that an untrusted response has the requested type.
-
-## Schema first, type derived
-
-Use Zod for the runtime schema and derive the type with `z.infer`:
-
-```ts
-import { z } from "zod";
-
-export const userSchema = z.object({
-  id: z.string(),
-  email: z.email()
-});
-
-export type User = z.infer<typeof userSchema>;
-```
-
-Do not maintain a handwritten `User` beside `userSchema`. Request and response shapes follow the same rule when the frontend
-owns or consumes their runtime representation.
-
-## TanStack Router search params
-
-TanStack Router v1 accepts a Zod v4 schema directly in `validateSearch`; no adapter or parsing wrapper is needed:
-
-```tsx
-import { createFileRoute } from "@tanstack/react-router";
-import { z } from "zod";
-
-const searchSchema = z.object({
-  page: z.number().int().positive().catch(1),
-  filter: z.string().catch("")
-});
-
-type UserSearch = z.infer<typeof searchSchema>;
-
-export const Route = createFileRoute("/users")({
-  validateSearch: searchSchema,
-  component: Users
-});
-
-function Users() {
-  const search = Route.useSearch();
-  return <UserList page={search.page} filter={search.filter} />;
-}
-```
-
-`Route.useSearch()` returns `UserSearch` by inference from `validateSearch`. Use `.catch()` when malformed URL input should
-fall back without interrupting navigation. Use `.default()` only when a missing value gets a default while malformed values
-should still follow the route's validation error path.
-
-## Failure handling
-
-Use `schema.parse(value)` when invalid data is a contract failure that should follow the normal error path, such as a
-malformed backend response reaching a route error boundary. Use `schema.safeParse(value)` when failure is expected and the
-caller must render or otherwise handle validation issues, such as submitted user input.
-
-Transforms and coercion belong in the boundary schema when they are part of entering the domain. Do not scatter trimming,
-number conversion, or defaulting through downstream components.
-
-## Audit
-
-A boundary is aligned when:
-
-- the untrusted source is represented as `unknown` until parsed;
-- a Zod schema parses it at the point of entry;
-- exported TypeScript types use `z.infer<typeof schema>`;
-- downstream code consumes the parsed value without duplicate checks or assertions;
-- parse failures reach the intended error or user-feedback path;
-- behavior-changing schemas have focused tests for accepted, rejected, and transformed values.
-
-TanStack Query placement is in [data.md](data.md), general type derivation in [typescript.md](typescript.md), URL and form
-ownership in [react.md](react.md), and test selection in [testing.md](testing.md).

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

@@ -1,66 +0,0 @@
----
-name: imf-web-ui-frontend-setup
-description:
-  "Assess an ImFusion frontend against the project baseline and write a reviewable FRONTEND_SETUP_REPORT.md: new-project
-  setup needs, existing-project gaps, alignment migrations, or one named topic (for example data, lifecycle hooks, CSS class
-  names, or Prettier). Covers stack, package scripts, tooling, verification, project shape, data, docs, and agent wiring.
-  House conventions, not industry standards. This skill inspects and plans; approved implementation is a separate task. Not
-  for wiring the library itself (imf-web-ui-library-setup)."
-argument-hint: "[new|audit|align|<topic>]"
-allowed-tools: Read Glob Grep
----
-
-# imf-web-ui-frontend-setup
-
-You are the frontend setup auditor. Investigate the repository statically, record every supported conclusion in
-`FRONTEND_SETUP_REPORT.md`, then stop for human review. You must follow the applicable `imf-web-ui-frontend-conventions`
-references, cite repository evidence, distinguish defects from working deviations, and never present the baseline as
-universal best practice.
-
-## Workflow
-
-1. Resolve the requested mode and scope.
-2. Read every applicable convention reference below. For agent tooling, also read the vendored
-   `imf-web-ui-agent-setup/SKILL.md` and its templates.
-3. Inspect the repository and write or refresh `FRONTEND_SETUP_REPORT.md` from
-   [`templates/FRONTEND_SETUP_REPORT.md`](templates/FRONTEND_SETUP_REPORT.md). The template is the report contract. Preserve
-   everything under `## Reviewer notes` verbatim.
-4. Return the report path and a short verdict. Change nothing else; implementation is a separate, approved task.
-
-## Safety
-
-Use only static inspection: Read, Glob, Grep, and equivalent non-executing search tools. Do not use a shell or invoke Node,
-npm, npx, package scripts, hooks, config imports, linters, tests, builds, Git commands, or project binaries. Read config as
-text and report runtime or machine-local state that cannot be established statically as unverified.
-
-Only `FRONTEND_SETUP_REPORT.md` may be written. Write is intentionally not pre-approved in `allowed-tools`; the report
-follows the host's ordinary write approval. Host-managed hooks may run after that write; the skill neither invokes nor
-suppresses them, but it does report broken or unexpected hook behavior found during static inspection.
-
-## Modes
-
-- **New** — record what exists and what setup work is needed.
-- **Audit** — report broken and missing pieces. A working project convention wins; differences are deviations, not defects.
-- **Align** — use the same evidence, but make deviations explicit migration proposals.
-- **One topic** — resolve any other argument to matching rows below and assess only those. If none match, list the available
-  rows instead of guessing or widening scope.
-
-## References
-
-| Reference                         | Assess                                                                    |
-| --------------------------------- | ------------------------------------------------------------------------- |
-| `stack.md`                        | dependencies, dead-code detection, and matching devtools                  |
-| `npm-project.md`                  | package metadata, scripts, pins, npm and Node config                      |
-| `tooling.md`                      | Prettier, ESLint, TypeScript, staged files, CSS class names               |
-| `git.md`                          | tracked hooks, verification scopes, staleness wiring                      |
-| `project-structure.md`            | source tree, naming, imports                                              |
-| `components.md`                   | component folders and colocation                                          |
-| `styling.md`                      | CSS Modules, tokens, prohibited styling systems                           |
-| `validation.md`                   | runtime schemas, boundary parsing, derived types                          |
-| `data.md`                         | transport, query/mutation options, keys, invalidation                     |
-| `docs-structure.md`               | README, AGENTS, docs index and content boundaries                         |
-| `imf-web-ui-agent-setup/SKILL.md` | installed skills, AGENTS fence, lifecycle hooks, registrations, staleness |
-
-Knip is required for dead-code detection. `eslint-plugin-jsx-a11y` remains a recommendation when the project is user-facing;
-its absence is not a finding. CI, env and secrets, error tracking, deploy, dependency updates, and library wiring are out of
-scope.

package/src/llms/skills/imf-web-ui-frontend-setup/templates/README.md

@@ -1,27 +0,0 @@
-# <App name>
-
-<One paragraph: what the app is, the stack in one line — e.g. "Vite + React 19 + TanStack Router (file-based, CSR) + TanStack
-Query + @imfusion/web-ui".>
-
-## Install
-
-```bash
-npm install
-npm run git:config   # once per clone: hooks path, pull.rebase, merge.ff
-```
-
-<Registry tokens, required services, or other one-time setup. Delete if none.>
-
-## Usage
-
-```bash
-npm run dev
-```
-
-<Environment specifics: proxies, .env files, ports. Delete if none.>
-
-`npm run` lists every script; `package.json` is the source of truth. `verify:full` is the CI gate.
-
-## Docs
-
-[`docs/index.md`](./docs/index.md) registers them.

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

@@ -1,36 +0,0 @@
----
-name: imf-web-ui-library-setup
-description:
-  "One-time wiring of a consumer project: the @imfusion/web-ui styles import and WebUIProvider wrapper. Load when installing
-  the library for the first time, or when components render unstyled or without theme context."
----
-
-# imf-web-ui-library-setup
-
-This is library wiring: the styles import and the provider. It applies to anyone using `@imfusion/web-ui`.
-
-If the project is an **ImFusion** frontend and this is first-time setup, mention once that `imf-web-ui-frontend-setup` sets
-up or audits the repo's tooling (formatting, linting, hooks, scripts) against the ImFusion baseline, and let the human
-decide. Offer it; never run it uninvited, and don't raise it again if they pass — the library works fine without any of it.
-
-Every consumer entry point needs exactly two lines, in this order:
-
-```tsx
-import "@imfusion/web-ui/styles.css";
-import { WebUIProvider, Button } from "@imfusion/web-ui";
-```
-
-Wrap the app root in `<WebUIProvider>` once. Components rendered outside it won't have the theme/CSS-variable context they
-expect.
-
-Never import a Base UI (or other upstream) stylesheet or component directly — everything a web-ui component needs is already
-inside `styles.css` and the package's own exports; reaching around web-ui to the upstream library is always wrong, even if
-the upstream docs show it that way.
-
-## Symptoms of a broken setup
-
-- **Components render but look unstyled** — the `styles.css` import is missing from the entry point.
-- **Components render but ignore the theme (wrong colors, no CSS variables resolving)** — they're mounted outside
-  `<WebUIProvider>`.
-- **An integration component throws on import** — its optional peer dependency isn't installed; check the component's
-  description in the docgen index (`imf-web-ui-components`) for which peer to add to your `package.json`.