@kerfjs/ui 4.4.1 → 5.0.0-beta.10

package/llms.txt

@@ -1,22 +1,131 @@
 # @kerfjs/ui
 
-Accessible, production-backed UI primitives for kerf applications.
+> Accessible, production-backed UI primitives for [kerf](https://github.com/brianwestphal/kerf)
+> applications. Components are plain functions returning `SafeHtml`; the app owns
+> state and wires stable `data-action` hooks once. This file orients an LLM to
+> generate correct, good-looking kerf UI — it is not a catalog to browse.
 
-- [Package guide](./README.md)
-- [AI skill](./ai/skill.md)
-- [Component contract](./docs/component-contract.md)
-- [Web Awesome theme contract](./docs/webawesome-theme.md)
-- [Accessibility and keyboard contracts](./docs/accessibility.md)
-- [Design philosophy](./docs/design-philosophy.md)
-- [Apple HIG translation](./docs/apple-hig.md)
-- [UX catalog](./docs/ux-demo.md)
+```bash
+npm install kerfjs @kerfjs/ui   # kerfjs is a peer; Web Awesome is an optional peer
+```
 
-The UX catalog is a category-grouped master/detail review surface with a focused route for every public visual component plus composition demos. Its collapsible ecosystem section also lists all 70 free Web Awesome 3.12 components, each with a focused themed route. Related entries use one grouped `Uses` / `Used by` selector across both sets; the shell, display preferences, and selected component share one semantic theme.
+Import each component from its own subpath (`@kerfjs/ui/list-item`, `@kerfjs/ui/toolbar`,
+…); the browser build pulls that component's reachable CSS automatically, so do not
+maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 
-Public components: `LucideIcon`, `Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `SegmentedControl`, `MenuItem`, `MenuHeader`, `ResizableRegion`, `wireResizableRegions`, `AppTab`, `TabBar`, `wireTabBars`, `reorderTabs`, `PageHeader`, `LoadingSpinner`, `Select`, `StateBanner`, `EmptyState`, `DialogHeader`, and `ValueTable`. `SegmentedControl` is controlled and supports toolbar, rounded-rectangle, and pill presentations with native pressed buttons in sequential Tab order. Semantic state palettes are opinionated, Web Awesome-compatible, and overridable globally, by tone, or per instance.
+## How to build a screen (retrieval order)
 
-Import visual components from explicit JavaScript subpaths. A CSS-aware browser bundler selects generated wrappers that bring in the foundation, the component CSS, and styles for reachable UI subcomponents; unrelated CSS stays out. The root barrel and `@kerfjs/ui/unstyled` are CSS-free; use `styles.css` with the root barrel only when the complete layer is intentional. Manual CSS exports remain available for custom pipelines, and application overrides follow package styles in the cascade. `@kerfjs/ui/webawesome.css` is an optional CSS-only theme for Web Awesome's free components; it includes Web Awesome's base stylesheet, registers no elements, and remains overridable through public `--wa-*` tokens. CSS, its generated browser wrappers, and `@kerfjs/ui/select/register` are the declared side effects. `kerfjs` is an external peer. The Web Awesome peer is optional and needed for its components. `wireTabBars` includes proximity-based horizontal edge autoscroll during same-bar drag reordering.
+1. **Pick the component from the interface need**, not by appearance — read
+   [component-selection.md](./docs/component-selection.md) (the problem→component
+   matrix, with imports, wiring, ownership, and alternatives).
+2. **Get exact signatures before emitting code** — read
+   [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) (real prop names,
+   callback shapes, disposer return types).
+3. **For exhaustive, structured facts** (ids, exports, variants, `publicClasses`,
+   relationships, side effects) load the
+   [Machine-readable component catalog](./ai/component-catalog.json) — the
+   canonical checked-in source; its schema is alongside it.
+4. **Apply the rules below and in** [skill.md](./ai/skill.md).
 
-The Web Awesome theme renders Tooltip and Popover without pointer arrows by default. Restore them only when the anchor relationship needs the pointer, using `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or one popover's public `--arrow-size`; `without-arrow` remains available for explicit local intent.
+## Core rules (do the right thing)
 
-Web Awesome catalog coverage means themed and inspectable, not preferred. Consider Popup when it replaces custom anchored positioning. Prefer Kerf Select over direct Dropdown/Dropdown Item/Select/Option composition, SegmentedControl over Button Group, TabBar or SegmentedControl over Web Awesome Tabs, LucideIcon over Web Awesome Icon, and ResizableRegion over Split Panel. ResizableRegion carries Hot Sheet 2's 1px separator plus hover/focus grip. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame.
+- **Reach for the primitive, not for CSS.** The package is built to look right
+  *unstyled*. Before adding `padding`, `margin`, `width`, `height`, `border`,
+  `background`, a wrapper card, or a decoration, check whether the component, the
+  pane, or the content-item already owns it — it almost always does. Prefer a
+  component prop or a `--kui-*` token; write CSS only for genuinely new structure,
+  and then only join a component's documented `publicClasses` (never reach in by
+  tag/id/attribute or an unlisted class).
+- **Never double-inset.** A `.kui-pane` has no padding; its `.kui-content` children
+  own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
+  container padding on top of a content-item's own margin — pick one owner. Use
+  `.kui-content` for 24px major vertical rhythm.
+- **Trust the defaults.** Render a control at its natural size and color (a
+  `LucideIcon` is 24px); if it looks wrong, fix the surrounding layout, not the
+  control. Never force a component's width/height to size it — that leaves a halo
+  or a stretched oval.
+- **Toolbars hold only `ToolbarText` and `ToolbarControlGroup`.** Never put a bare
+  button, input, link, or loose markup in a `leading`/`center`/`trailing` zone.
+  Wrap every control — `SegmentedControl`, `Select`, a collapsible
+  `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. A
+  toolbar popup menu is a `single` `ToolbarControlGroup` around a `wa-dropdown`
+  (its `slot="trigger"` `wa-button` is the toolbar button, kept under
+  `data-morph-skip-children`).
+- **`PanelHeader` is *the* panel/dialog/page heading.** A plain toolbar with an
+  optional bordered icon group, an extra-large `ToolbarText` title, the trailing
+  controls you pass, and an optional subtitle below — do not hand-build a heading
+  row or restyle a toolbar into one.
+- **Space by the five-step scale, by relationship not by eye.** `0`
+  `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
+  group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing
+  regions). 12px/32px are off-scale exceptions.
+- **Panes share one child-owned geometry.** Sidebars, main areas, inspectors, and
+  dialogs all use an unpadded `.kui-pane` (optional `.kui-pane__toolbar`, one
+  scrolling `.kui-pane__content`, optional `.kui-pane__footer`). A visible pane owns
+  its collapse control; a hidden pane's restore moves to the adjacent main
+  toolbar's matching edge — no icon-only rail. Keep one scroll owner per region.
+- **State and behavior live in the app.** Components take semantic `data-action`
+  strings and controlled values; wire them once with `delegate()`/`delegateActions()`
+  or the disposer-returning `wire…` helpers, and own domain copy, transport, and
+  policy in a thin adapter. Every element must earn its place — cut chrome, labels,
+  and readouts that do not help a person decide or act.
+- **App state is domain/persisted; helpers own only ephemeral mechanics.** Keep
+  navigation stacks, tab selection and order, pane sizes, and `collapsed`/`expanded`
+  disclosure flags in the app — they are data or persisted layout, and the app reads
+  them to render. The `wire…` helpers own the *ephemeral* parts: `wireNavStack` the
+  push/pop animation, `wireTabBars` the overflow autoscroll and drag preview,
+  `wireResizableRegions` the live drag preview; they report committed changes via
+  callbacks. The one richer case is `wireTokenSearchFields`, which manages the
+  collapsible field's expand/collapse/focus by default (on, per-behavior opt-out) and
+  exposes the `expanded` signal on its handle — bind it in render or hand in your own
+  via `collapsible.signals`. Do not hand-roll open/collapse/focus that helper
+  provides; but do keep a plain disclosure toggle (a one-line boolean the app already
+  renders from) in the app. For real-app composition it also offers a focusout
+  keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn`,
+  so a sibling suggestions/date popover does not collapse an empty field), opt-in
+  atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via
+  `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an
+  `onEdit({id, editor})` input callback — so the app can drop its own keydown/input
+  boilerplate while still owning parsing and controlled token state.
+- **Placeholder loading state, don't rebuild it.** For a value or component that is
+  still loading, set `placeholder` on the component (`Select`, `ListHeader`,
+  `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`,
+  `AppTab`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
+  slots as subtle **unanimated** skeleton blocks and interactivity disabled, so a
+  parent composes a faithful loading view (e.g. an inspector) without hand-rebuilding
+  markup. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
+  (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
+  `LoadingSpinner` for known busy activity instead.
+
+## Public exports
+
+`LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarText`,
+`PanelHeader`, `ListItem`, `ListActionRow`, `ListHeader`, `SegmentedControl`,
+`Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
+`wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
+`ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
+`LoadingSpinner`, `Skeleton`, `ValueTable`, `ValueTableRow`. Whole-screen layouts (opt-in,
+tree-shakeable, declarative with `wire…` helpers, each with a companion CSS import):
+`NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
+`@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
+shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
++ `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
+`@kerfjs/ui/catalog` is another opt-in shell — a
+`Catalog` component + `wireCatalog` helper for building a component-gallery catalog
+(collapsible category sidebar + preview stage + resources footer) from your own
+entries; controlled/stateless like the layouts. `@kerfjs/ui/webawesome` is a
+type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
+declared side effects.
+
+## Reference
+
+- [skill.md](./ai/skill.md): the full rule set + a common-mistakes table (the shipped AI skill).
+- [design-philosophy.md](./docs/design-philosophy.md): why kerf UI is shaped this way — the decision principles behind the rules above.
+- [layout.md](./docs/layout.md): the pane/content-item geometry, public roles/tokens, and the spacing scale.
+- [component-contract.md](./docs/component-contract.md): what a component owns vs. what the app owns.
+- [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
+- [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
+- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
+- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists).
+- [component-catalog.json](./ai/component-catalog.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts and exact signatures.
+- [README.md](./README.md): package overview and the component subpath table.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@kerfjs/ui",
-  "version": "4.4.1",
+  "version": "5.0.0-beta.10",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
   "author": "Brian Westphal <brian.westphal@bleugris.com>",
-  "homepage": "https://brianwestphal.github.io/kerf/docs/ui-package/",
+  "homepage": "https://brianwestphal.github.io/kerf/docs/component-packages/",
   "repository": {
     "type": "git",
     "url": "https://github.com/brianwestphal/kerf",
@@ -44,6 +44,11 @@
       "browser": "./dist/browser/lucide-icon.js",
       "import": "./dist/lucide-icon.js"
     },
+    "./disclosure-arrow": {
+      "types": "./dist/disclosure-arrow.d.ts",
+      "browser": "./dist/browser/disclosure-arrow.js",
+      "import": "./dist/disclosure-arrow.js"
+    },
     "./toolbar": {
       "types": "./dist/toolbar.d.ts",
       "browser": "./dist/browser/toolbar.js",
@@ -59,15 +64,20 @@
       "browser": "./dist/browser/toolbar-text.js",
       "import": "./dist/toolbar-text.js"
     },
-    "./menu-item": {
-      "types": "./dist/menu-item.d.ts",
-      "browser": "./dist/browser/menu-item.js",
-      "import": "./dist/menu-item.js"
+    "./list-action-row": {
+      "types": "./dist/list-action-row.d.ts",
+      "browser": "./dist/browser/list-action-row.js",
+      "import": "./dist/list-action-row.js"
+    },
+    "./list-item": {
+      "types": "./dist/list-item.d.ts",
+      "browser": "./dist/browser/list-item.js",
+      "import": "./dist/list-item.js"
     },
-    "./menu-header": {
-      "types": "./dist/menu-header.d.ts",
-      "browser": "./dist/browser/menu-header.js",
-      "import": "./dist/menu-header.js"
+    "./list-header": {
+      "types": "./dist/list-header.d.ts",
+      "browser": "./dist/browser/list-header.js",
+      "import": "./dist/list-header.js"
     },
     "./resizable-region": {
       "types": "./dist/resizable-region.d.ts",
@@ -78,11 +88,23 @@
       "types": "./dist/wire-resizable-regions.d.ts",
       "import": "./dist/wire-resizable-regions.js"
     },
+    "./device-class": {
+      "types": "./dist/device-class.d.ts",
+      "import": "./dist/device-class.js"
+    },
     "./app-tab": {
       "types": "./dist/app-tab.d.ts",
       "browser": "./dist/browser/app-tab.js",
       "import": "./dist/app-tab.js"
     },
+    "./catalog": {
+      "types": "./dist/catalog.d.ts",
+      "import": "./dist/catalog.js"
+    },
+    "./wire-catalog": {
+      "types": "./dist/wire-catalog.d.ts",
+      "import": "./dist/wire-catalog.js"
+    },
     "./tab-bar": {
       "types": "./dist/tab-bar.d.ts",
       "browser": "./dist/browser/tab-bar.js",
@@ -92,10 +114,37 @@
       "types": "./dist/wire-tab-bars.d.ts",
       "import": "./dist/wire-tab-bars.js"
     },
-    "./page-header": {
-      "types": "./dist/page-header.d.ts",
-      "browser": "./dist/browser/page-header.js",
-      "import": "./dist/page-header.js"
+    "./nav-stack": {
+      "types": "./dist/nav-stack.d.ts",
+      "import": "./dist/nav-stack.js"
+    },
+    "./wire-nav-stack": {
+      "types": "./dist/wire-nav-stack.d.ts",
+      "import": "./dist/wire-nav-stack.js"
+    },
+    "./split-view": {
+      "types": "./dist/split-view.d.ts",
+      "import": "./dist/split-view.js"
+    },
+    "./workbench": {
+      "types": "./dist/workbench.d.ts",
+      "import": "./dist/workbench.js"
+    },
+    "./collapsible-panel": {
+      "types": "./dist/collapsible-panel.d.ts",
+      "import": "./dist/collapsible-panel.js"
+    },
+    "./wire-sidebar": {
+      "types": "./dist/wire-sidebar.d.ts",
+      "import": "./dist/wire-sidebar.js"
+    },
+    "./tab-scaffold": {
+      "types": "./dist/tab-scaffold.d.ts",
+      "import": "./dist/tab-scaffold.js"
+    },
+    "./wire-tab-scaffold": {
+      "types": "./dist/wire-tab-scaffold.d.ts",
+      "import": "./dist/wire-tab-scaffold.js"
     },
     "./loading-spinner": {
       "types": "./dist/loading-spinner.d.ts",
@@ -107,15 +156,33 @@
       "browser": "./dist/browser/select.js",
       "import": "./dist/select.js"
     },
+    "./skeleton": {
+      "types": "./dist/skeleton.d.ts",
+      "browser": "./dist/browser/skeleton.js",
+      "import": "./dist/skeleton.js"
+    },
     "./segmented-control": {
       "types": "./dist/segmented-control.d.ts",
       "browser": "./dist/browser/segmented-control.js",
       "import": "./dist/segmented-control.js"
     },
+    "./token-search-field": {
+      "types": "./dist/token-search-field.d.ts",
+      "browser": "./dist/browser/token-search-field.js",
+      "import": "./dist/token-search-field.js"
+    },
+    "./wire-token-search-fields": {
+      "types": "./dist/wire-token-search-fields.d.ts",
+      "import": "./dist/wire-token-search-fields.js"
+    },
     "./select/register": {
       "types": "./dist/select-register.d.ts",
       "import": "./dist/select-register.js"
     },
+    "./webawesome": {
+      "types": "./dist/webawesome.d.ts",
+      "import": "./dist/webawesome.js"
+    },
     "./state-banner": {
       "types": "./dist/state-banner.d.ts",
       "browser": "./dist/browser/state-banner.js",
@@ -126,10 +193,10 @@
       "browser": "./dist/browser/empty-state.js",
       "import": "./dist/empty-state.js"
     },
-    "./dialog-header": {
-      "types": "./dist/dialog-header.d.ts",
-      "browser": "./dist/browser/dialog-header.js",
-      "import": "./dist/dialog-header.js"
+    "./panel-header": {
+      "types": "./dist/panel-header.d.ts",
+      "browser": "./dist/browser/panel-header.js",
+      "import": "./dist/panel-header.js"
     },
     "./value-table": {
       "types": "./dist/value-table.d.ts",
@@ -140,55 +207,80 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./foundation.css": "./src/foundation.css",
-    "./webawesome.css": "./src/webawesome.css",
-    "./styles.css": "./src/styles.css",
-    "./lucide-icon.css": "./src/lucide-icon.css",
-    "./toolbar.css": "./src/toolbar.css",
-    "./toolbar-control-group.css": "./src/toolbar-control-group.css",
-    "./toolbar-text.css": "./src/toolbar-text.css",
-    "./menu-item.css": "./src/menu-item.css",
-    "./menu-header.css": "./src/menu-header.css",
-    "./resizable-region.css": "./src/resizable-region.css",
-    "./app-tab.css": "./src/app-tab.css",
-    "./tab-bar.css": "./src/tab-bar.css",
-    "./page-header.css": "./src/page-header.css",
-    "./loading-spinner.css": "./src/loading-spinner.css",
-    "./select.css": "./src/select.css",
-    "./segmented-control.css": "./src/segmented-control.css",
-    "./state-banner.css": "./src/state-banner.css",
-    "./empty-state.css": "./src/empty-state.css",
-    "./dialog-header.css": "./src/dialog-header.css",
-    "./value-table.css": "./src/value-table.css",
+    "./foundation.css": "./dist/styles/foundation.css",
+    "./layout.css": "./dist/styles/layout.css",
+    "./webawesome.css": "./dist/styles/webawesome.css",
+    "./styles.css": "./dist/styles/styles.css",
+    "./lucide-icon.css": "./dist/styles/lucide-icon.css",
+    "./disclosure-arrow.css": "./dist/styles/disclosure-arrow.css",
+    "./toolbar.css": "./dist/styles/toolbar.css",
+    "./toolbar-control-group.css": "./dist/styles/toolbar-control-group.css",
+    "./toolbar-text.css": "./dist/styles/toolbar-text.css",
+    "./list-action-row.css": "./dist/styles/list-action-row.css",
+    "./list-item.css": "./dist/styles/list-item.css",
+    "./list-header.css": "./dist/styles/list-header.css",
+    "./resizable-region.css": "./dist/styles/resizable-region.css",
+    "./app-tab.css": "./dist/styles/app-tab.css",
+    "./catalog.css": "./dist/styles/catalog.css",
+    "./tab-bar.css": "./dist/styles/tab-bar.css",
+    "./nav-stack.css": "./dist/styles/nav-stack.css",
+    "./split-view.css": "./dist/styles/split-view.css",
+    "./workbench.css": "./dist/styles/workbench.css",
+    "./collapsible-panel.css": "./dist/styles/collapsible-panel.css",
+    "./tab-scaffold.css": "./dist/styles/tab-scaffold.css",
+    "./loading-spinner.css": "./dist/styles/loading-spinner.css",
+    "./select.css": "./dist/styles/select.css",
+    "./skeleton.css": "./dist/styles/skeleton.css",
+    "./segmented-control.css": "./dist/styles/segmented-control.css",
+    "./token-search-field.css": "./dist/styles/token-search-field.css",
+    "./state-banner.css": "./dist/styles/state-banner.css",
+    "./empty-state.css": "./dist/styles/empty-state.css",
+    "./panel-header.css": "./dist/styles/panel-header.css",
+    "./value-table.css": "./dist/styles/value-table.css",
     "./ai/*": "./ai/*",
     "./docs/*": "./docs/*"
   },
   "files": [
     "dist",
-    "src/*.css",
     "ai",
     "docs",
+    "ux-demo/recipes",
     "llms.txt",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup && node ../scripts/clean-dist-output.mjs dist && node scripts/build-browser-entries.mjs",
+    "build": "tsup && node ../scripts/clean-dist-output.mjs dist && node scripts/build-css.mjs && node scripts/build-browser-entries.mjs",
     "dev": "npm run build && vite --config ux-demo/vite.config.ts",
     "demo:build": "npm run build && vite build --config ux-demo/vite.config.ts && node scripts/check-demo-bundle.mjs",
     "demo:serve": "vite preview --config ux-demo/vite.config.ts",
-    "lint": "eslint src tests ux-demo --max-warnings 0",
+    "format:css": "prettier --write \"src/**/*.css\" \"ux-demo/**/*.css\"",
+    "check:format": "prettier --check \"src/**/*.css\" \"ux-demo/**/*.css\"",
+    "catalog:sync": "node scripts/sync-component-catalog.mjs",
+    "check:catalog": "node scripts/sync-component-catalog.mjs --check && node scripts/check-component-catalog.mjs",
+    "check:recipes": "node scripts/check-recipes.mjs",
+    "check:ai-regressions": "node scripts/check-ai-regressions.mjs && node scripts/audit-ai-regression-results.mjs",
+    "check:ai-signatures": "node scripts/sync-ai-public-signatures.mjs --check",
+    "ai:signatures:sync": "npm run build && node scripts/sync-ai-public-signatures.mjs",
+    "ai:regressions:compile": "node scripts/compile-ai-regression-response.mjs",
+    "ai:regressions:prepare": "node scripts/prepare-ai-regression.mjs",
+    "ai:regressions:record": "node scripts/record-ai-regression-run.mjs",
+    "ai:regressions:score": "node scripts/score-ai-regression.mjs",
+    "check:guidance": "node scripts/check-decision-guidance.mjs",
+    "lint": "eslint src tests ux-demo docs/examples --max-warnings 0",
     "typecheck": "node node_modules/typescript7/bin/tsc --noEmit",
     "test": "npm run test:unit && npm run test:bundle",
     "test:unit": "vitest run tests/unit --coverage",
     "test:bundle": "npm run build && vitest run tests/bundle",
+    "test:consumer-types": "npm run build && node node_modules/typescript7/bin/tsc -p tests/consumer-types/webawesome/tsconfig.json",
     "test:e2e": "npm run demo:build && playwright test",
-    "check": "npm run lint && npm run typecheck && npm test && npm run demo:build && npm pack --dry-run",
-    "prepublishOnly": "npm run check"
+    "check": "npm run check:format && npm run check:catalog && npm run check:recipes && npm run check:guidance && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm pack --dry-run",
+    "prepublishOnly": "npm run check",
+    "design-templates:build": "node scripts/build-design-templates.mjs"
   },
   "peerDependencies": {
     "@awesome.me/webawesome": "^3.12.0",
-    "kerfjs": "^4.0.0",
+    "kerfjs": "^5.0.0-0",
     "lucide": "^1.43.0"
   },
   "peerDependenciesMeta": {
@@ -204,11 +296,14 @@
     "@typescript-eslint/eslint-plugin": "^8.65.0",
     "@typescript-eslint/parser": "^8.65.0",
     "@vitest/coverage-v8": "4.1.11",
+    "domotion-svg": "^0.29.0",
     "esbuild": "^0.25.0",
     "eslint": "^10.8.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "happy-dom": "^20.9.0",
     "lucide": "1.43.0",
+    "postcss": "^8.5.28",
+    "prettier": "^3.9.6",
     "tsup": "^8.3.0",
     "typescript": "^6.0.3",
     "typescript7": "npm:typescript@^7.0.2",

package/ux-demo/recipes/app-shell.tsx

@@ -0,0 +1,32 @@
+import '@kerfjs/ui/layout.css';
+import './recipes.css';
+
+import { ListHeader } from '@kerfjs/ui/list-header';
+import { ListItem } from '@kerfjs/ui/list-item';
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { ResizableRegion } from '@kerfjs/ui/resizable-region';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
+import { ToolbarText } from '@kerfjs/ui/toolbar-text';
+import { ValueTable, ValueTableRow } from '@kerfjs/ui/value-table';
+import { signal } from 'kerfjs';
+import { Bell, Folder, Inbox, Settings } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const selected = signal('inbox');
+  const navigationSize = signal(224);
+  const inspectorSize = signal(240);
+  const responsivePane = signal<'content' | 'navigation' | 'inspector'>('content');
+  const render = () => <section class="kui-recipe recipe-shell kui-recipe__surface kui-layout" data-recipe="recipe-app-shell" data-responsive-pane={responsivePane.value}>
+    <Toolbar label="Atlas workspace" leading={<ToolbarControlGroup appearance="borderless" single><ToolbarText text="Atlas" /></ToolbarControlGroup>} trailing={<div class="recipe-shell__toolbar-actions"><ToolbarControlGroup className="recipe-shell__responsive-controls" appearance="borderless" label="Workspace panes"><button type="button" aria-label="Show navigation" aria-controls="recipe-shell-navigation" aria-pressed={String(responsivePane.value === 'navigation')} data-action="recipe-action" data-recipe-command="show-navigation"><LucideIcon icon={Folder} name="folder" /></button><button type="button" aria-label="Show content" aria-controls="recipe-shell-content" aria-pressed={String(responsivePane.value === 'content')} data-action="recipe-action" data-recipe-command="show-content"><LucideIcon icon={Inbox} name="inbox" /></button><button type="button" aria-label="Show inspector" aria-controls="recipe-shell-inspector" aria-pressed={String(responsivePane.value === 'inspector')} data-action="recipe-action" data-recipe-command="show-inspector"><LucideIcon icon={Settings} name="settings" /></button></ToolbarControlGroup><ToolbarControlGroup appearance="borderless" label="Workspace controls"><button type="button" aria-label="Notifications" data-action="recipe-action" data-recipe-command="notify"><LucideIcon icon={Bell} name="bell" /></button><button type="button" aria-label="Settings" data-action="recipe-action" data-recipe-command="settings"><LucideIcon icon={Settings} name="settings" /></button></ToolbarControlGroup></div>} />
+    <div class="recipe-shell__body">
+      <div id="recipe-shell-navigation" class="recipe-shell__nav-region"><ResizableRegion id="recipe-navigation" label="Navigation" size={navigationSize.value} min={180} max={320}><aside class="recipe-shell__nav kui-pane"><ListHeader label="Workspace" /><nav class="recipe-shell__nav-list kui-pane__content kui-content" aria-label="Workspace"><section><ListItem action="recipe-action" itemId="inbox" label="Inbox" icon={<LucideIcon icon={Inbox} name="inbox" />} selected={selected.value === 'inbox'} /><ListItem action="recipe-action" itemId="projects" label="Projects with a deliberately wrapping title" icon={<LucideIcon icon={Folder} name="folder" />} selected={selected.value === 'projects'} multiline /></section></nav></aside></ResizableRegion></div>
+      <main id="recipe-shell-content" class="recipe-shell__main kui-pane"><PanelHeader title={selected.value === 'inbox' ? 'Inbox triage' : 'Active projects'} titleId="recipe-shell-main-title" actions={<button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="new">New task</button>} /><div class="recipe-shell__main-body kui-pane__content kui-content"><p class="kui-recipe__ownership kui-content-item">Recipe owns pane geometry and one scroll owner per pane. The app owns routing, data, pane visibility, sizes, and persistence.</p><div class="recipe-shell__cards">{['Release accessibility audit', 'Prepare tablet navigation', 'Review stale-data states', 'Confirm package boundaries'].map((title) => <article class="recipe-shell__card kui-content-item"><strong>{title}</strong><p class="kui-recipe__muted">Assigned to the interface systems team · due this week</p></article>)}</div></div></main>
+      <div id="recipe-shell-inspector" class="recipe-shell__inspector-region"><ResizableRegion id="recipe-inspector" label="Inspector" size={inspectorSize.value} min={200} max={360} edge="start"><aside class="recipe-shell__inspector kui-pane"><PanelHeader title="Inspector" titleId="recipe-shell-inspector-title" /><div class="recipe-shell__inspector-body kui-pane__content kui-content"><ValueTable label="Selected task"><ValueTableRow label="Status" value="In review" /><ValueTableRow label="Owner" value="Mara Chen" /><ValueTableRow label="Priority" value="High" /></ValueTable></div></aside></ResizableRegion></div>
+    </div>
+  </section>;
+  return { render, action(command, element) { const pane = command.match(/^show-(navigation|content|inspector)$/)?.[1] as typeof responsivePane.value | undefined; if (pane) responsivePane.value = pane; const id = element.dataset.itemId; if (id) selected.value = id; announce(id ? `Opened ${id}` : pane ? `Showing ${pane}` : command === 'new' ? 'New task requested' : `${command} requested`); }, resize(id, size) { if (id === 'recipe-navigation') navigationSize.value = size; if (id === 'recipe-inspector') inspectorSize.value = size; announce(`${id} resized to ${size}px`); } };
+};

package/ux-demo/recipes/collapsible-sidebar.tsx

@@ -0,0 +1,100 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/collapsible-panel.css';
+import './recipes.css';
+
+import { CollapsiblePanel, CollapsiblePanelToggle } from '@kerfjs/ui/collapsible-panel';
+import { deviceClass } from '@kerfjs/ui/device-class';
+import { ListHeader } from '@kerfjs/ui/list-header';
+import { ListItem } from '@kerfjs/ui/list-item';
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
+import { ToolbarText } from '@kerfjs/ui/toolbar-text';
+import { type SidebarStorage, wireSidebar } from '@kerfjs/ui/wire-sidebar';
+import { signal } from 'kerfjs';
+import { Bell, Folder, Inbox, Users } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+const RAIL_ACTION = 'recipe-sidebar-rail';
+const DRAWER_ACTION = 'recipe-sidebar-drawer';
+
+/**
+ * A memory-backed store so the recipe demonstrates the persistence hook without
+ * writing to the shared `localStorage` the catalog page runs in.
+ */
+function memoryStorage(): SidebarStorage {
+  const map = new Map<string, string>();
+  return { getItem: (key) => map.get(key) ?? null, setItem: (key, value) => { map.set(key, value); } };
+}
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const selected = signal('inbox');
+  const railCollapsed = signal(false);
+  const drawerCollapsed = signal(true);
+  const storage = memoryStorage();
+  // A shared window-backed device class: when the viewport is compact the wire
+  // switches the rail/drawer to a dismissable overlay presentation.
+  const device = deviceClass();
+
+  const railToggle = (inPanel: boolean) => <CollapsiblePanelToggle side="left" collapsed={railCollapsed.value} action={RAIL_ACTION} panelId="sidebar-rail" label={railCollapsed.value ? 'Show navigation' : 'Hide navigation'} className={inPanel ? '' : 'recipe-collapsible-sidebar__reveal'} />;
+  const drawerToggle = () => <CollapsiblePanelToggle side="bottom" collapsed={drawerCollapsed.value} action={DRAWER_ACTION} panelId="sidebar-console" label={drawerCollapsed.value ? 'Show activity' : 'Hide activity'} />;
+
+  const render = () => <section class="kui-recipe recipe-collapsible-sidebar kui-recipe__surface" data-recipe="recipe-collapsible-sidebar" data-rail-collapsed={String(railCollapsed.value)} data-drawer-collapsed={String(drawerCollapsed.value)}>
+    <CollapsiblePanel id="sidebar-rail" side="left" size={232} collapsed={railCollapsed.value} label="Workspace navigation" className="recipe-collapsible-sidebar__rail kui-pane">
+      <div class="recipe-collapsible-sidebar__rail-head">
+        <ToolbarText text="Atlas" />
+        <ToolbarControlGroup appearance="borderless" single>{railToggle(true)}</ToolbarControlGroup>
+      </div>
+      <nav class="recipe-collapsible-sidebar__nav kui-pane__content kui-content" aria-label="Workspace">
+        <section>
+          <ListHeader label="Workspace" />
+          <ListItem action="recipe-action" itemId="inbox" label="Inbox" icon={<LucideIcon icon={Inbox} name="inbox" />} trailing={<span>12</span>} selected={selected.value === 'inbox'} />
+          <ListItem action="recipe-action" itemId="projects" label="Projects" icon={<LucideIcon icon={Folder} name="folder" />} selected={selected.value === 'projects'} />
+          <ListItem action="recipe-action" itemId="shared" label="Shared with me" icon={<LucideIcon icon={Users} name="users" />} selected={selected.value === 'shared'} />
+        </section>
+      </nav>
+    </CollapsiblePanel>
+    <main class="recipe-collapsible-sidebar__main kui-pane">
+      <PanelHeader
+        title={selected.value === 'projects' ? 'Projects' : selected.value === 'shared' ? 'Shared with me' : 'Inbox'}
+        titleId="recipe-collapsible-main-title"
+        icon={railToggle(false)}
+        actions={<ToolbarControlGroup appearance="borderless" single>{drawerToggle()}</ToolbarControlGroup>}
+      />
+      <div class="recipe-collapsible-sidebar__body kui-pane__content kui-content">
+        <p class="kui-recipe__ownership kui-content-item">The app owns each panel's <code>collapsed</code> signal, sizes, and content; <code>wireSidebar</code> owns the toggle, focus move/restore, the compact overlay, and persistence.</p>
+        <article class="recipe-collapsible-sidebar__card kui-content-item"><strong>Narrow the window to a compact width</strong><p class="kui-recipe__muted">The rail and drawer become a dismissable overlay: a backdrop, Escape, and a trapped Tab ring, all managed by the wire.</p></article>
+      </div>
+    </main>
+    <CollapsiblePanel id="sidebar-console" side="bottom" size={168} collapsed={drawerCollapsed.value} label="Activity" className="recipe-collapsible-sidebar__drawer kui-pane">
+      <Toolbar label="Activity" divider leading={<ToolbarControlGroup appearance="borderless" single><ToolbarText text="Activity" size="small" /></ToolbarControlGroup>} trailing={<ToolbarControlGroup appearance="borderless" single>{drawerToggle()}</ToolbarControlGroup>} />
+      <div class="recipe-collapsible-sidebar__drawer-body kui-pane__content kui-content">
+        <ul class="recipe-collapsible-sidebar__log">
+          <li><LucideIcon icon={Bell} name="bell" />Deploy finished · 2m ago</li>
+          <li><LucideIcon icon={Bell} name="bell" />Review requested · 9m ago</li>
+        </ul>
+      </div>
+    </CollapsiblePanel>
+  </section>;
+
+  return {
+    render,
+    action(command, element) {
+      const id = element.dataset.itemId;
+      if (id) { selected.value = id; announce(`Opened ${id}`); return; }
+      announce(`${command} requested`);
+    },
+    wire(root) {
+      return wireSidebar(root, {
+        deviceClass: device,
+        storage,
+        panels: [
+          { id: 'sidebar-rail', collapsed: railCollapsed, toggleAction: RAIL_ACTION, storageKey: 'recipe-sidebar-rail' },
+          { id: 'sidebar-console', collapsed: drawerCollapsed, toggleAction: DRAWER_ACTION, storageKey: 'recipe-sidebar-console' },
+        ],
+      });
+    },
+  };
+};