@kerfjs/ui 5.0.0-beta.9 → 5.0.0-beta.90

package/docs/design/templates/value-table.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 492 274" width="492" height="274"><defs><clipPath id="cp0"><rect x="16" y="38" width="460" height="220"/></clipPath><clipPath id="ct1"><rect x="16" y="16" width="460" height="22"/></clipPath><clipPath id="irc2"><rect x="16" y="38" width="460" height="220" rx="0"/></clipPath></defs><rect x="0" y="0" width="492" height="274" rx="0" fill="rgb(255,255,255)"/><text x="16" y="28" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="12" font-weight="600" fill="rgb(110,110,115)">Key/value detail rows</text><g clip-path="url(#cp0)"><g clip-path="url(#irc2)"><clipPath id="svgimg3vclip"><rect x="16" y="38" width="460" height="220"/></clipPath><g clip-path="url(#svgimg3vclip)"><g transform="translate(16 38)"><defs><clipPath id="svgimg3cp0"><rect x="28" y="20" width="404" height="165.2"/></clipPath><clipPath id="svgimg3ov1"><rect x="29" y="21" width="402" height="163.2" rx="11"/></clipPath><clipPath id="svgimg3cp2"><rect x="37" y="32.4" width="46.5" height="18"/></clipPath><clipPath id="svgimg3ct3"><rect x="37" y="32.4" width="46.5" height="18"/></clipPath><clipPath id="svgimg3ct4"><rect x="241.7" y="32.4" width="181.3" height="18"/></clipPath><clipPath id="svgimg3cp5"><rect x="37" y="70" width="24" height="24.2"/></clipPath><clipPath id="svgimg3cp7"><rect x="69" y="73.2" width="90.6" height="18"/></clipPath><clipPath id="svgimg3ct8"><rect x="69" y="73.2" width="90.6" height="18"/></clipPath><clipPath id="svgimg3ct9"><rect x="253.1" y="73.2" width="169.9" height="18"/></clipPath><clipPath id="svgimg3cp10"><rect x="37" y="114" width="50" height="18"/></clipPath><clipPath id="svgimg3ct11"><rect x="37" y="114" width="50" height="18"/></clipPath><clipPath id="svgimg3ct12"><rect x="222.2" y="114" width="200.8" height="18"/></clipPath><clipPath id="svgimg3cp13"><rect x="37" y="154.8" width="83.7" height="18"/></clipPath><clipPath id="svgimg3ct14"><rect x="37" y="154.8" width="83.7" height="18"/></clipPath><clipPath id="svgimg3ct15"><rect x="230.9" y="154.8" width="192.1" height="18"/></clipPath></defs><g clip-path="url(#svgimg3cp0)"><rect x="28" y="20" width="404" height="165.2" rx="12" fill="rgba(0,0,98,0.05)"/><rect x="28.5" y="20.5" width="403" height="164" rx="11.5" fill="none" stroke="rgba(0,0,28,0.18)" stroke-width="1"/></g><g clip-path="url(#svgimg3ov1)"><g clip-path="url(#svgimg3cp2)"><g clip-path="url(#svgimg3ct3)"><text x="37" y="47.39" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(29,29,31)">Status</text></g></g><text x="391.91" y="47.39" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="650" fill="rgb(29,29,31)">Live</text></g><g clip-path="url(#svgimg3ov1)"><g clip-path="url(#svgimg3cp5)"><g color="rgb(29, 29, 31)"><clipPath id="svgimg3svgic6"><rect x="37" y="70.2" width="24" height="24"/></clipPath><g clip-path="url(#svgimg3svgic6)"><g transform="translate(37 70.188)"><path d="M12 15v5s3-.6 4-2c1-1.6 0-5 0-5" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(29, 29, 31)" stroke-width="2px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M4.5 16.5c-1.5 1.3-2 5-2 5s3.7-.5 5-2c.7-.8.7-2.1 0-3a2 2 0 0 0-3 0" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(29, 29, 31)" stroke-width="2px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M9 12a22 22 0 0 1 2-4 13 13 0 0 1 11-6c0 2.7-.8 7.5-6 11a22 22 0 0 1-4 2Z" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(29, 29, 31)" stroke-width="2px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M9 12H4s.5-3 2-4c1.6-1 5 0 5 0" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(29, 29, 31)" stroke-width="2px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></g></g></g></g><g clip-path="url(#svgimg3cp7)"><g clip-path="url(#svgimg3ct8)"><text x="69" y="88.19" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(29,29,31)">Environment</text></g></g><text x="338.63" y="88.19" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="650" fill="rgb(29,29,31)">Production</text><g data-domotion-pseudo-source="blink-pseudo-fragment-v1" data-domotion-pseudo="::before" data-domotion-pseudo-owner="source-fragments"><g><line x1="69" y1="62.5" x2="423" y2="62.5" stroke="rgba(0, 0, 28, 0.18)" stroke-width="1"/></g></g></g><g clip-path="url(#svgimg3ov1)"><g clip-path="url(#svgimg3cp10)"><g clip-path="url(#svgimg3ct11)"><text x="37" y="128.98" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(29,29,31)">Region</text></g></g><text x="349.39" y="128.98" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="650" fill="rgb(29,29,31)">us-east-1</text><g data-domotion-pseudo-source="blink-pseudo-fragment-v1" data-domotion-pseudo="::before" data-domotion-pseudo-owner="source-fragments"><g><line x1="37" y1="103.5" x2="423" y2="103.5" stroke="rgba(0, 0, 28, 0.18)" stroke-width="1"/></g></g></g><g clip-path="url(#svgimg3ov1)"><g clip-path="url(#svgimg3cp13)"><g clip-path="url(#svgimg3ct14)"><text x="37" y="169.78" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(29,29,31)">Last deploy</text></g></g><text x="333.14" y="169.78" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="650" fill="rgb(29,29,31)">2 hours ago</text><g data-domotion-pseudo-source="blink-pseudo-fragment-v1" data-domotion-pseudo="::before" data-domotion-pseudo-owner="source-fragments"><g><line x1="37" y1="143.5" x2="423" y2="143.5" stroke="rgba(0, 0, 28, 0.18)" stroke-width="1"/></g></g></g></g></g></g></g></svg>

package/docs/design/templates.md

@@ -0,0 +1,140 @@
+# Design templates — components as self-contained SVGs
+
+`docs/design/templates/` holds **SVG design templates** for `@kerfjs/ui`
+components: a faithful, self-contained picture of each component in its common
+presentation combinations, captured from the real rendered HTML/CSS (production
+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/
+  toolbar.svg                   ← library: every variant, composed (light)
+  toolbar-dark.svg              ← library: dark theme
+  toolbar/
+    icon-actions.svg
+    icon-actions-dark.svg
+    …
+  toolbar-control-group.svg
+  toolbar-control-group-dark.svg
+  toolbar-control-group/
+    …
+```
+
+- Each **variant** is captured in both themes — `<variant>.svg` (light) and
+  `<variant>-dark.svg` (dark) — a standalone SVG that scales crisply and drops
+  into an `<img>` anywhere. Dark is driven by domotion's `--color-scheme`, which
+  foundation.css's `light-dark()` tokens respond to. Captured with
+  `--text-mode system-font`, so text is emitted as authored `<text>` painted by the
+  viewer's system fonts: real, selectable, and small (no embedded font data). The
+  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. 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
+
+```sh
+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 `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
+own application-level components. Copy `scripts/build-design-templates.mjs` as a
+starting point and:
+
+1. Import your component and render it to a `SafeHtml` string with realistic
+   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. 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 --flatten-nested-svg -o <variant>.svg`, once per theme with
+   `--color-scheme light` / `--color-scheme dark` (if your components theme with
+   `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.

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
@@ -90,8 +116,10 @@ Reuse a component when surfaces share its purpose, anatomy, state model, and int
 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,6 +130,15 @@ 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.

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,42 @@
+# 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.
+
+`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.
+
+`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"
+    }
+  ]
+}