@kerfjs/ui 5.0.0-beta.24 → 5.0.0-beta.26

package/docs/component-selection.md

@@ -75,42 +75,55 @@ 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, panel, or dialog heading; use `PanelHeader`.                                                                                                                                                                                                                                                               | 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)                 |
-| Floating controls over content — `FloatingToolbar`                                                                      | A small cluster of controls (e.g. a drawer restore) must float over scrolling content — distinct and forced-dark — inside a positioned container.                                                                       | Do not use it for a primary page or panel toolbar (use `Toolbar`), or for anything that must sit above dialogs/overlays — it is not top-layer.                                                                                                                                                                                       | Compose `ToolbarControlGroup`s and delegate their actions; the app owns visibility and position.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Controls, visibility, and position.                                                                                                                      | `@kerfjs/ui/floating-toolbar`                        | [Component subpaths](../README.md#component-subpaths)                               |
-| Toolbar identity text — `ToolbarText`                                                                                   | A toolbar needs extra-large (page/panel title), large, default, or compact textual identity.                                                                                                                            | Plain text is not a heading by default; when a title needs heading semantics pass `headingLevel` (or prefer `PanelHeader`, which forwards it).                                                                                                                                                                                       | Optional `headingLevel` for `role="heading"` + `aria-level`. Defaults to one line, ellipsized when it does not fit; `wrap` flows onto multiple lines, `ellipsis` toggles the trailing …, and `maxLines` caps a wrap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Text, heading level, overflow behavior, and responsive priority.                                                                                         | `@kerfjs/ui/toolbar-text`                            | [Toolbar composition](../README.md#component-subpaths)                              |
-| Vertical stack — `List`                                                                                                 | Rows, sections, or arbitrary components need a consistent vertical stretch layout, optional standard/custom gap, flex growth, one vertical scroll owner, or edge dividers.                                              | It is layout-only and does not provide `ul`/`ol` semantics. Do not nest scroll owners or use it when a horizontal layout is required.                                                                                                                                                                                                | Choose `gap`, `flex`, `scrollable`, and canonical `dividerSides` (`t`, `r`, `b`, `l` combinations in that order); bound the block size when scrolling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Child semantics/content, containing height, and which optional layout behaviors apply.                                                                   | `@kerfjs/ui/list`                                    | [Pane geometry](../README.md#pane-and-content-geometry)                             |
-| Navigation row — `ListItem`                                                                                             | A pane or navigation area needs a selectable, disabled, dormant-trailing, or multiline action row.                                                                                                                      | Do not put a control in `trailing`; use `ListActionRow` 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/list-item`                               | [Pane geometry](../README.md#pane-and-content-geometry)                             |
-| Navigation row with trailing action — `ListActionRow`                                                                   | A full-width row needs a selectable primary action and an independently focusable trailing action.                                                                                                                      | Use `ListItem` 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/list-action-row`                         | [Accessibility](./accessibility.md#listactionrow)                                   |
-| Navigation section heading — `ListHeader`                                                                               | 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, panel, or dialog title; use `PanelHeader`. | 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/list-header`                             | [Pane geometry](../README.md#pane-and-content-geometry)                             |
-| Inset self-bordered control — `ListInsetControl`                                                                        | A control that owns its own border and padding but no outer margin (a search input, a `SegmentedControl`) must line up inside a `.kui-content` list with the standard 8px inline margins and stretch to fill the row.   | Do not wrap a `.kui-content-item` or a `ListItem`/`ListHeader` that already owns its inline margin — that double-insets it. Do not add ad-hoc `margin`/`padding` around a bare control to align it; use this instead.                                                                                                                | Place the self-bordered control(s) as children; they stretch to fill. It applies only the inline margin, flex stretch, and 8px gap — the child owns its own border and padding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | The control(s), their state, and action wiring.                                                                                                          | `@kerfjs/ui/list-inset-control`                      | [Pane geometry](../README.md#component-subpaths)                                    |
-| Inset bare text — `ListInsetText`                                                                                       | A plain string or inline content with no margin, border, or padding of its own must sit in a `.kui-content` list with its text edge aligned to the bordered items around it.                                            | Do not use it to wrap a component that already owns content-item geometry (`ListItem`, `StateBanner`, a `.kui-content-item`) — that double-insets it. Do not hand-roll the 8px margin / 1px border / 8px padding.                                                                                                                    | Pass the text or inline `SafeHtml` as children; it supplies the 8px inline margin, 1px transparent border, and 8px padding so the text edge lands at the standard 17px inset. Pass `horizontalOnly` to keep that horizontal inset but drop the vertical margin, border, and padding for tight text layout.                                                                                                                                                                                                                                                                                                                                                                                                             | The text, copy, and localization.                                                                                                                        | `@kerfjs/ui/list-inset-text`                         | [Pane geometry](../README.md#component-subpaths)                                    |
-| Application column — `Pane`                                                                                             | A sidebar, main area, inspector, or dialog needs shared vertical header/content/footer organization, one scroll owner, and optional edge separators.                                                                    | Do not pad the pane shell, wrap child-owned geometry in competing insets, invent unrelated centered measures, or leave an icon-only rail for a hidden pane.                                                                                                                                                                          | Import `Pane`, provide optional fixed header/footer slots around its primary vertical content, and opt into only the needed logical-edge separators; add `.kui-content-item` as needed. A visible pane owns collapse in its toolbar; move a hidden inline-start pane's restore control to the main toolbar leading edge and an inline-end pane's restore control to its trailing edge.                                                                                                                                                                                                                                                                                                                                 | Layout hierarchy, reading width, responsive relocation, pane visibility state, slot semantics, labels, and separator placement.                          | `@kerfjs/ui/pane`                                    | [Pane anatomy](./layout.md#anatomy)                                                 |
-| Lowered content surface — `SunkenPanel`                                                                                 | A main work area or nested content group needs one visually lowered surface with a compact inset and vertical stack.                                                                                                    | Do not use it merely to add padding, as a replacement for `Pane` anatomy, or around children that already own the same outer surface.                                                                                                                                                                                                | Compose the application-owned content as children, choose the default `rounded` shape or `square` for a flush edge-to-edge area, and pass `ariaLabel` only when the surface is a distinct named region.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Region semantics, accessible name, shape, scroll ownership, child ordering, and content.                                                                 | `@kerfjs/ui/sunken-panel`                            | [SunkenPanel](./sunken-panel.md)                                                    |
-| 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 `ListItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract.                                                                                      | Compose `ListHeader`, `ListItem`, and `ListActionRow` in `.kui-content`; use `ListHeader` 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)                                            |
-| Panel, dialog, or page heading — `PanelHeader`                                                                          | A panel, dialog, or page needs a heading with an extra-large title, an optional icon and subtitle, and trailing actions.                                                                                                | Do not use it as persistent app chrome; use `Toolbar`. It supplies header structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior.                                                                                                                                                    | Connect the title id and any provided summary id to the dialog or panel host, pass the trailing controls (typically a `ToolbarControlGroup`), and delegate their actions. **For a page or view title set `headingLevel` (usually `1`)** so the title is a real heading landmark (`role="heading"` + `aria-level`) for screen-reader heading navigation; omit it for a dialog title, which is referenced via `aria-labelledby` to `titleId` and needs no heading.                                                                                                                                                                                                                                                       | Open state, focus lifecycle, dismissal, the trailing controls, labels, copy, and the heading level for page use.                                         | `@kerfjs/ui/panel-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)                                    |
-| Loading placeholder — `Skeleton` + a component's `placeholder` prop                                                     | A value or a whole component is still loading and should hold its space as a subtle, unanimated block, keeping the layout stable — an inspector or detail view rendering its real chrome with per-record values absent. | Do not use it for known progress (use `LoadingSpinner`), do not animate it, and do not hand-rebuild a component's empty state — set `placeholder` on the component instead. Prefer it over `wa-skeleton`, which the pure-Kerf primitives avoid to stay Web-Awesome-free.                                                             | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render skeletons in its value slots with interactivity disabled; use the standalone `Skeleton` for a custom slot.                                                                                                                                                                                                                                                                                                                                                                                                  | Loading lifecycle, which slots are unknown, and announcing the loading region.                                                                           | `@kerfjs/ui/skeleton`                                | [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 it also manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse); bind the field's `expanded` to the signal on the returned handle (`handle.expanded(id)`) or adopt your own via `collapsible.signals`, and opt out per behavior only when the app must own it. | Parsing, suggestions, tokens, query execution, results, announcements, and — only if overriding the default — the collapsible `expanded` 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. Use the optional tone-tinted `badge` for a terse count or status beside the title, not as the only expression of meaning.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | State mapping, message lifetime, retry/action behavior, badge content, 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) |
+| 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 or heading — `Toolbar`                                                                              | Leading identity, optional centered content, and trailing controls form one horizontal app bar or a page/panel/dialog heading.                                                                                          | Do not add bespoke heading geometry or a private wrapper; use the same zone contract everywhere.                                                                                                                                                                                                                                           | Put identity/title text directly in a zone as `ToolbarText`; group controls and icon tiles in `ToolbarControlGroup`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Actions, command availability, responsive relocation, state, and supporting copy below a heading.                                                        | `@kerfjs/ui/toolbar`                                 | [Toolbar composition](../README.md#component-subpaths)                              |
+| Toolbar control cluster — `ToolbarControlGroup`                                                                         | Related toolbar controls need contained/borderless chrome, compact/tight geometry, icon/text/mixed/avatar anatomy, selected treatment, or nested dropdown sizing.                                                       | 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; declare typed content and appearance instead of overriding descendants or `::part(base)`; use `SegmentedControl` for an exclusive choice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Actions, pressed/expanded state, content, and policy.                                                                                                    | `@kerfjs/ui/toolbar-control-group`                   | [Component ownership](./component-contract.md#ownership-boundaries)                 |
+| Floating controls over content — `FloatingToolbar`                                                                      | A small cluster of controls (e.g. a drawer restore) must float over scrolling content — distinct and forced-dark — inside a positioned container.                                                                       | Do not use it for a primary page or panel toolbar (use `Toolbar`), or for anything that must sit above dialogs/overlays — it is not top-layer.                                                                                                                                                                                             | Compose `ToolbarControlGroup`s and delegate their actions; the app owns visibility and position.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Controls, visibility, and position.                                                                                                                      | `@kerfjs/ui/floating-toolbar`                        | [Component subpaths](../README.md#component-subpaths)                               |
+| Toolbar identity text — `ToolbarText`                                                                                   | A toolbar needs extra-large (page/panel title), large, default, or compact textual identity.                                                                                                                            | Plain text is not a heading by default; when a title needs heading semantics pass `headingLevel`.                                                                                                                                                                                                                                          | Optional `headingLevel` for `role="heading"` + `aria-level`. Defaults to one line, ellipsized when it does not fit; `wrap` flows onto multiple lines, `ellipsis` toggles the trailing …, and `maxLines` caps a wrap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Text, heading level, overflow behavior, and responsive priority.                                                                                         | `@kerfjs/ui/toolbar-text`                            | [Toolbar composition](../README.md#component-subpaths)                              |
+| Vertical stack — `List`                                                                                                 | Rows, sections, or arbitrary components need a consistent vertical stretch layout, optional standard/custom gap, flex growth, one vertical scroll owner, or edge dividers.                                              | It is layout-only and does not provide `ul`/`ol` semantics. Do not nest scroll owners or use it when a horizontal layout is required.                                                                                                                                                                                                      | Choose `gap`, `flex`, `scrollable`, and canonical `dividerSides` (`t`, `r`, `b`, `l` combinations in that order); bound the block size when scrolling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Child semantics/content, containing height, and which optional layout behaviors apply.                                                                   | `@kerfjs/ui/list`                                    | [Pane geometry](../README.md#pane-and-content-geometry)                             |
+| Navigation row — `ListItem`                                                                                             | A pane or navigation area needs a selectable, disabled, dormant-trailing, or multiline action row.                                                                                                                      | Do not put a control in `trailing`; use `ListActionRow` 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/list-item`                               | [Pane geometry](../README.md#pane-and-content-geometry)                             |
+| Navigation row with trailing action — `ListActionRow`                                                                   | A full-width row needs a selectable primary action and an independently focusable trailing action.                                                                                                                      | Use `ListItem` 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/list-action-row`                         | [Accessibility](./accessibility.md#listactionrow)                                   |
+| Navigation section heading — `ListHeader`                                                                               | 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, panel, or dialog title; use a heading `Toolbar`. | 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/list-header`                             | [Pane geometry](../README.md#pane-and-content-geometry)                             |
+| Inset self-bordered control — `ListInsetControl`                                                                        | A control that owns its own border and padding but no outer margin (a search input, a `SegmentedControl`) must line up inside a `.kui-content` list with the standard 8px inline margins and stretch to fill the row.   | Do not wrap a `.kui-content-item` or a `ListItem`/`ListHeader` that already owns its inline margin — that double-insets it. Do not add ad-hoc `margin`/`padding` around a bare control to align it; use this instead.                                                                                                                      | Place the self-bordered control(s) as children; they stretch to fill. It applies only the inline margin, flex stretch, and 8px gap — the child owns its own border and padding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | The control(s), their state, and action wiring.                                                                                                          | `@kerfjs/ui/list-inset-control`                      | [Pane geometry](../README.md#component-subpaths)                                    |
+| Inset bare text — `ListInsetText`                                                                                       | A plain string or inline content with no margin, border, or padding of its own must sit in a `.kui-content` list with its text edge aligned to the bordered items around it.                                            | Do not use it to wrap a component that already owns content-item geometry (`ListItem`, `StateBanner`, a `.kui-content-item`) — that double-insets it. Do not hand-roll the 8px margin / 1px border / 8px padding.                                                                                                                          | Pass the text or inline `SafeHtml` as children; it supplies the 8px inline margin, 1px transparent border, and 8px padding so the text edge lands at the standard 17px inset. Pass `horizontalOnly` to keep that horizontal inset but drop the vertical margin, border, and padding for tight text layout.                                                                                                                                                                                                                                                                                                                                                                                                             | The text, copy, and localization.                                                                                                                        | `@kerfjs/ui/list-inset-text`                         | [Pane geometry](../README.md#component-subpaths)                                    |
+| Application column — `Pane`                                                                                             | A sidebar, main area, inspector, or dialog needs shared vertical header/content/footer organization, one scroll owner, and optional edge separators.                                                                    | Do not pad the pane shell, wrap child-owned geometry in competing insets, invent unrelated centered measures, or leave an icon-only rail for a hidden pane.                                                                                                                                                                                | Import `Pane`, provide optional fixed header/footer slots around its primary vertical content, and opt into only the needed logical-edge separators; add `.kui-content-item` as needed. A visible pane owns collapse in its toolbar; move a hidden inline-start pane's restore control to the main toolbar leading edge and an inline-end pane's restore control to its trailing edge.                                                                                                                                                                                                                                                                                                                                 | Layout hierarchy, reading width, responsive relocation, pane visibility state, slot semantics, labels, and separator placement.                          | `@kerfjs/ui/pane`                                    | [Pane anatomy](./layout.md#anatomy)                                                 |
+| One-pane navigation — `NavStack`                                                                                        | A compact flow pushes into details while keeping earlier views mounted, or a single-pane screen needs the same stable layout contract.                                                                                  | Do not use it when list and detail should remain visible together; use `SplitView`. Do not use it alone for co-equal top-level destinations; use one stack per `TabScaffold` tab.                                                                                                                                                          | Keep the ordered view array controlled, import its CSS explicitly, and call `wireNavStack` for back delegation, transitions, and focus restoration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | View keys/content/titles, push and pop actions, focus targets, and optional bottom toolbar.                                                              | `@kerfjs/ui/nav-stack`                               | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
+| Responsive list-detail — `SplitView`                                                                                    | A primary list and related detail belong together on roomy devices but become a one-pane drill-down on compact devices.                                                                                                 | Do not use it for a single linear flow or a multi-panel editor shell.                                                                                                                                                                                                                                                                      | Provide controlled selection/detail state and device class; opt into resize wiring only when the separator is user adjustable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Selection, detail content, compact back action, device policy, and optional persisted width.                                                             | `@kerfjs/ui/split-view`                              | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
+| Compact top-level destinations — `TabScaffold`                                                                          | A handset or portrait-tablet app has two to five co-equal destinations whose scenes and nested navigation must remain mounted across switches.                                                                          | Do not use it for document tabs, reorderable work items, or a desktop navigation rail.                                                                                                                                                                                                                                                     | Keep the active id controlled, import its CSS explicitly, and call `wireTabScaffold`; commonly place one `NavStack` in each tab scene.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Destination definitions, active id, routing, persistence, and roomy-device replacement.                                                                  | `@kerfjs/ui/tab-scaffold`                            | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
+| Desktop multi-panel workspace — `Workbench`                                                                             | A desktop-class tool needs a central work area plus independently collapsible navigator, inspector, or console regions.                                                                                                 | Do not shrink the full shell onto compact devices or use it for one standalone panel.                                                                                                                                                                                                                                                      | Render only the required rails/drawer, keep collapse state controlled, and replace peripheral regions with stacks or overlays below desktop sizes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Panel presence/content, collapsed states, sizes, persistence, responsive replacement, and controls.                                                      | `@kerfjs/ui/workbench`                               | [Workbench](./workbench.md)                                                         |
+| Standalone rail or drawer — `CollapsiblePanel`                                                                          | One left/right rail or bottom drawer needs controlled collapse without adopting the complete `Workbench` shell.                                                                                                         | Do not use it for several coordinated workspace panels or retain an empty icon-only rail while collapsed.                                                                                                                                                                                                                                  | Pair it with `CollapsiblePanelToggle`; call `wireSidebar` for focus transfer, Escape/backdrop dismissal, compact overlay trapping, and persistence integration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Panel content/size, collapsed state, toggle placement, persistence, and compact policy.                                                                  | `@kerfjs/ui/collapsible-panel`                       | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
+| Lowered content surface — `SunkenPanel`                                                                                 | A main work area or nested content group needs one visually lowered surface with a compact inset and vertical stack.                                                                                                    | Do not use it merely to add padding, as a replacement for `Pane` anatomy, or around children that already own the same outer surface.                                                                                                                                                                                                      | Compose the application-owned content as children, choose the default `rounded` shape or `square` for a flush edge-to-edge area, and pass `ariaLabel` only when the surface is a distinct named region.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Region semantics, accessible name, shape, scroll ownership, child ordering, and content.                                                                 | `@kerfjs/ui/sunken-panel`                            | [SunkenPanel](./sunken-panel.md)                                                    |
+| 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 `ListItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract.                                                                                            | Compose `ListHeader`, `ListItem`, and `ListActionRow` in `.kui-content`; use `ListHeader` 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, compact/segmented/icon-only presentation, label truncation, 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`; use typed appearance props instead of descendant CSS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Tab identity, order, selection, close policy, content, domain metadata values, and outer placement.                                                      | `@kerfjs/ui/app-tab`                                 | [Tabs contract](./accessibility.md#tabs)                                            |
+| Application tab strip — `TabBar`, `wireTabBars`, `reorderTabs`                                                          | Tabs switch page regions and may overflow, close, reorder, fill a segmented inspector strip, or sit beside a trailing action.                                                                                           | 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. Choose typed presentation/allocation props while the parent owns outer placement.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Ordered tabs, selection, panels, routing, closing, persistence, and outer placement.                                                                     | `@kerfjs/ui/tab-bar` plus `@kerfjs/ui/wire-tab-bars` | [Tabs contract](./accessibility.md#tabs)                                            |
+| Panel, dialog, or page heading — `Toolbar` + `ToolbarText`                                                              | A panel, dialog, or page needs an extra-large title, optional icon, grouped trailing actions, and optional supporting copy.                                                                                             | Do not add a private heading wrapper or bespoke layout. The toolbar supplies structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior.                                                                                                                                                       | Connect title/supporting-copy ids to the host, group controls, and delegate actions. **For a page or view title set `headingLevel` (usually `1`)** on `ToolbarText`; omit it for a dialog title referenced by `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Open state, focus lifecycle, dismissal, controls, ids, copy, and heading level.                                                                          | `@kerfjs/ui/toolbar` + `@kerfjs/ui/toolbar-text`     | [Toolbar headings](./accessibility.md#toolbar-headings)                             |
+| Dialog or popup geometry — `DialogSurface`, `PopupSurface`                                                              | Recurring Web Awesome dialogs need standard sizes/presentations/body/footer insets, or dropdown menus need list-compatible inset ownership.                                                                             | Do not use these wrappers as generic layout or to replace native dialog/dropdown behavior. Avoid consumer `::part()` overrides for covered patterns.                                                                                                                                                                                       | Wrap one `wa-dialog` or `wa-dropdown`; choose the typed geometry while retaining native labeling, open state, focus, dismissal, and menu semantics.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | State, focus lifecycle, dismissal, labels, content, and outer placement.                                                                                 | `@kerfjs/ui/surface-scaffold`                        | [Surface scaffolds](./surface-scaffold.md)                                          |
+| 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)                                    |
+| Loading placeholder — `Skeleton` + a component's `placeholder` prop                                                     | A value or a whole component is still loading and should hold its space as a subtle, unanimated block, keeping the layout stable — an inspector or detail view rendering its real chrome with per-record values absent. | Do not use it for known progress (use `LoadingSpinner`), do not animate it, and do not hand-rebuild a component's empty state — set `placeholder` on the component instead. Prefer it over `wa-skeleton`, which the pure-Kerf primitives avoid to stay Web-Awesome-free.                                                                   | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render skeletons in its value slots with interactivity disabled; use the standalone `Skeleton` for a custom slot.                                                                                                                                                                                                                                                                                                                                                                                                                 | Loading lifecycle, which slots are unknown, and announcing the loading region.                                                                           | `@kerfjs/ui/skeleton`                                | [Accessibility](./accessibility.md#shared-rules)                                    |
+| Value selection — `Select`                                                                                              | A controlled form, toolbar, or compact navigation value comes from a moderate or long choice list, possibly grouped, icon-bearing, icon-only when closed, or truncating.                                                | 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. Use typed presentation props rather than consumer `::part()` overrides; let the parent own placement.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Controlled value, validation, choices, domain mapping, and outer placement.                                                                              | `@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 it also manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse); bind the field's `expanded` to the signal on the returned handle (`handle.expanded(id)`) or adopt your own via `collapsible.signals`, and opt out per behavior only when the app must own it. | Parsing, suggestions, tokens, query execution, results, announcements, and — only if overriding the default — the collapsible `expanded` 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. Use the optional tone-tinted `badge` for a terse count or status beside the title, not as the only expression of meaning.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | State mapping, message lifetime, retry/action behavior, badge content, 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; `PanelHeader` heads a panel, dialog, or page.
+- `Toolbar` serves persistent app chrome and headings; the zone contents and accessible naming distinguish the purpose.
 - `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.
+- Configure application panels through the shared `separator`, `collapseMotion`,
+  `contentOverflow`, `presentation`, `restoreControl`, and `restorePosition`
+  props on `ResizableRegion`, `Workbench` panels, and `CollapsiblePanel`. These
+  cover separator suppression, one-reflow collapse with composited motion,
+  bottom-drawer popups, compact overlays or replacements, and safe-area restore
+  placement without descendant `.kui-*` overrides. `wireSidebar` also accepts a
+  hidden compact replacement and keeps compact overlays exclusive by default.
 - `TokenSearchField` is a structured editor. A native input or `wa-input` is the right answer for ordinary text.
 
 ## Toolbar composition
@@ -122,9 +135,11 @@ controls). Do not drop bare buttons, inputs, links, or arbitrary markup straight
 into a zone; wrap controls in a `ToolbarControlGroup` so they get the shared
 toolbar geometry, hover/pressed treatment, and grouping. `SegmentedControl`,
 `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live
-**inside** a `ToolbarControlGroup`, not loose in the zone. `PanelHeader` is the
-one wrapper that composes these for you as a panel/dialog/page heading.
-Its bottom divider is enabled by default. Set `dividerSides=""` for none, or
+**inside** a `ToolbarControlGroup`, not loose in the zone. For a page, panel, or
+dialog heading, put an extra-large `ToolbarText` directly in the leading zone,
+optionally preceded by a grouped icon, and group trailing actions. Keep supporting
+copy below as app-owned content. A bottom divider is enabled by default. Set
+`dividerSides=""` for none, or
 use the canonical physical-edge combinations (`t`, `r`, `b`, `l`, in that
 order—for example `tr` or `trbl`) when the toolbar owns other separator edges.
 
@@ -158,6 +173,21 @@ own DOM.
 </ToolbarControlGroup>
 ```
 
+## Configuring recurring list rows
+
+Configure the List family instead of selecting its descendant classes. Use
+`density="compact"` for result-heavy panes, `description` for the secondary
+label line, `status` for dormant state text, and `busy` for known progress that
+keeps current content visible. `divider` marks group boundaries without an
+app-owned separator rule. `ListHeader.indicatorTone` gives count, badge, or
+status content neutral, accent, or danger attention.
+
+When a row needs a context action, use `ListActionRow`; its two native buttons
+remain siblings. `trailingActionVisibility="interaction"` keeps the action
+available on hover and keyboard focus and automatically leaves it visible on
+non-hover devices. These props own presentation only—the application still
+owns labels, status meaning, action policy, selection, and domain metadata.
+
 ## Correct composition and duplicated-markup trap
 
 Correct: let the pane stay unpadded while its children own the shared 8/1/8

package/docs/design/templates.md

@@ -9,7 +9,7 @@ component picture without running the app.
 
 ## Coverage
 
-Templated components (each with light + dark variants): `PanelHeader`,
+Templated components (each with light + dark variants):
 `ToolbarControlGroup`, `Toolbar`, `ToolbarText`, `List`, `ListItem`, `ListHeader`,
 `ListActionRow`, `ValueTable`, `StateBanner`, `EmptyState`, `Skeleton`,
 `SegmentedControl`, `TabBar`/`AppTab`, and `TokenSearchField`.
@@ -27,11 +27,9 @@ catalog and the app-layouts docs cover those.
 
 ```
 docs/design/templates/
-  panel-header.svg              ← library: every variant, composed (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
     …
@@ -74,7 +72,7 @@ not have to interpret nested `<svg>` elements.
 
 **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.
 

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

@@ -19,7 +19,7 @@
       "zones": [
         {
           "id": "header",
-          "accepts": ["@kerfjs/ui:panel-header"],
+          "accepts": ["@kerfjs/ui:toolbar"],
           "cardinality": { "min": 1, "max": 1 },
           "exclusiveWith": []
         },
@@ -32,11 +32,8 @@
       ],
       "children": {
         "mode": "listed",
-        "concepts": ["@kerfjs/ui:panel-header", "@kerfjs/ui:value-table"],
-        "requiredConcepts": [
-          "@kerfjs/ui:panel-header",
-          "@kerfjs/ui:value-table"
-        ]
+        "concepts": ["@kerfjs/ui:toolbar", "@kerfjs/ui:value-table"],
+        "requiredConcepts": ["@kerfjs/ui:toolbar", "@kerfjs/ui:value-table"]
       },
       "state": [
         { "id": "selected-record", "owner": "application", "required": true }

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

@@ -36,7 +36,7 @@
         "border": "child",
         "padding": "child",
         "notes": [
-          "The embedding pane positions the inspector; PanelHeader, ValueTable, and action groups retain their own geometry."
+          "The embedding pane positions the inspector; Toolbar, ValueTable, and action groups retain their own geometry."
         ]
       },
       "documentation": "docs/inspector.md"

package/docs/layout.md

@@ -56,7 +56,7 @@ control border and 1px control padding, so its default rounded-rectangle radius
 is 10px inside the control's 12px radius.
 
 A visible parent surface does not make every child another visible card. The
-composer recipe keeps its form as the single surface, uses `PanelHeader` for
+composer recipe keeps its form as the single surface, uses a heading `Toolbar` for
 its task hierarchy, and places field and action control edges on the shared 8px
 inline gutter instead of nesting them inside another padded content item. A
 conditional `StateBanner` remains visibly distinct because it communicates
@@ -77,7 +77,7 @@ semantic status.
 | Explicit scroll owner outside a pane     | `.kui-scroll-owner`       | `overflow: auto`                      |
 
 The component layer applies the same contract to `Toolbar`, `ListHeader`,
-`ListItem`, `PanelHeader`, `StateBanner`, `ValueTable`,
+`ListItem`, `Toolbar`, `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
@@ -85,13 +85,11 @@ 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.
-`PanelHeader` is a plain top `Toolbar` used as a panel, dialog, or page heading
-and overrides no Toolbar styles. The leading zone holds the optional icon (a
-normal bordered `ToolbarControlGroup` given a brand fill with a matching border,
-a 22px glyph) and the title as extra-large `ToolbarText`; the app's trailing
-controls go straight into the trailing zone, and the icon group is omitted when
-no icon is passed. The optional subtitle is a separate row below the toolbar, its
-text left-aligned with the title text.
+Panel, dialog, and page headings are plain `Toolbar` compositions. The leading
+zone holds an optional icon `ToolbarControlGroup` and a direct extra-large
+`ToolbarText`; actions belong in a trailing group. Omit empty groups. Supporting
+copy is app-owned content below the toolbar and aligns with the intended content
+edge.
 
 ## Spacing scale
 

package/docs/recipes.md

@@ -56,7 +56,7 @@ no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
 
 [Open the recipe](../ux-demo/?component=recipe-workspace-header) · [TSX source](../ux-demo/recipes/workspace-header.tsx)
 
-`PanelHeader` owns the page heading while one control cluster holds secondary,
+The page heading is a direct `Toolbar`/`ToolbarText` composition while one control cluster holds secondary,
 overflow, and primary actions. The app owns authorization and command policy;
 controls relocate without changing focus order.
 
@@ -66,10 +66,10 @@ controls relocate without changing focus order.
 
 The production Web Awesome dialog owns modal focus and Escape; the thin recipe
 adapter restores the invoking control consistently after the hide event.
-`PanelHeader`, `ListHeader`, `ListItem`, and `ValueTable` own their included
+`Toolbar`, `ListHeader`, `ListItem`, and `ValueTable` own their included
 anatomy. The application owns open state, selection, dismissal policy, and
-record actions. `PanelHeader` places the trailing controls the app passes
-directly into its top toolbar's trailing zone.
+record actions. A `ToolbarControlGroup` places the app's trailing controls in
+the top toolbar's trailing zone.
 The header sits on the dialog edge while retaining its internal control inset;
 the selected title receives the full content gutter, the metadata table fills
 the available detail width between the usual outer margins, and the action
@@ -80,8 +80,9 @@ Do not rebuild the dialog or reach into private shadow parts.
 
 [Open the recipe](../ux-demo/?component=recipe-composer-form) · [TSX source](../ux-demo/recipes/composer-form.tsx)
 
-`PanelHeader` supplies the task title and summary, with their ids referenced
-by the form. Production fields own labels, help, and native focus. The field
+A direct `ToolbarText` supplies the task title, with app-owned supporting copy
+below; their ids are referenced by the form. Production fields own labels, help,
+and native focus. The field
 and footer control edges sit directly on the shared 8px inline gutter rather
 than acquiring a second content-item padding inset; major children remain 24px
 apart and related controls use 8px gaps. The app owns
@@ -126,7 +127,7 @@ settles the chrome (reduced motion collapses the slide to instant). A live
 [Open the recipe](../ux-demo/?component=recipe-loading-inspector) · [TSX source](../ux-demo/recipes/loading-inspector.tsx)
 
 A record inspector whose per-record values load asynchronously. Every
-value-bearing component (`PanelHeader`, `ValueTable`/`ValueTableRow`, `Select`,
+value-bearing component (`ToolbarText`, `ValueTable`/`ValueTableRow`, `Select`,
 `SegmentedControl`, `ListItem`, `StateBanner`) takes its `placeholder` from one
 loading flag, so the same real chrome renders a faithful loading state and then
 the populated record — no separate skeleton markup. The composition is the point;

package/docs/surface-scaffold.md

@@ -0,0 +1,17 @@
+# Dialog and popup surface scaffolds
+
+`DialogSurface` and `PopupSurface` configure recurring Web Awesome surface
+geometry without application `::part()` overrides. They do not replace Web
+Awesome behavior: the application still owns open state, focus lifecycle,
+dismissal policy, ids, labels, and content.
+
+Wrap one `wa-dialog` with `DialogSurface`. Choose `size` (`small`, `medium`, or
+`large`), `presentation` (`modal`, `side-sheet`, or `fullscreen`), and independent
+`bodyInset` / `footerInset` (`none`, `compact`, or `comfortable`). The defaults
+match Kerf's medium modal, 8px body, and 16px footer rhythm.
+
+Wrap one `wa-dropdown` with `PopupSurface`. `inset="list-zero"` removes menu
+padding for a child that already owns row insets, `compact` uses 4px, and
+`standard` uses the shared 8px surface inset. Keep the dropdown trigger named and
+preserve `data-morph-skip-children` when its upgraded light-DOM items must retain
+identity across Kerf rerenders.