@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.100

package/docs/design/templates.md

@@ -7,15 +7,29 @@ tokens and styles, representative sample data). They're for design review,
 documentation, figma/paste hand-off, and any surface that wants an accurate
 component picture without running the app.
 
+## Coverage
+
+Templated components (each with light + dark variants):
+`ToolbarControlGroup`, `Toolbar`, `ToolbarText`, `List`, `ListItem`, `ListHeader`,
+`ListActionRow`, `ValueTable`, `StateBanner`, `EmptyState`, `Skeleton`,
+`SegmentedControl`, `TabBar`/`AppTab`, and `TokenSearchField`.
+
+Deliberately **not** templated (they don't read as a single static component
+picture): `Select` renders a Web Awesome custom element that needs its runtime
+registered, so it has no faithful static capture; `LucideIcon` and
+`DisclosureArrow` are decorative primitives best seen inside the components that
+use them; `ResizableRegion` and the whole-screen layouts (`NavStack`,
+`SplitView`, `Workbench`, `TabNavigator`) and the `Catalog` shell are
+interaction-/viewport-driven screens rather than component cards — the live UX
+catalog and the app-layouts docs cover those.
+
 ## Layout
 
 ```
 docs/design/templates/
-  panel-header.svg              ← library: every variant, inlined (light)
-  panel-header-dark.svg         ← library: dark theme
-  panel-header/
-    icon-summary-actions.svg    ← one self-contained variant (light)
-    icon-summary-actions-dark.svg ← the same variant, dark theme
+  toolbar.svg                   ← library: every variant, composed (light)
+  toolbar-dark.svg              ← library: dark theme
+  toolbar/
     icon-actions.svg
     icon-actions-dark.svg
     …
@@ -34,13 +48,12 @@ docs/design/templates/
   kerf UI design font stack is system-based, so the picture matches; a viewer
   without those fonts falls back to its own.
 - The **library** files (`<component>.svg` light, `<component>-dark.svg` dark) lay
-  the variants out with captions and embed an inline **copy** of each variant as a
-  positioned nested `<svg>`. Each is fully self-contained and renders everywhere —
-  a browser, an `<img>`, GitHub, or a static rasterizer. (External
-  `<use href="…#id">` and `<image href="…">` references render blank in many SVG
-  viewers, so the library inlines copies instead. Each copy's local ids and
-  domotion font-family names are namespaced so the inlined variants don't collide
-  in the one document; the individual variant files stay individually reusable.)
+  the variants out with captions. The generator writes a temporary HTML page whose
+  `<img>` elements reference the individual variant SVGs, then captures that page
+  with domotion and `--flatten-nested-svg`. The final library is self-contained,
+  contains positioned groups rather than nested `<svg>` elements, and remains
+  reliable in design tools such as Sketch. The individual variant files stay
+  independently reusable.
 
 ## Building
 
@@ -51,15 +64,48 @@ npm run design-templates:build
 This renders each component's real `SafeHtml` (with its CSS subpaths + `foundation.css`
 tokens and representative sample data) into a standalone page and captures it with
 [`domotion-svg`](https://github.com/brianwestphal/domotion)'s `domotion capture`.
+The capture command uses `--flatten-nested-svg`, which converts safely flattenable
+inline SVGs (including component icons) to groups so design tools such as Sketch do
+not have to interpret nested `<svg>` elements.
 `domotion` must be reachable: it resolves `DOMOTION_BIN`, then a local
 `node_modules/.bin/domotion`, then a sibling `../domotion` checkout.
 
+Each manifest entry's `css` list names the stylesheets a template starts from; the
+build expands every component in it through that component's generated browser
+entry (`dist/browser/<name>.js`), which imports every stylesheet the component's
+runtime reaches. A nested component's styles — the `Badge` inside `StateBanner` or
+`ListHeader`, the `Skeleton` inside a placeholder — are therefore loaded exactly as a
+consumer's browser import loads them, instead of depending on a hand-maintained
+list. Run `npm run build` before the template build so those entries exist.
+
 **Keep the templates current as components change.** The variants live in the
 `COMPONENTS` manifest in `scripts/build-design-templates.mjs` — when a component
-gains or changes a presentation combination (e.g. a new `PanelHeader` slot), add
+gains or changes a presentation combination (e.g. a new `Toolbar` slot), add
 or adjust its variant there and re-run the build. Cover the common cases: if a
 component can render with or without an icon, include both.
 
+`npm run check:design-templates` (part of `npm run check`) is an offline gate
+that verifies every component + variant in the manifest has its committed output —
+a light and dark SVG per variant plus the two per-component library files — and
+that no stray template files linger for a removed component. It also rejects any
+variant or library capture that still contains nested `<svg>` elements, guarding
+the Sketch compatibility contract. It does **not**
+re-render (that needs domotion + a browser), so it catches a manifest entry whose
+templates were never generated or a half-regenerated set.
+
+Deeper **visual drift** — a component changed but its template was not regenerated —
+is caught by `npm run check:design-templates:drift`, a CI-only gate (it runs in a
+dedicated macOS browser job, **not** in the offline `npm run check`). The committed
+templates use system-font text, whose layout metrics differ by operating system, so
+macOS is the canonical exact-render environment for both generation and comparison.
+The capture fixture also pins its monospace token to `Courier New`; otherwise
+`ui-monospace` resolves to different fonts on developer and hosted macOS machines.
+The gate regenerates every template into a throwaway directory and fails if any
+regenerated SVG differs from the committed one, after normalizing the bits that
+legitimately vary between runs (XML comments and the auto-minted element ids / font
+names). If it fails, run `npm run design-templates:build` on macOS and commit the
+updated SVGs.
+
 ## Templating your own components
 
 Apps that build on `@kerfjs/ui` can produce the same design templates for their
@@ -70,14 +116,25 @@ starting point and:
    sample data (pass icon/action slots as `SafeHtml`, e.g. `LucideIcon({ … })` or
    `raw('<button …>')` — never plain strings, which kerf escapes).
 2. List the component's CSS (its `@kerfjs/ui` subpaths plus `foundation.css` for
-   tokens and `layout.css`), and any of your own component CSS.
+   tokens and `layout.css`), and any of your own component CSS. Include the CSS of
+   every `@kerfjs/ui` component it renders inside itself (a `Badge`, a `Skeleton`),
+   or expand the list the way `resolveTemplateStyles()` does.
 3. Enumerate the presentation combinations in the per-component manifest.
 4. Capture each variant with `domotion capture <page.html> --selector <css>
-   --text-mode system-font -o <variant>.svg`, once per theme with
+--text-mode system-font --flatten-nested-svg -o <variant>.svg`, once per theme with
    `--color-scheme light` / `--color-scheme dark` (if your components theme with
-   `light-dark()`), then write a light and a dark library file that each embed an
-   inline copy of every variant (namespacing each copy's ids/font-family names so
-   they don't collide) rather than referencing them, so they render everywhere.
+   `light-dark()`).
+5. Build a light and dark HTML library page that references the generated variants
+   with `<img src="./component/variant.svg">`, and capture each page with the same
+   domotion options, including `--flatten-nested-svg`. Let domotion own embedding,
+   id isolation, and flattening instead of hand-assembling SVG markup.
 
 Maintaining these next to the components — and reviewing the captured SVGs on
 every component change — keeps the design source of truth honest.
+
+ListItem templates retain the shared 18px leading icon and 44px row target;
+regenerate both themes and library sheets when that geometry changes. The browser
+pane/sidebar geometry checks cover the resulting 43px icon-label offset from the
+section edge (17px content inset + 18px icon + 8px gap).
+
+For a focused update, pass component names: `npm run design-templates:build -- toolbar`. Omit them to capture all components. Toolbar width variants use the real `wireToolbarVisibility` helper after rendering typed props. The `ListActionRow` "Trailing overflow menu" variant renders a real `trailingMenu` `PopupMenu`. Its trigger is a native button inside Web Awesome's shadow root, and domotion cannot read that button's author styles. A registered trigger would therefore be captured as a raster image, which also stops the library sheet from flattening. The capture instead leaves the PopupMenu unregistered. The template-only `staticPopupMenuTriggerCss` gives the trigger host the geometry `popup-menu.css` gives its `::part(base)` in a row: a 44px-wide box, as tall as the row, with the 16px icon centered. It also hides the closed menu's items. The icon lands at the same position as in a registered capture.

package/docs/design-philosophy.md

@@ -18,26 +18,50 @@ A reference image defines hierarchy, relationships, and intended feel. It does n
 
 ### Continuity is correctness
 
-Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. The default owner is the application: domain data and persisted layout preferences — a navigation stack, a selection, a tab order, a pane size, a `collapsed`/`expanded` disclosure flag — are the app's signals, which it reads to render. A `wire…` helper owns only the *ephemeral mechanics* around that state (a push/pop animation, overflow autoscroll, a live resize preview) and reports committed changes through callbacks. A helper takes over a piece of transient state itself only when hand-rolling that behavior is substantial and error-prone enough to cause real, inconsistent variation across apps — `wireTokenSearchFields`'s collapsible reveal/focus/Escape/blur-collapse is the bar; a one-line boolean toggle is not. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
+Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. The default owner is the application: domain data and persisted layout preferences — a navigation stack, a selection, a tab order, a pane size, a `collapsed`/`expanded` disclosure flag — are the app's signals, which it reads to render. A `wire…` helper owns only the _ephemeral mechanics_ around that state (a push/pop animation, overflow autoscroll, a live resize preview) and reports committed changes through callbacks. A helper takes over a piece of transient state itself only when hand-rolling that behavior is substantial and error-prone enough to cause real, inconsistent variation across apps — `wireTokenSearchFields`'s collapsible reveal/focus/Escape/blur-collapse is the bar; a one-line boolean toggle is not. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
 
 ### Hierarchy precedes decoration
 
-Establish one reading order and one dominant action per decision point. Group first with alignment, spacing, typography, and shared surfaces. A border, fill, badge, or nested card must communicate a real distinction.
+Establish one reading order and one dominant action per decision point. Group first with alignment, spacing, typography, and shared surfaces. A border, fill, badge, or nested card must communicate a real distinction. A divider is chrome too: a line between a pane's own header and its list, or under a toolbar whose content already spaces itself, marks nothing and is dropped (`dividerSides=""`), never padded around. Put a control near where its effect appears — a collapsed drawer's restore beside the drawer, not in a distant top toolbar.
 
 ### Reach for the primitive, not for CSS
 
-The package is designed to look right *unstyled*. A screen built from the
+The package is designed to look right _unstyled_. A screen built from the
 primitives, their props, and the semantic tokens should already read well, so
-custom CSS is the exception. Before adding any `padding`, `margin`, `width`,
+applications do not carry a component-customization stylesheet. Prefer a Kerf
+UI component over a Web Awesome component over a raw HTML tag, using each for
+what it is good at; a `Discouraged` Web Awesome element is reached only through
+the Kerf component that wraps it (`PopupMenu`, `Select`), never rendered
+directly. Before adding any `padding`, `margin`, `width`,
 `height`, `border`, `background`, wrapper card, or decoration, check whether the
 component, the pane, or the content-item already owns it — it almost always does,
 and adding more usually **double-insets** or fights the component (the most common
 mistake). Trust component defaults: render a control at its natural size and color
 and fix the surrounding layout rather than overriding the control. Legitimate
-custom CSS is limited to genuinely new structure, and even then may only join a
-component's documented `publicClasses` or override documented `--kui-*` tokens at a
-real composition boundary — never size, space, or re-skin a primitive by hand, and
-never build a heading, toolbar, card, or pane geometry that a primitive provides.
+CSS for genuinely new structure belongs to the application-owned component that
+renders that structure. It must not select a nested Kerf or Web Awesome component;
+configure those children through props and documented tokens instead. Never size,
+space, or re-skin a primitive by hand, and never build a heading, toolbar, card,
+or pane geometry that a primitive provides.
+
+### Components own their styles; configure, never override
+
+Every component styles only itself. How it looks and sits is configuration —
+typed props and data attributes such as size, density, inset, presentation,
+tone, `dividerSides`, `ToolbarConfig`, and `PaneConfig` — never a stylesheet
+somewhere else reaching into it. When a component must adapt inside another
+(a `PopupMenu` inside a compact `ToolbarControlGroup`, an `AppTab` in a
+segmented `TabBar`), the **child** styles itself in that context, in its own
+stylesheet; the parent keys only its own elements on a child's state
+(`:has(> .kui-select[open])`) and names kerf children by class, not by `wa-*`
+tag. Values a parent provides to its children are custom properties named after
+the parent. A component never writes another component's private variables and
+never puts a hook class on a child's root to restyle it.
+
+The same holds for applications and component packages built on Kerf UI: expose
+configuration on your own components, configure kerf components through their
+props, and treat a missing prop as a component gap to report, not a reason to
+override. `npm run check:css-ownership` enforces this inside the package.
 
 ### Panes share one child-owned geometry
 
@@ -45,21 +69,23 @@ Sidebars, main areas, inspectors, and dialogs use the same unpadded pane. Their
 children own margin, border, background, padding, and radius, so a transparent
 surface occupies exactly the same geometry as a visible one. Major content
 groups use 24px vertical separation; the inside of an item and the gap between
-toolbar groups use 8px. Rows and actions keep 44px targets.
+toolbar groups use 8px. Rows and actions keep 44px targets. Align text to text
+and icons to icons: a title, a row label, and bare prose share one text column,
+and a border is decoration, never the alignment anchor — a bordered surface
+extends to the pane gutter rather than being indented so its border lines up
+with a heading's text.
 
 Use the package composition so the geometry has one owner:
 
 ```tsx
-<aside class="kui-pane">
-  <nav class="kui-pane__content kui-content">
+<Pane element="aside" contentElement="nav" label="Workspace" contentLabel="Workspace pages">
     <section>
-    <ListHeader label="Workspace" />
-    <ListItem action="open" label="Inbox" icon={inboxIcon} />
-    <ListItem action="open" label="Drafts" />
+      <ListHeader label="Workspace" />
+      <ListItem action="open" label="Inbox" icon={inboxIcon} />
+      <ListItem action="open" label="Drafts" />
     </section>
-    <div class="kui-content-item">Panel contents</div>
-  </nav>
-</aside>
+    <ContentItem>Panel contents</ContentItem>
+</Pane>
 ```
 
 Do not pad the pane and then pad every wrapper. That duplicates the geometry
@@ -85,13 +111,23 @@ Use the shortest understandable, recoverable interaction. Avoid modes, dialogs,
 
 Reuse a component when surfaces share its purpose, anatomy, state model, and interaction behavior—not merely its appearance. Components expose semantic actions and explicit variants. Product-specific copy, transport, persistence, and domain states stay in application adapters.
 
+### Words follow one capitalization rule
+
+Inconsistent capitalization reads as unfinished. Kerf follows Apple's
+per-element convention: anything that names a command, control, view, or
+field is title style ("Save Draft", "Workspace Settings"), and anything that
+describes, explains, or reports is sentence style ("Saved just now"). Apply it
+the same way on every screen; see [Writing interface copy](./writing.md).
+
 ### Use a finite vocabulary
 
 Color, type, spacing, radius, elevation, and motion express semantic roles. Prefer package tokens over raw values in consuming code. State is never communicated by color alone.
 
 The default vocabulary is opinionated rather than empty: neutral, brand/info,
-success, warning, and danger provide quiet/normal/loud fills, borders, and
-foregrounds compatible with Hot Sheet 2 and Web Awesome. Consumers may replace
+pop, success, warning, and danger provide quiet/normal/loud fills, borders, and
+foregrounds compatible with Hot Sheet 2 and Web Awesome. Pop is vibrant,
+non-status emphasis for featured, novel, or celebratory content; never use it as
+a success, warning, or danger substitute. Consumers may replace
 the global palette, one semantic role, or one component instance through
 documented custom properties without rewriting component CSS.
 
@@ -102,13 +138,22 @@ separation, very minor air, standard within a group, between homogeneous groups,
 and major between heterogeneous groups. Off-scale values (12px, 32px) are
 deliberate exceptions. See [`layout.md`](layout.md) "Spacing scale".
 
+Empty space also has a job. Keep related controls and content close, leave more
+room between distinct decisions, and let a short form or sparse state occupy
+only the width it needs. Align neighboring content edges before adjusting gaps.
+Do not fill an open area with a card, divider, label, or evenly stretched row
+merely to use the space. Give the pane, surface, and child layout one owner each;
+avoid a negative margin or spacer that only cancels an inset another component
+already provides. Recheck that rhythm with side rails open and at narrow and
+intermediate widths.
+
 ### Responsive design reprioritizes
 
 Protect primary content, readable type, recognizable icons, and usable targets. Relocate secondary information before compressing it below a usable scale. Keep one clear scroll owner per region and test narrow, wide, zoomed, and intermediate layouts.
 
 ### Production behavior is proof
 
-The catalog uses the same exports and CSS consumers receive. Its category-grouped master/detail layout keeps one component under review at a time, and its decorative shell consumes the same semantic palette as the component stage. Every public visual primitive has a focused route; composition demos declare their direct dependencies so reviewers can navigate both `Uses` and `Used by` relationships. Every enabled control works. Demonstrations cover meaningful variants and adverse states with realistic enough content to expose wrapping, clipping, density, and state-transition defects.
+The catalog uses the same exports and CSS consumers receive. Its category-grouped master/detail layout keeps one component under review at a time, and its decorative shell consumes the same semantic palette as the component stage. Every public visual primitive has a focused route; composition demos declare their direct dependencies so reviewers can navigate both `Uses` and `Used By` relationships. Every enabled control works. Demonstrations cover meaningful variants and adverse states with realistic enough content to expose wrapping, clipping, density, and state-transition defects.
 
 ### Be platform-fluent, not platform-costumed
 

package/docs/device-class.md

@@ -7,7 +7,7 @@ the foundation the app/dialog layouts build on (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 
 ```ts
-import { deviceClass } from '@kerfjs/ui/device-class';
+import { deviceClass } from "@kerfjs/ui/device-class";
 
 const device = deviceClass(); // ReadonlySignal<DeviceClass>
 
@@ -19,14 +19,14 @@ effect(() => {
 
 ## `DeviceClass`
 
-| Field | Meaning |
-| --- | --- |
-| `size` | `xs-mobile` \| `mobile` \| `tablet` \| `desktop` \| `xl-desktop` |
-| `orientation` | `portrait` \| `landscape` |
+| Field                           | Meaning                                                                    |
+| ------------------------------- | -------------------------------------------------------------------------- |
+| `size`                          | `xs-mobile` \| `mobile` \| `tablet` \| `desktop` \| `xl-desktop`           |
+| `orientation`                   | `portrait` \| `landscape`                                                  |
 | `segments` / `verticalSegments` | viewport segment counts (foldables / dual-screen); `1` on ordinary devices |
-| `handset` | `xs-mobile` or `mobile` |
-| `compact` | "one pane at a time" — a handset or a portrait tablet |
-| `atLeast(size)` | true when the current size is `size` or larger |
+| `handset`                       | `xs-mobile` or `mobile`                                                    |
+| `compact`                       | "one pane at a time" — a handset or a portrait tablet                      |
+| `atLeast(size)`                 | true when the current size is `size` or larger                             |
 
 Reading `device.value` inside an `effect`/`computed` re-runs when the viewport
 crosses a breakpoint, rotates, or changes its segment count. One shared viewport
@@ -50,5 +50,6 @@ pure, DOM-free bucketing core.
 ## Server rendering
 
 Without a DOM, `deviceClass()` resolves to an SSR default (1024×768, landscape,
-one segment) and hydrates to the real class on the client. Override the assumed
+one segment). That signal is a fixed snapshot — there is no hydration step; a
+`deviceClass()` called in the browser reads the real viewport. Override the assumed
 viewport with `deviceClass({ ssr: { width, height } })`.

package/docs/document-baseline.md

@@ -0,0 +1,93 @@
+# Document baseline
+
+Import `@kerfjs/ui/document.css` when an application wants Kerf UI to own its
+document-level defaults:
+
+```ts
+import "@kerfjs/ui/document.css";
+```
+
+```html
+<body>
+  <div id="app" class="kui-app-root"></div>
+</body>
+```
+
+The opt-in stylesheet applies `border-box` sizing to every element and
+pseudo-element, removes the body margin, and gives the body the foundation
+font, foreground, lowered surface, and `1.45` line height. Plain links use the
+semantic `--kui-color-text-link` token with zero selector specificity.
+Native table cells (`th`, `td`) and form controls (`button`, `input`, `select`,
+`textarea`) inherit the surrounding font family, size, and line height through
+zero-specificity selectors. Table headers keep their native bold weight and
+alignment, and application styles can override the baseline.
+
+Native controls also get semantic cursors, again at zero specificity so a
+component's or application's own cursor wins:
+
+- `pointer` on enabled `button`, `a[href]`, `[role="button"]` (unless
+  `aria-disabled="true"`), `summary`, `select`, checkbox / radio / color /
+  file / button / reset / submit inputs, and a `label` wrapping an enabled
+  checkbox or radio;
+- `not-allowed` on disabled `button`, `input`, `select`, and `textarea`, on
+  `[role="button"][aria-disabled="true"]`, and on a disabled `wa-button`'s
+  `base` part (Web Awesome leaves a pointer there);
+- `text` on enabled `textarea` and text-like inputs (`text`, `search`,
+  `email`, `url`, `tel`, `password`, `number`, and untyped).
+
+Applications no longer need their own global cursor policy for native
+controls.
+
+`html`, `body`, and `.kui-app-root` form a definite `height: 100%` chain. Add
+`.kui-app-root` to the one direct mount container of a full-height application
+whose child is a `Workbench`, `SplitView`, `NavStack`, or another percentage-
+height shell. Ordinary document-flow pages can import the baseline without the
+class. Do not put `.kui-app-root` on several sibling containers: each requests
+the full available document height.
+The class sets `height: 100%`, not a viewport minimum; the direct child shell
+must also fill its parent (for example with its `fill` prop). If the host page
+already supplies a definite height, use that host geometry instead.
+
+### Viewport-locked application shell
+
+A shell that fills the whole window (a `Workbench` app such as Hot Sheet) can
+also lock the document to the viewport:
+
+```html
+<body>
+  <div id="app" class="kui-app-root" data-viewport="locked"></div>
+</body>
+```
+
+With `data-viewport="locked"` on a `.kui-app-root` that is a direct child of
+`body`, `html`, `body`, and the root take `height: 100dvh` and
+`overflow: clip`:
+
+- The **dynamic** viewport height tracks the visible area as mobile browser
+  toolbars show and hide (iOS Safari, WKWebView), so the root is never taller
+  than what the person can see.
+- `overflow: clip` (rather than `hidden`) leaves the document with no scroll
+  container at all. Neither the person, nor `scrollIntoView()`, nor focus can
+  leave the page scrolled: only the shell's `Pane`s scroll.
+
+**On-screen keyboard.** `100dvh` does not shrink for the on-screen keyboard.
+When a field near the bottom takes focus, iOS pans the _visual_ viewport to
+reveal it and pans back when the keyboard closes; because the document itself
+cannot scroll, there is no leftover document offset to restore. A field
+inside a scrolling `Pane` is revealed by that Pane's own scroll. If the
+layout should instead shrink above the keyboard, add
+`interactive-widget=resizes-content` to the viewport meta tag on engines
+that support it. Do not add scroll-restoration handlers for the document:
+the locked document has no scroll position.
+
+Leave the attribute off for document-flow pages and embedded shells; the
+default `height: 100%` chain keeps those scrolling normally.
+
+`kui-app-root` is the public class of the component catalog's
+`document-baseline` entry, so `kerf-ui-doctor` and the
+`kerfjs/ui-public-boundaries` ESLint rule accept it (no KUI-L101 finding).
+
+The stylesheet is intentionally absent from `@kerfjs/ui/styles.css` and every
+component browser import because its global selectors would otherwise change
+consumer documents implicitly. Import it once and load application overrides
+after it.

package/docs/examples/application-ui-profile.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "../../ai/application-ui-profile.schema.json",
+  "schemaVersion": 1,
+  "scope": "workspace",
+  "catalogs": [
+    {
+      "package": "@kerfjs/ui",
+      "selection": {
+        "path": "../../ai/component-catalog.json",
+        "schemaVersion": 1
+      },
+      "composition": {
+        "path": "../../ai/component-composition.json",
+        "schemaVersion": 1
+      }
+    },
+    {
+      "package": "@acme/ui",
+      "composition": {
+        "path": "./component-composition-extension.json",
+        "schemaVersion": 1
+      }
+    }
+  ],
+  "preferences": {
+    "application-shell": {
+      "preferred": "@kerfjs/ui:recipe-app-shell",
+      "rationale": "The workspace uses the standard resizable three-region shell."
+    },
+    "record-inspector": {
+      "preferred": "@acme/ui:inspector",
+      "rationale": "The application-owned inspector maps record policy onto Kerf panel primitives."
+    }
+  },
+  "theme": {
+    "colorScheme": "light",
+    "allowedColorSchemes": ["light", "dark"],
+    "density": "standard",
+    "allowedDensities": ["standard"]
+  },
+  "tokens": {
+    "--kui-color-brand-fill-normal": "oklch(0.62 0.16 255)"
+  },
+  "layout": {
+    "shell": "@kerfjs/ui:recipe-app-shell",
+    "pane": "@kerfjs/ui:pane",
+    "responsiveStrategy": "device-class",
+    "compactNavigation": "nav-stack",
+    "scrollOwnership": "one-per-pane",
+    "spacingScale": "kerf-five-step"
+  },
+  "exceptions": [
+    {
+      "id": "legacy-list-header",
+      "rules": ["KUI-C103"],
+      "target": "src/features/legacy-report/report-list-header.tsx",
+      "rationale": "The legacy report adapter owns disclosure content and its expanded state."
+    }
+  ]
+}

package/docs/examples/command-palette-adapter.tsx

@@ -1,5 +1,7 @@
 import '@kerfjs/ui/layout.css';
 
+import { ContentItem } from '@kerfjs/ui/content-item';
+import { Text } from '@kerfjs/ui/text';
 import { delegate, mount, signal } from 'kerfjs';
 import { delegateActions } from 'kerfjs/actions';
 
@@ -26,17 +28,57 @@ export function mountCommandPaletteAdapter(
   const query = signal('');
   const render = () => {
     const needle = query.value.trim().toLocaleLowerCase();
-    const matches = commands.filter((command) => !needle ||
-      [command.label, ...(command.keywords ?? [])].some((value) => value.toLocaleLowerCase().includes(needle)));
-    return <section class="app-command-palette kui-content" aria-label="Command palette">
-      <div class="kui-content-item"><label for="app-command-query">Search commands</label><input id="app-command-query" type="search" value={query.value} autocomplete="off" data-command-query /></div>
-      <p class="kui-content-item" aria-live="polite">{matches.length} matching commands</p>
-      <ul class="kui-content-item" aria-label="Matching commands">{matches.map((command) => <li><button type="button" data-action="run-command" data-command-id={command.id}>{command.label}</button></li>)}</ul>
-      <footer class="kui-control-cluster kui-content-item" aria-label="Command palette actions">
-        <button type="button" data-action="clear-query">Clear search</button>
-        <button type="button" data-action="close-palette">Close</button>
-      </footer>
-    </section>;
+    const matches = commands.filter(
+      (command) =>
+        !needle ||
+        [command.label, ...(command.keywords ?? [])].some((value) =>
+          value.toLocaleLowerCase().includes(needle),
+        ),
+    );
+    return (
+      <section
+        class="app-command-palette kui-content"
+        aria-label="Command Palette"
+      >
+        <ContentItem>
+          <label for="app-command-query">Search commands</label>
+          <input
+            id="app-command-query"
+            type="search"
+            value={query.value}
+            autocomplete="off"
+            data-command-query
+          />
+        </ContentItem>
+        <Text class="kui-content-item" aria-live="polite">
+          {matches.length} matching commands
+        </Text>
+        <ul class="kui-content-item" aria-label="Matching commands">
+          {matches.map((command) => (
+            <li>
+              <button
+                type="button"
+                data-action="run-command"
+                data-command-id={command.id}
+              >
+                {command.label}
+              </button>
+            </li>
+          ))}
+        </ul>
+        <footer
+          class="kui-control-cluster kui-content-item"
+          aria-label="Command Palette Actions"
+        >
+          <button type="button" data-action="clear-query">
+            Clear Search
+          </button>
+          <button type="button" data-action="close-palette">
+            Close
+          </button>
+        </footer>
+      </section>
+    );
   };
 
   const stopMount = mount(root, render);
@@ -52,12 +94,22 @@ export function mountCommandPaletteAdapter(
     },
     'close-palette': onClose,
   });
-  const stopInput = delegate<HTMLInputElement>(root, 'input', '[data-command-query]', (_event, input) => {
-    query.value = input.value;
-  });
-  const stopEscape = delegate(root, 'keydown', '[data-command-query]', (event) => {
-    if ((event as KeyboardEvent).key === 'Escape') onClose();
-  });
+  const stopInput = delegate<HTMLInputElement>(
+    root,
+    'input',
+    '[data-command-query]',
+    (_event, input) => {
+      query.value = input.value;
+    },
+  );
+  const stopEscape = delegate(
+    root,
+    'keydown',
+    '[data-command-query]',
+    (event) => {
+      if ((event as KeyboardEvent).key === 'Escape') onClose();
+    },
+  );
   let disposed = false;
   return () => {
     if (disposed) return;

package/docs/examples/component-catalog-extension.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "../../ai/component-catalog-extension.schema.json",
+  "schemaVersion": 1,
+  "package": "@acme/ui",
+  "description": "Application-owned components composed with Kerf UI.",
+  "entries": [
+    {
+      "id": "acme-filter-chip",
+      "name": "FilterChip",
+      "kind": "component",
+      "purpose": "A removable application filter displayed inside a token-search workflow.",
+      "useWhen": [
+        "A saved application filter needs a compact visible label and remove action."
+      ],
+      "avoidWhen": [
+        "The value belongs to TokenSearchField's own controlled token collection."
+      ],
+      "publicClasses": ["acme-filter-chip"],
+      "publicTokens": ["--acme-filter-chip-accent"],
+      "uses": ["chip"],
+      "source": "src/filter-chip.tsx",
+      "styleSources": ["src/filter-chip.css"],
+      "demoSource": "ux-demo/demos/filter-chip.tsx",
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "documentation": "docs/filter-chip.md"
+    },
+    {
+      "id": "acme-inspector",
+      "name": "Inspector",
+      "kind": "composition",
+      "purpose": "An application inspector composed from Kerf panel, content, and value primitives.",
+      "useWhen": ["A selected record needs a titled fact-and-action region."],
+      "avoidWhen": ["A ValueTable alone expresses the complete interaction."],
+      "uses": ["acme-filter-chip", "toolbar", "value-table"],
+      "source": "src/inspector.tsx",
+      "demoSource": "ux-demo/demos/inspector.tsx",
+      "geometry": {
+        "margin": "parent",
+        "border": "child",
+        "padding": "child",
+        "notes": [
+          "The embedding pane positions the inspector; Toolbar, ValueTable, and action groups retain their own geometry."
+        ]
+      },
+      "documentation": "docs/inspector.md"
+    }
+  ]
+}