@kerfjs/ui 4.4.1 → 5.0.0-beta.3

package/docs/component-contract.md

@@ -2,13 +2,86 @@
 
 `@kerfjs/ui` components are plain functions that return Kerf `SafeHtml`. They have no component instance or lifecycle.
 
+## Selection boundary
+
+Begin with the [need-first component matrix](./component-selection.md). Reuse a
+primitive only when purpose, anatomy, state, and interaction match. Compose
+public primitives for recurring layout; add a thin application adapter for
+product state and policy; use custom markup when the semantic contract differs.
+Recurring cross-product custom patterns belong in an upstream component or
+recipe request, not in duplicated markup or selectors for undocumented anatomy.
+
+The shipped [`component-catalog.json`](../ai/component-catalog.json) is the
+canonical machine-readable inventory. Its facts are projected into the UX
+catalog deterministically; package checks compare them with runtime exports,
+package delivery paths, Web Awesome's installed manifest, AI guidance, and
+documentation links. Nuanced prose in this contract and the selection guide
+remains authored rather than generated.
+
 ## Ownership boundaries
 
 - Components own semantic markup, stable anatomy, documented variants, ARIA projection, and package CSS hooks.
 - Applications own signals/stores, product copy, domain-state mapping, persistence, routing, permissions, and transport.
 - Actions are `data-action` strings. Wire them at a stable root with `delegate()` or `delegateActions()` and retain the disposer.
 - A reusable component never owns per-instance mutable module state.
-- Consumers style through `--kui-*` semantic tokens and public component classes. Foundation tokens provide opinionated neutral, brand/info, success, warning, and danger fill/border/foreground roles. Stateful components expose local override variables; do not target private descendants when a documented variant or token exists.
+- Consumers style through `--kui-*` semantic tokens and public component classes. Foundation tokens provide opinionated neutral, brand/info, success, warning, and danger fill/border/foreground roles. Stateful components expose local override variables; prefer an equivalent prop or token before writing a selector.
+
+`MenuItem.rootAttributes`, `MenuActionRow.rootAttributes`,
+`MenuHeader.rootAttributes`, and `AppTab.rootAttributes` accept
+application-owned `data-*` metadata without
+adding product fields to the shared API. A `MenuActionRow` trailing action uses
+`trailingActionAttributes`, and a `MenuHeader` action/disclosure uses
+`triggerAttributes`, for `data-*`, native popover target/action attributes, and
+the corresponding `aria-controls`/`aria-haspopup` relationship. These slots do
+not accept roles or component-owned action, selection, disclosure, accessible
+name, disabled, or icon fields. Extension objects are filtered at runtime,
+including case-insensitive rejection of protected `data-*` names, and the
+component writes its protected attributes after the accepted metadata. Typed,
+structurally widened, and JavaScript callers therefore cannot replace its
+contract.
+
+`AppTab.closeIcon` and `ResizableRegion.handleIcon` replace dormant decorative
+glyph content only. They must not contain controls or interactive roles. The
+component continues to own the named close button or focusable separator, and
+`wireTabBars()` / `wireResizableRegions()` continue to own transient behavior
+and disposal.
+
+`MenuItem.trailing`, `MenuActionRow.label`, `MenuActionRow.icon`, and
+`MenuActionRow.trailingActionIcon` are dormant SafeHtml slots. They must not
+contain controls. When a row needs an independently interactive trailing
+region, `MenuActionRow` owns the noninteractive root and the two sibling native
+buttons; the application owns their delegated behavior and controlled state.
+
+### Public CSS anatomy
+
+The `publicClasses` array on each entry in
+[`component-catalog.json`](../ai/component-catalog.json) is the exact supported
+anatomy boundary. A scoped selector may join documented public classes, such as
+`.workspace .kui-toolbar .kui-toolbar__trailing`, when composition-specific
+layout cannot be expressed by a prop or token. A class being public does not
+make copied component markup an invocation or transfer state and accessibility
+ownership to the application.
+
+Do not select a component's descendant by element name, id, attribute alone, or
+an unlisted implementation class. Selectors such as `.kui-state-banner span`,
+`.kui-menu-item [data-state]`, and `.kui-menu-item .local-label` depend on
+private structure. If no prop, token, or cataloged class expresses a recurring
+need, request a supported hook instead of inferring one from rendered markup.
+
+`DisclosureArrow` uses an 18px root-scaled visual by default. Override
+`--kui-disclosure-arrow-size` on the component or its containing scope when a
+consumer needs another size. Kerf `Select` uses a separate Web Awesome expand
+glyph contract, `--kui-disclosure-icon-scale: .5`; changing one contract does
+not implicitly change the other. Direction changes take the shortest rotation
+path; a 180-degree closed-to-open tie uses counterclockwise rotation.
+
+In `MenuHeader` toggle mode, omitting `actionIcon` composes the production
+`DisclosureArrow` and derives its visual direction from `expanded`. The app
+must update that controlled state and reveal or hide real content. Passing a
+custom `actionIcon` replaces the default rather than layering or rotating both.
+The root fills the available inline width after its standard margins. A
+separate action stays at the logical end in its 44px target while the visible
+glyph defaults to 18px through `--kui-menu-header-action-icon-size`.
 
 `StateBanner` exposes instance-level `--kui-state-banner-background`,
 `--kui-state-banner-border`, `--kui-state-banner-foreground`,
@@ -27,11 +100,47 @@ separator with a compact grip that appears on hover or keyboard focus. Override
 `--kui-resizable-region-handle-active-color` on a region when its containing
 surface needs a different contrast level.
 
+`@kerfjs/ui/layout.css` defines one structural model for sidebars, main areas,
+inspectors, and dialogs. `.kui-pane` is unpadded and contains an optional
+toolbar, one scrolling `.kui-pane__content`, and an optional footer.
+`.kui-content` gives major children 24px vertical separation.
+`.kui-content-item` gives one child 8px inline margin, a real 1px border,
+8px padding, and 12px corners; border and background may be transparent without
+changing geometry. `.kui-content-item--pill` selects the 22px radius.
+
+`ToolbarControlGroup` is the unit of toolbar organization, even for dormant
+text. Each group reserves `calc(2px + remify(42px))`, or 44px, with 8px between
+groups and inside items. `MenuHeader` similarly separates its dormant title and
+optional count or badge from its optional 44px action. Use the mutually
+exclusive `count`/`countLabel` pair for non-negative safe-integer section
+quantities; reserve `badge` for non-count `SafeHtml`. Do not concatenate counts
+into the section label. Do not add padding to pane shells,
+double child-owned geometry with wrapper insets, or create competing scroll
+owners. The [layout contract](./layout.md) lists the public roles and tokens.
+
+`DialogHeader` composes its icon and first title line inside a borderless
+`ToolbarControlGroup` in a real top `Toolbar`. Direct `actions` children are
+automatically placed in one contained `ToolbarControlGroup`; use the optional
+localized `actionsLabel` when that group needs an accessible name. Existing
+pre-grouped action content remains layout-compatible, but new callers should
+pass the action children rather than groups. The optional summary is a separate
+row aligned below the title, so it cannot pull the 24px icon or 34px circular
+icon background out of vertical alignment with the 44px action row.
+
+`ValueTable` composes typed `ValueTableRow` entries. A row owns its `dt`/`dd`
+semantics and may receive a leading `SafeHtml` icon. Every row keeps 8px of
+root-scaled padding above and below its content; the shared item-padding token
+continues to own its inline inset. Separators follow the content they introduce:
+8px from either edge for an iconless row, or 40px from the left edge (8px
+padding + 24px icon + 8px gap) and 8px from the right edge for an icon-bearing
+row. Applications own the values, formatting, and whether an icon is decorative
+or meaningfully labeled.
+
 ## Imports and side effects
 
 Every component has an explicit JS and CSS subpath. In CSS-aware browser builds,
 the JS component subpath resolves to a generated wrapper that imports the
-foundation, the component stylesheet, and styles for its reachable UI
+foundation, the compiled component stylesheet from `dist/styles`, and styles for its reachable UI
 subcomponents. The source graph derives those transitive styles at build time;
 an application root never maintains that list. Unused component subpaths and
 their CSS remain unreachable. The root barrel and `@kerfjs/ui/unstyled` stay
@@ -45,19 +154,35 @@ when called and return disposers. CSS, the generated wrappers that make it
 reachable, and the registration module are the package's only declared side
 effects.
 
+Package source styles express root-scaled geometry with `remify(<px>)`; the
+build converts it against the 16px authoring baseline and exposes only ordinary
+`rem` CSS. Literal pixels remain for intentional hairlines, and `em` remains
+explicit when a value is relative to its component's current font size. The UX
+catalog applies the same transform to source CSS under Vite so `npm run dev`
+retains hot module replacement.
+
 `@kerfjs/ui/webawesome.css` is a separate, optional CSS boundary. It imports
 Web Awesome's public base stylesheet and overrides its semantic theme layer to
 match the Kerf/Hot Sheet 2 system. It never imports component JavaScript.
+`import type {} from '@kerfjs/ui/webawesome'` is the matching side-effect-free
+Kerf JSX declaration boundary for every catalog-supported `wa-*` tag.
 Consumers register only the individual Web Awesome modules they render and can
 override `--wa-*` values after the theme import. The shared `--wa-*` values feed
 both Web Awesome controls and Kerf's `--kui-*` foundation aliases, preventing a
 second application palette.
 
+`Select` owns its custom-element reconciliation seam. It gives each slotted
+option icon a stable key and leaves the upgraded Web Awesome-owned slot subtree
+untouched on later Kerf renders. Its custom selected slot is keyed by the
+controlled value so changed selections replace that content. Applications
+should pass ordinary `choices` and `renderSelected` output rather than adding
+their own morph-control attributes.
+
 `kerfjs` is a peer dependency and remains external in every build. Importing a toolbar must not bundle a second Kerf runtime, another UI component, Web Awesome registration, the UX catalog, or development tooling.
 
 ## Extracted versus application-specific
 
-The package set is intentionally domain-neutral: icon rendering, toolbar primitives, controlled segmented choices, menu rows/headers, resizable regions and wiring, controlled reorderable tab bars, headers, loading, select, banners, empty states, dialog headers, and value tables.
+The package set is intentionally domain-neutral: icon rendering, toolbar primitives, controlled segmented choices, a controlled token-chip search field with DOM read/caret helpers, menu rows/headers, resizable regions and wiring, controlled reorderable tab bars, headers, loading, select, banners, empty states, dialog headers, and typed value-table rows.
 
 Keep product adapters outside the package: connection-state maps, ticket empty-state copy, project/terminal/chat tab actions, saved pane sizes, provider or repository models, and application-specific palettes. An adapter may compose these primitives, map product state into their props, and override semantic CSS variables.
 

package/docs/component-selection.md

@@ -0,0 +1,133 @@
+# Component selection and composition
+
+Start with the interface need, not an export name or a screenshot resemblance.
+Use the shipped [`component-catalog.json`](../ai/component-catalog.json) when a
+tool needs exhaustive structured facts; this page remains the concise human
+decision procedure.
+
+1. Search the [Kerf UX catalog](./ux-demo.md) and the supported Web Awesome set.
+2. Reuse a primitive when its purpose, anatomy, state, and interaction match.
+3. Compose primitives for recurring layout. Prefer public props and tokens; when a composition needs a selector, target only classes listed in the catalog's `publicClasses` contract.
+4. Add a thin application adapter for product copy, domain mapping, actions, routing, persistence, permissions, and transport.
+5. Use custom markup only when the semantic contract differs. If the pattern recurs across products, open an upstream component or recipe request.
+
+The application adapter is usually a plain function that maps domain state to
+component props plus stable `data-action` values. It is not a fork of package
+markup or CSS.
+
+## Production recipes
+
+Use the [complete recipe guide](./recipes.md) when several primitives form one
+application boundary:
+
+| Task | Stable catalog route |
+| --- | --- |
+| Desktop application shell | [Catalog](../ux-demo/) · `?component=recipe-app-shell` |
+| Navigation sidebar | [Catalog](../ux-demo/) · `?component=recipe-navigation-sidebar` |
+| Workspace header | [Catalog](../ux-demo/) · `?component=recipe-workspace-header` |
+| Master-detail dialog | [Catalog](../ux-demo/) · `?component=recipe-master-detail-dialog` |
+| Composer form | [Catalog](../ux-demo/) · `?component=recipe-composer-form` |
+| List workspace states | [Catalog](../ux-demo/) · `?component=recipe-list-workspace-states` |
+| Compact toolbar choices and actions | [Catalog](../ux-demo/) · `?component=recipe-compact-toolbar` |
+
+Recipes use public production exports and show ownership boundaries; they are
+copyable reference compositions, not new monolithic components.
+
+## Missing recurring concepts
+
+Kerf UI does not export a command-palette component. Do not invent a package
+command-palette import.
+The typed [application adapter example](./examples/command-palette-adapter.tsx)
+imports `@kerfjs/ui/layout.css`, assigns one `.kui-layout` root and one surface
+inset, and groups its related footer commands with `.kui-control-cluster` while
+the application owns ranking, history, shortcut policy, focus policy,
+availability, actions, and copy. If that concept recurs across products, open
+an upstream component or recipe request.
+
+## Problem-to-component matrix
+
+| Interface need | Use when | Do not use when; nearest alternative | Required wiring | Application owns | Import | Recipe |
+| --- | --- | --- | --- | --- | --- | --- |
+| Icon — `LucideIcon` | A decorative or explicitly labeled Lucide-compatible icon belongs in app UI. | Do not use an icon as the only name of an unfamiliar action; add visible or accessible text. Prefer it over Web Awesome `wa-icon`. | None. | Icon choice and meaningful label. | `@kerfjs/ui/lucide-icon` | [Accessibility](./accessibility.md#shared-rules) |
+| Disclosure indicator — `DisclosureArrow` | A control needs one animated 18px root-scaled visual for open and closed state, including configurable directions or a replacement icon. | Do not use it as the interactive control or accessible name; place it inside the button or control that exposes expanded state. | Pass the controlled `open` state, render it inside the owning control, author replacement icon content facing right before transforms, and override `--kui-disclosure-arrow-size` only when another visual size is required. Direction changes use the shortest rotation path, with counterclockwise chosen for a 180-degree closed-to-open tie. | Open state, interaction, accessible name, size override, replacement glyph, direction choices, and shortest-path rotation. | `@kerfjs/ui/disclosure-arrow` | [Component ownership](./component-contract.md#ownership-boundaries) |
+| Application toolbar — `Toolbar` | Leading identity, optional centered content, and trailing controls form one horizontal app bar. | Do not use it for a page title and one page action; use `PageHeader`. Do not use it as a dialog heading; use `DialogHeader`. | Compose `ToolbarText` and `ToolbarControlGroup` where their contracts fit. | Actions, command availability, responsive relocation, and state. | `@kerfjs/ui/toolbar` | [Toolbar composition](../README.md#component-subpaths) |
+| Toolbar control cluster — `ToolbarControlGroup` | Related toolbar controls need contained, borderless, pressed, or single-control treatment. | Do not use it merely to align unrelated buttons; use toolbar slots or ordinary layout. Web Awesome `wa-button-group` is only for an exceptional grouped-action contract. | Delegate child actions; use `SegmentedControl` for an exclusive choice. | Actions, pressed/expanded state, and policy. | `@kerfjs/ui/toolbar-control-group` | [Component ownership](./component-contract.md#ownership-boundaries) |
+| Toolbar identity text — `ToolbarText` | A toolbar needs large, default, or compact textual identity. | Do not substitute it for document heading semantics; use `PageHeader` or native headings. | None. | Text and responsive priority. | `@kerfjs/ui/toolbar-text` | [Toolbar composition](../README.md#component-subpaths) |
+| Navigation row — `MenuItem` | A pane or navigation area needs a selectable, disabled, dormant-trailing, or multiline action row. | Do not put a control in `trailing`; use `MenuActionRow` when the trailing region must be independently interactive. Use an `<a>` for navigation that must retain link behavior, a native `<button>` for an ordinary action, or implement the complete ARIA menu widget. | Delegate its `data-action`; compose inside a `.kui-content` section. Put domain event/drop metadata in `rootAttributes` rather than adding wrapper markup. | Routing, selection, permissions, copy, action handling, and domain `data-*` values. | `@kerfjs/ui/menu-item` | [Pane geometry](../README.md#pane-and-content-geometry) |
+| Navigation row with trailing action — `MenuActionRow` | A full-width row needs a selectable primary action and an independently focusable trailing action. | Use `MenuItem` when trailing content is dormant metadata. Do not put controls inside the row's `label`, `icon`, or `trailingActionIcon` SafeHtml slots. Do not use `AppTab` outside tablist semantics or `ToolbarControlGroup` outside a toolbar. | Delegate both action strings; update controlled selection and any popover/context-menu state in the app. | Routing, selection, both action policies, domain metadata, and popover/context-menu behavior. | `@kerfjs/ui/menu-action-row` | [Accessibility](./accessibility.md#menuactionrow) |
+| Navigation section heading — `MenuHeader` | A menu section needs a full-width label, semantic count, non-count badge, logical-end action, or real disclosure state. | Do not concatenate counts into `label` or put numeric content in `badge`; use `count` with the localized full phrase in `countLabel`. Do not add a disclosure arrow to navigation that reveals nothing. Do not shrink its 44px action target to the 18px visual. Do not use it as a page or dialog title; use `PageHeader` or `DialogHeader`. | Delegate its optional action; the app controls expanded state and revealed content. Toggle mode supplies `DisclosureArrow` unless `actionIcon` replaces it. Use `triggerAttributes` only for domain `data-*` or a native popover relationship. | Section organization, valid count and localized count label, disclosure state and content, non-count badge content, popover target behavior, and policy. | `@kerfjs/ui/menu-header` | [Pane geometry](../README.md#pane-and-content-geometry) |
+| Application layout composition | A sidebar, main area, inspector, or dialog needs shared toolbar/content/footer and child geometry. | Do not pad the pane shell, wrap child-owned geometry in competing insets, or invent unrelated centered measures. | Use `.kui-pane` and one `.kui-pane__content`; add `.kui-content` and `.kui-content-item` as needed. | Layout hierarchy, reading width, scroll ownership, and responsive relocation. | `@kerfjs/ui/layout.css` | [Pane anatomy](./layout.md#anatomy) |
+| Menu composition | Navigation sections need full-size rows and the same content-item geometry as every other pane. | Do not add sidebar-specific wrapper padding, shrink targets to icon size, nest an interactive trailing control in `MenuItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract. | Compose `MenuHeader`, `MenuItem`, and `MenuActionRow` in `.kui-content`; use `MenuHeader` toggle mode with real controlled content, and use `.kui-content-item` for other surfaces plus a pane footer for toolbar actions. | Information architecture, disclosure content and state, responsive drawer/shell behavior, and token overrides. | `@kerfjs/ui/layout.css` | [Pane geometry](../README.md#pane-and-content-geometry) |
+| Resizable application pane — `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer` | A controlled split pane needs the Kerf separator, collapse state, pointer plus keyboard resizing, or a product-specific decorative grip. | Do not use it for a static two-column layout; use CSS grid. Prefer it over Web Awesome `wa-split-panel` unless that component's distinct API is required. Keep `handleIcon` noninteractive. | Call `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` once and retain its disposer. | Size signal, min/max policy, collapse policy, persistence, and optional decorative handle icon. | `@kerfjs/ui/resizable-region` | [ResizableRegion contract](./accessibility.md#resizableregion) |
+| One application tab — `AppTab` | A controlled app tab needs selection, close, drag, leading/trailing anatomy, safe domain metadata, or a product-specific close glyph. | Do not render it alone or use it for a small settings choice; compose in `TabBar`, or use `SegmentedControl`. Keep `closeIcon` noninteractive. | Compose in `TabBar`; let `wireTabBars` manage interaction. Put only domain `data-*` values in `rootAttributes`. | Tab identity, order, selection, close policy, content, and domain metadata values. | `@kerfjs/ui/app-tab` | [Tabs contract](./accessibility.md#tabs) |
+| Application tab strip — `TabBar`, `wireTabBars`, `reorderTabs` | Tabs switch page regions and may overflow, close, or reorder. | Do not use it for a compact local view toggle; use `SegmentedControl`. Do not use it for a long choice list; use `Select`. Prefer it over Web Awesome `wa-tab-group`, `wa-tab`, and `wa-tab-panel` for Kerf app tabs. | Call `wireTabBars` once, retain the disposer, and apply `onReorder` synchronously; `reorderTabs` is the default array helper. | Ordered tabs, selection, panels, routing, closing, and persistence. | `@kerfjs/ui/tab-bar` plus `@kerfjs/ui/wire-tab-bars` | [Tabs contract](./accessibility.md#tabs) |
+| Page title and action — `PageHeader` | A page needs its primary heading and an optional trailing action. | Do not use it as persistent app chrome; use `Toolbar`. Do not use it inside a modal task; use `DialogHeader`. | Delegate an optional action normally. | Page title, action, and responsive placement. | `@kerfjs/ui/page-header` | [Header ownership](./component-contract.md#extracted-versus-application-specific) |
+| Dialog title and summary — `DialogHeader` | A dialog needs a toolbar-aligned title, optional summary/id and icon, and grouped actions wired to the dialog's ARIA references. | Do not use it as the page's `h1`; use `PageHeader`. It supplies header structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior. | Connect title and optional summary ids to the dialog host, pass action children directly, localize `actionsLabel` when the group needs a name, and delegate actions. | Open state, focus lifecycle, dismissal, actions, labels, and copy. | `@kerfjs/ui/dialog-header` | [Header ownership](./component-contract.md#extracted-versus-application-specific) |
+| Key/value facts — `ValueTable`, `ValueTableRow` | Read-only labels and values form a semantic definition list, optionally with a leading icon. | Do not use it for editable form fields or a row/column data grid; use native form or table semantics. | Compose typed `ValueTableRow` entries; pass `icon` when a 24px leading icon adds useful context. | Values, formatting, icon meaning, and empty/loading policy. | `@kerfjs/ui/value-table` | [Component ownership](./component-contract.md#ownership-boundaries) |
+| Indeterminate activity — `LoadingSpinner` | A Kerf surface needs compact, labeled or decorative indeterminate progress. | Do not use it for known progress; use Web Awesome `wa-progress-bar` or `wa-progress-ring`. Direct Web Awesome UI may use `wa-spinner`; do not mix spinner systems within one surface. | None; pass a label when the spinner conveys status. | Loading lifecycle and adjacent status copy. | `@kerfjs/ui/loading-spinner` | [Accessibility](./accessibility.md#shared-rules) |
+| Value selection — `Select` | A controlled form value comes from a moderate or long choice list, possibly grouped or icon-bearing. | Do not use it for commands; use a real action menu. Do not use it for a small visible choice set; use `SegmentedControl`. Prefer it over direct `wa-select`, `wa-option`, or value-like `wa-dropdown`/`wa-dropdown-item` composition. | Import `@kerfjs/ui/select/register` once; listen for standard input/change events. | Controlled value, validation, choices, and domain mapping. | `@kerfjs/ui/select` | [Web Awesome integration](../README.md#web-awesome-theme) |
+| Small exclusive choice — `SegmentedControl` | A few visible choices switch a compact view or setting, with toolbar, rounded, or pill presentation. | Do not use it for tabpanel semantics; use `TabBar`. Do not use it for many choices; use `Select`. Prefer it over `wa-button-group` when the controls select one value. | Delegate its action, read `data-segment-value`, update `value`, and rerender. | Controlled value, labels, action, and persistence. | `@kerfjs/ui/segmented-control` | [SegmentedControl contract](./accessibility.md#segmentedcontrol) |
+| Structured search editor — `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`, `wireTokenSearchFields` | Free text and ordered, editable, removable filter tokens share one searchbox; enable `collapsible` when an empty, unfocused field should reduce to one iconic action, standalone or in a toolbar group. | Do not use it for ordinary text entry; use a native input or Web Awesome `wa-input`. Do not use it when filters belong in separate form controls. | Read DOM-owned text on input, empty `textContent` on clear, and use `placeTokenSearchCaret` after explicit controlled focus changes. Call `wireTokenSearchFields` from `@kerfjs/ui/wire-token-search-fields` once so Enter submits without adding a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. In `collapsible` mode, control `expanded`, transfer focus after activation, and clear the transient state after focus leaves. | Parsing, suggestions, tokens, query execution, results, announcements, and the transient focus/open signal. | `@kerfjs/ui/token-search-field` | [TokenSearchField contract](./accessibility.md#tokensearchfield) |
+| Persistent inline status — `StateBanner` | A neutral, info, success, warning, or danger message belongs next to the affected work. | Do not use it for a no-content screen; use `EmptyState`. Do not use it for transient confirmation; use a toast. Web Awesome `wa-callout` is the ecosystem alternative for Web Awesome-owned content. | Delegate an optional action; choose alert urgency only for attention-requiring failure. | State mapping, message lifetime, retry/action behavior, and copy. | `@kerfjs/ui/state-banner` | [Feedback accessibility](./accessibility.md#shared-rules) |
+| Empty or busy content area — `EmptyState` | A content region has no items, cannot proceed, or is loading and needs explanation plus an optional action. | Do not use it for an inline status update; use `StateBanner`. Do not use it for transient success; use `wa-toast`/`wa-toast-item` or the application's toast system. | Delegate its optional action; it composes `LoadingSpinner` when busy. | Empty/busy policy, recovery action, illustration, and copy. | `@kerfjs/ui/empty-state` | [Feedback ownership](./component-contract.md#extracted-versus-application-specific) |
+
+## Ambiguous choices
+
+- `Toolbar` is persistent app chrome; `PageHeader` identifies a page; `DialogHeader` labels a focused modal task.
+- `TabBar` changes tabpanels and supports overflow/reorder; `SegmentedControl` chooses among a few compact views; `Select` handles a longer value list.
+- `StateBanner` persists beside affected work; `EmptyState` replaces absent content; `wa-callout` is contextual ecosystem content; `wa-toast` and `wa-toast-item` are transient and must not carry the only copy of important state.
+- `ResizableRegion` is an interactive controlled pane. CSS grid is the right answer when columns do not need a user-operable separator.
+- `TokenSearchField` is a structured editor. A native input or `wa-input` is the right answer for ordinary text.
+
+## Correct composition and duplicated-markup trap
+
+Correct: let the pane stay unpadded while its children own the shared 8/1/8
+geometry and 44px targets.
+
+```tsx
+<aside class="kui-pane">
+  <nav class="kui-pane__content kui-content">
+    <section>
+    <MenuHeader label="Workspace" />
+    <MenuItem action="open" label="Inbox" icon={inboxIcon} />
+    <MenuActionRow action="open-file" label="main.ts" trailingAction="file-actions" trailingActionLabel="Actions for main.ts" trailingActionIcon={moreIcon} />
+    </section>
+    <div class="kui-content-item">Workspace details</div>
+  </nav>
+</aside>
+```
+
+Incorrect: duplicating component-like rows and compensating for nested padding
+forks the package anatomy and spacing contract.
+
+```tsx
+<aside class="sidebar padded">
+  <h2 class="menu-header-copy">Workspace</h2>
+  <button class="menu-row-copy padded">Inbox</button>
+  <div class="panel indented-with-negative-margin">Workspace details</div>
+</aside>
+```
+
+## Web Awesome overlap policy
+
+Web Awesome catalog coverage means supported and themed, not preferred. Import
+`@kerfjs/ui/webawesome` for Kerf JSX types, individual component modules for
+registration, and the CSS-only `@kerfjs/ui/webawesome.css` theme.
+
+| Web Awesome choice | Kerf decision |
+| --- | --- |
+| `wa-button`, `wa-dropdown`, `wa-dropdown-item` | Use buttons and command menus for actions. Use `MenuItem` for a navigation row and `Select` when the user chooses a value. |
+| `wa-button-group` | Use only for exceptional grouped actions; use `SegmentedControl` for one-of-many selection. |
+| `wa-input`, `wa-tag` | Use for ordinary text and tags; use `TokenSearchField` only when text and ordered filter tokens form one editor. |
+| `wa-select`, `wa-option` | Use `Select`, which owns Kerf spacing, controlled rendering, icon stability, and explicit registration. |
+| `wa-tab-group`, `wa-tab`, `wa-tab-panel` | Use `TabBar`/`AppTab` for application tabs or `SegmentedControl` for compact local views. |
+| `wa-icon` | Use `LucideIcon` in application UI. |
+| `wa-split-panel` | Use `ResizableRegion` for Kerf application panes; retain Split Panel only when its distinct API is required. |
+| `wa-spinner`, `wa-progress-bar`, `wa-progress-ring`, `wa-skeleton` | Use `LoadingSpinner` for compact Kerf indeterminate activity; choose the ecosystem component when its distinct progress or placeholder semantics fit. |
+| `wa-callout`, `wa-toast`, `wa-toast-item` | Use `StateBanner` for persistent inline app status, `EmptyState` for absent content, and toasts only for transient feedback. |
+| `wa-popup`, `wa-tooltip`, `wa-popover` | Prefer the high-level interaction whose semantics fit. Use Popup only when its low-level anchored positioning removes custom placement code. |
+| `wa-tree`, `wa-tree-item`, `wa-animated-image`, `wa-comparison` | Use only for the specialized behavior named by the component. |
+| `wa-zoomable-frame` | Avoid for application UI; keep embedded-media behavior application-owned. |
+
+All other entries in the [Web Awesome theme contract](./webawesome-theme.md#coverage)
+remain supported when their native semantic contract matches the product need.

package/docs/design-philosophy.md

@@ -24,6 +24,44 @@ Unrelated updates must not close controls, move focus, reset a draft, replace a
 
 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.
 
+### Panes share one child-owned geometry
+
+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.
+
+Use the package composition so the geometry has one owner:
+
+```tsx
+<aside class="kui-pane">
+  <nav class="kui-pane__content kui-content">
+    <section>
+    <MenuHeader label="Workspace" />
+    <MenuItem action="open" label="Inbox" icon={inboxIcon} />
+    <MenuItem action="open" label="Drafts" />
+    </section>
+    <div class="kui-content-item">Panel contents</div>
+  </nav>
+</aside>
+```
+
+Do not pad the pane and then pad every wrapper. That duplicates the geometry
+and makes transparent borders behave differently from visible ones:
+
+```tsx
+<aside class="pane padded">
+  <section class="padded">
+    <MenuHeader label="Workspace" />
+    <div class="panel padded-again">Panel contents</div>
+  </section>
+</aside>
+```
+
+Change the shared item tokens at a real composition boundary when a product
+needs different geometry; do not compensate with one-off negative margins.
+
 ### Prefer directness
 
 Use the shortest understandable, recoverable interaction. Avoid modes, dialogs, confirmations, and explicit saves when direct manipulation can safely express the same result. Low ceremony still requires a discoverable affordance, visible focus, and honest feedback.

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

@@ -0,0 +1,70 @@
+import '@kerfjs/ui/layout.css';
+
+import { delegate, mount, signal } from 'kerfjs';
+import { delegateActions } from 'kerfjs/actions';
+
+export interface AppCommand {
+  id: string;
+  label: string;
+  keywords?: string[];
+}
+
+export interface CommandPaletteCallbacks {
+  onClose(): void;
+  onRun(command: AppCommand): void;
+}
+
+/**
+ * Application-local example, not an @kerfjs/ui export. The application owns
+ * ranking, history, shortcuts, focus policy, command availability, and copy.
+ */
+export function mountCommandPaletteAdapter(
+  root: HTMLElement,
+  commands: AppCommand[],
+  { onClose, onRun }: CommandPaletteCallbacks,
+): () => void {
+  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 stopMount = mount(root, render);
+  const stopActions = delegateActions(root, 'click', {
+    'run-command': (_event, element) => {
+      const id = (element as HTMLElement).dataset.commandId;
+      const command = commands.find((candidate) => candidate.id === id);
+      if (command) onRun(command);
+    },
+    'clear-query': () => {
+      query.value = '';
+      root.querySelector<HTMLInputElement>('[data-command-query]')?.focus();
+    },
+    '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();
+  });
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    stopEscape();
+    stopInput();
+    stopActions();
+    stopMount();
+  };
+}

package/docs/layout.md

@@ -0,0 +1,95 @@
+# Pane and content layout
+
+Import `@kerfjs/ui/layout.css` for the shared geometry used by sidebars, main
+areas, inspectors, and dialogs. The vocabulary deliberately describes structure
+rather than location: the same pane can be placed anywhere.
+
+## Anatomy
+
+```tsx
+<aside class="kui-pane">
+  <div class="kui-pane__toolbar"><Toolbar label="Workspace" ... /></div>
+  <div class="kui-pane__content kui-content">
+    <section>...</section>
+    <section>...</section>
+  </div>
+  <footer class="kui-pane__footer"><Toolbar label="Actions" ... /></footer>
+</aside>
+```
+
+`.kui-pane` has no padding. It reserves rows for an optional toolbar, one
+scrolling content area, and an optional footer. A main area or dialog often
+omits the footer; a navigation pane commonly uses all three. Fixed chrome stays
+outside `.kui-pane__content`, which is the pane's scroll owner.
+
+`.kui-content` is a vertical stack with a 24px gap between major children.
+Sections may contain adjacent `MenuItem` rows without adding another major gap.
+Ordinary surface-like children use `.kui-content-item` and own their complete
+geometry:
+
+- 8px inline margin from the pane edge
+- 1px border, transparent by default
+- 8px internal padding and 8px internal gap
+- `calc(1px + remify(11px))`, or 12px, rounded corners
+
+Use `.kui-content-item--pill` for the 22px pill radius expressed as
+`calc(1px + remify(21px))`. Consumers can make a content item visible without
+changing its geometry by setting `--kui-content-item-border` and
+`--kui-content-item-background`.
+
+A visible parent surface does not make every child another visible card. The
+composer recipe keeps its form as the single surface and uses three transparent
+content items for the introduction, fields, and footer. A conditional
+`StateBanner` remains visibly distinct because it communicates semantic status.
+
+## Public roles and tokens
+
+| Need | Class | Token / default |
+| --- | --- | --- |
+| Unpadded toolbar/content/footer structure | `.kui-pane` | — |
+| Scrolling pane content | `.kui-pane__content` | — |
+| Major vertical rhythm | `.kui-content` | `--kui-layout-content-gap: 24px` |
+| Self-contained child geometry | `.kui-content-item` | 8px margin + 1px border + 8px padding |
+| Pill child | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px` |
+| Related controls | `.kui-control-cluster` | `--kui-layout-control-gap: 8px` |
+| Inline metadata | `.kui-inline-metadata` | `--kui-layout-metadata-gap: 4px` |
+| Explicit scroll owner outside a pane | `.kui-scroll-owner` | `overflow: auto` |
+
+The component layer applies the same contract to `Toolbar`, `MenuHeader`,
+`MenuItem`, `PageHeader`, `DialogHeader`, `StateBanner`, `ValueTable`,
+`ValueTableRow`, tabs, and form controls. A value-table row separator starts at
+the row's 8px content inset, or at 40px when the row contains its 24px leading
+icon and 8px gap, and always ends 8px from the right edge. Each value-table row
+also keeps 8px of root-scaled block padding independently of its semantic inline
+inset. Most interactive rows and toolbar groups are 44px tall.
+Toolbar groups reserve a real 1px outer border around a 42px inner area, even
+when their border and background are transparent.
+`DialogHeader` applies the same rule internally: its icon/title identity is a
+borderless group in a top toolbar, its direct action children are wrapped in a
+contained group, and its optional subtitle is a separate row aligned below the
+title. The icon visual is 24px inside a 34px circular background.
+
+## Ownership rules
+
+1. Do not pad a sidebar, main area, dialog, or `.kui-pane` shell. Children own
+   their own margin, border, background, padding, and radius.
+2. Use 24px gaps for major vertical separation and 8px gaps inside an item or
+   between toolbar groups. Do not confuse the two relationships.
+3. Wrap toolbar content in `ToolbarControlGroup`, including dormant text. A
+   transparent group still reserves the same 44px geometry as a visible group.
+4. Keep one scrolling content owner per pane. Toolbar and footer siblings stay
+   fixed while the content scrolls.
+5. A split item keeps dormant and interactive regions separate. For example,
+   `MenuHeader` renders its title/count-or-badge cluster separately from its optional
+   logical-end 44px action. The header fills the available inline width and its
+   action glyph defaults to 18px; disclosure mode makes the title cluster itself
+   the button and supplies the production `DisclosureArrow` unless `actionIcon`
+   replaces it.
+   `MenuActionRow` uses a noninteractive row root around sibling 44px primary
+   and trailing buttons. `MenuItem.trailing` remains dormant content.
+6. Reading width, column placement, and responsive relocation remain application
+   decisions. The shared classes define local geometry, not the whole shell.
+
+At narrow widths or 200% zoom, relocate or stack panes before shrinking targets.
+The 8/1/8 item contract and 44px controls remain stable, so screenshots and
+focus-order tests exercise the same model at every viewport.