@kerfjs/ui 5.0.0-beta.23 → 5.0.0-beta.25

package/docs/component-selection.md

@@ -75,41 +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)                              |
-| 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 and pass `ariaLabel` only when the surface is a distinct named region.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Region semantics, accessible name, 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | State mapping, message lifetime, retry/action behavior, and copy.                                                                                        | `@kerfjs/ui/state-banner`                            | [Feedback accessibility](./accessibility.md#shared-rules)                           |
-| Empty or busy content area — `EmptyState`                                                                               | A content region has no items, cannot proceed, or is loading and needs explanation plus an optional action.                                                                                                             | Do not use it for an inline status update; use `StateBanner`. Do not use it for transient success; use `wa-toast`/`wa-toast-item` or the application's toast system.                                                                                                                                                                 | Delegate its optional action; it composes `LoadingSpinner` when busy.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Empty/busy policy, recovery action, illustration, and copy.                                                                                              | `@kerfjs/ui/empty-state`                             | [Feedback ownership](./component-contract.md#extracted-versus-application-specific) |
+| 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
@@ -121,8 +135,13 @@ 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.
+**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.
 
 Common toolbar patterns:
 
@@ -154,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/empty-state/filtered-dark.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 190" width="460" height="190"><defs><clipPath id="cp0"><rect x="214" y="66" width="32" height="32.3"/></clipPath><clipPath id="ct1"><rect x="174.4" y="114.3" width="111.2" height="23"/></clipPath><clipPath id="ct2"><rect x="115.7" y="145.3" width="228.6" height="20.3"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="191" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#cp0)"><g transform="translate(214 66.3)" color="rgb(174, 174, 178)"><svg data-lucide="filter" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="rgb(174, 174, 178)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" font-family="system-ui, -apple-system, sans-serif" style="overflow:hidden" width="32" height="32"><path d="M10 20a1 1 0 0 0 .6.9l2 1A1 1 0 0 0 14 21v-7a2 2 0 0 1 .5-1.3l7.2-8A1 1 0 0 0 21 3H3a1 1 0 0 0-.7 1.7l7.2 8A2 2 0 0 1 10 14Z" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></svg></g></g><text x="174.42" y="133.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(245,245,247)">No matches</text><text x="115.72" y="160.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(174,174,178)">No tickets match the current filters.</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 190" width="460" height="190"><defs><clipPath id="cp0"><rect x="214" y="66" width="32" height="32.3"/></clipPath><clipPath id="ct2"><rect x="174.4" y="114.3" width="111.2" height="23"/></clipPath><clipPath id="ct3"><rect x="115.7" y="145.3" width="228.6" height="20.3"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="191" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#cp0)"><g color="rgb(174, 174, 178)"><clipPath id="svgic1"><rect x="214" y="66.3" width="32" height="32"/></clipPath><g clip-path="url(#svgic1)"><g transform="translate(214 66.344)scale(1.33333)"><path d="M10 20a1 1 0 0 0 .6.9l2 1A1 1 0 0 0 14 21v-7a2 2 0 0 1 .5-1.3l7.2-8A1 1 0 0 0 21 3H3a1 1 0 0 0-.7 1.7l7.2 8A2 2 0 0 1 10 14Z" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></g></g></g></g><text x="174.42" y="133.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(245,245,247)">No matches</text><text x="115.72" y="160.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(174,174,178)">No tickets match the current filters.</text></svg>

package/docs/design/templates/empty-state/filtered.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 190" width="460" height="190"><defs><clipPath id="cp0"><rect x="214" y="66" width="32" height="32.3"/></clipPath><clipPath id="ct1"><rect x="174.4" y="114.3" width="111.2" height="23"/></clipPath><clipPath id="ct2"><rect x="115.7" y="145.3" width="228.6" height="20.3"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="191" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#cp0)"><g transform="translate(214 66.3)" color="rgb(110, 110, 115)"><svg data-lucide="filter" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="rgb(110, 110, 115)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" font-family="system-ui, -apple-system, sans-serif" style="overflow:hidden" width="32" height="32"><path d="M10 20a1 1 0 0 0 .6.9l2 1A1 1 0 0 0 14 21v-7a2 2 0 0 1 .5-1.3l7.2-8A1 1 0 0 0 21 3H3a1 1 0 0 0-.7 1.7l7.2 8A2 2 0 0 1 10 14Z" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></svg></g></g><text x="174.42" y="133.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(29,29,31)">No matches</text><text x="115.72" y="160.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(110,110,115)">No tickets match the current filters.</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 190" width="460" height="190"><defs><clipPath id="cp0"><rect x="214" y="66" width="32" height="32.3"/></clipPath><clipPath id="ct2"><rect x="174.4" y="114.3" width="111.2" height="23"/></clipPath><clipPath id="ct3"><rect x="115.7" y="145.3" width="228.6" height="20.3"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="191" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#cp0)"><g color="rgb(110, 110, 115)"><clipPath id="svgic1"><rect x="214" y="66.3" width="32" height="32"/></clipPath><g clip-path="url(#svgic1)"><g transform="translate(214 66.344)scale(1.33333)"><path d="M10 20a1 1 0 0 0 .6.9l2 1A1 1 0 0 0 14 21v-7a2 2 0 0 1 .5-1.3l7.2-8A1 1 0 0 0 21 3H3a1 1 0 0 0-.7 1.7l7.2 8A2 2 0 0 1 10 14Z" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></g></g></g></g><text x="174.42" y="133.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(29,29,31)">No matches</text><text x="115.72" y="160.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(110,110,115)">No tickets match the current filters.</text></svg>

package/docs/design/templates/empty-state/with-action-dark.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 220" width="460" height="220"><defs><clipPath id="cp0"><rect x="214" y="53" width="32" height="32"/></clipPath><clipPath id="ct1"><rect x="157.7" y="101" width="144.7" height="23"/></clipPath><clipPath id="ct2"><rect x="73.7" y="132" width="312.7" height="20.3"/></clipPath><clipPath id="ct3"><rect x="178.6" y="168.3" width="102.8" height="32"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="212" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#cp0)"><g transform="translate(214 53)" color="rgb(174, 174, 178)"><svg data-lucide="inbox" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="rgb(174, 174, 178)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" font-family="system-ui, -apple-system, sans-serif" style="overflow:hidden" width="32" height="32"><polyline points="22 12 16 12 14 15 10 15 8 12 2 12" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M5.5 5.1 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.4-6.9A2 2 0 0 0 16.8 4H7.2a2 2 0 0 0-1.7 1.1" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></svg></g></g><text x="157.67" y="120" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(245,245,247)">No open tickets</text><text x="73.67" y="147" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(174,174,178)">When someone files a ticket it will show up here.</text><rect x="178.6" y="168.3" width="102.8" height="32" rx="16" fill="rgb(28,28,30)"/><rect x="179.5" y="168.5" width="101" height="31" rx="15.5" fill="none" stroke="rgb(72,72,74)" stroke-width="1"/><text x="191.63" y="190.3" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(245,245,247)">New ticket</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 220" width="460" height="220"><defs><clipPath id="cp0"><rect x="214" y="53" width="32" height="32"/></clipPath><clipPath id="ct2"><rect x="157.7" y="101" width="144.7" height="23"/></clipPath><clipPath id="ct3"><rect x="73.7" y="132" width="312.7" height="20.3"/></clipPath><clipPath id="ct4"><rect x="178.6" y="168.3" width="102.8" height="32"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="212" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#cp0)"><g color="rgb(174, 174, 178)"><clipPath id="svgic1"><rect x="214" y="53" width="32" height="32"/></clipPath><g clip-path="url(#svgic1)"><g transform="translate(214 53)scale(1.33333)"><polyline points="22 12 16 12 14 15 10 15 8 12 2 12" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M5.5 5.1 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.4-6.9A2 2 0 0 0 16.8 4H7.2a2 2 0 0 0-1.7 1.1" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></g></g></g></g><text x="157.67" y="120" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(245,245,247)">No open tickets</text><text x="73.67" y="147" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(174,174,178)">When someone files a ticket it will show up here.</text><rect x="178.6" y="168.3" width="102.8" height="32" rx="16" fill="rgb(28,28,30)"/><rect x="179.5" y="168.5" width="101" height="31" rx="15.5" fill="none" stroke="rgb(72,72,74)" stroke-width="1"/><text x="191.63" y="190.3" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(245,245,247)">New ticket</text></svg>

package/docs/design/templates/empty-state/with-action.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 220" width="460" height="220"><defs><clipPath id="cp0"><rect x="214" y="53" width="32" height="32"/></clipPath><clipPath id="ct1"><rect x="157.7" y="101" width="144.7" height="23"/></clipPath><clipPath id="ct2"><rect x="73.7" y="132" width="312.7" height="20.3"/></clipPath><clipPath id="ct3"><rect x="178.6" y="168.3" width="102.8" height="32"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="212" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#cp0)"><g transform="translate(214 53)" color="rgb(110, 110, 115)"><svg data-lucide="inbox" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="rgb(110, 110, 115)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" font-family="system-ui, -apple-system, sans-serif" style="overflow:hidden" width="32" height="32"><polyline points="22 12 16 12 14 15 10 15 8 12 2 12" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M5.5 5.1 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.4-6.9A2 2 0 0 0 16.8 4H7.2a2 2 0 0 0-1.7 1.1" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></svg></g></g><text x="157.67" y="120" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(29,29,31)">No open tickets</text><text x="73.67" y="147" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(110,110,115)">When someone files a ticket it will show up here.</text><rect x="178.6" y="168.3" width="102.8" height="32" rx="16" fill="rgb(255,255,255)"/><rect x="179.5" y="168.5" width="101" height="31" rx="15.5" fill="none" stroke="rgb(209,209,214)" stroke-width="1"/><text x="191.63" y="190.3" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(29,29,31)">New ticket</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 220" width="460" height="220"><defs><clipPath id="cp0"><rect x="214" y="53" width="32" height="32"/></clipPath><clipPath id="ct2"><rect x="157.7" y="101" width="144.7" height="23"/></clipPath><clipPath id="ct3"><rect x="73.7" y="132" width="312.7" height="20.3"/></clipPath><clipPath id="ct4"><rect x="178.6" y="168.3" width="102.8" height="32"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="212" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#cp0)"><g color="rgb(110, 110, 115)"><clipPath id="svgic1"><rect x="214" y="53" width="32" height="32"/></clipPath><g clip-path="url(#svgic1)"><g transform="translate(214 53)scale(1.33333)"><polyline points="22 12 16 12 14 15 10 15 8 12 2 12" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M5.5 5.1 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.4-6.9A2 2 0 0 0 16.8 4H7.2a2 2 0 0 0-1.7 1.1" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></g></g></g></g><text x="157.67" y="120" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(29,29,31)">No open tickets</text><text x="73.67" y="147" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(110,110,115)">When someone files a ticket it will show up here.</text><rect x="178.6" y="168.3" width="102.8" height="32" rx="16" fill="rgb(255,255,255)"/><rect x="179.5" y="168.5" width="101" height="31" rx="15.5" fill="none" stroke="rgb(209,209,214)" stroke-width="1"/><text x="191.63" y="190.3" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(29,29,31)">New ticket</text></svg>

package/docs/design/templates/empty-state-dark.svg

@@ -1,7 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="492" height="502" viewBox="0 0 492 502">
-  <rect width="492" height="502" fill="#1c1c1e"/>
-  <text x="16" y="30" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#aeaeb2">Icon, title, detail, and action</text>
-  <svg x="16" y="38" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 220" width="460" height="220"><defs><clipPath id="v0-cp0"><rect x="214" y="53" width="32" height="32"/></clipPath><clipPath id="v0-ct1"><rect x="157.7" y="101" width="144.7" height="23"/></clipPath><clipPath id="v0-ct2"><rect x="73.7" y="132" width="312.7" height="20.3"/></clipPath><clipPath id="v0-ct3"><rect x="178.6" y="168.3" width="102.8" height="32"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="212" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#v0-cp0)"><g transform="translate(214 53)" color="rgb(174, 174, 178)"><svg data-lucide="inbox" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="rgb(174, 174, 178)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" font-family="system-ui, -apple-system, sans-serif" style="overflow:hidden" width="32" height="32"><polyline points="22 12 16 12 14 15 10 15 8 12 2 12" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M5.5 5.1 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.4-6.9A2 2 0 0 0 16.8 4H7.2a2 2 0 0 0-1.7 1.1" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></svg></g></g><text x="157.67" y="120" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(245,245,247)">No open tickets</text><text x="73.67" y="147" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(174,174,178)">When someone files a ticket it will show up here.</text><rect x="178.6" y="168.3" width="102.8" height="32" rx="16" fill="rgb(28,28,30)"/><rect x="179.5" y="168.5" width="101" height="31" rx="15.5" fill="none" stroke="rgb(72,72,74)" stroke-width="1"/><text x="191.63" y="190.3" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(245,245,247)">New ticket</text></svg>
-  <text x="16" y="288" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#aeaeb2">No results for a filter</text>
-  <svg x="16" y="296" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 190" width="460" height="190"><defs><clipPath id="v1-cp0"><rect x="214" y="66" width="32" height="32.3"/></clipPath><clipPath id="v1-ct1"><rect x="174.4" y="114.3" width="111.2" height="23"/></clipPath><clipPath id="v1-ct2"><rect x="115.7" y="145.3" width="228.6" height="20.3"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="191" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#v1-cp0)"><g transform="translate(214 66.3)" color="rgb(174, 174, 178)"><svg data-lucide="filter" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="rgb(174, 174, 178)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" font-family="system-ui, -apple-system, sans-serif" style="overflow:hidden" width="32" height="32"><path d="M10 20a1 1 0 0 0 .6.9l2 1A1 1 0 0 0 14 21v-7a2 2 0 0 1 .5-1.3l7.2-8A1 1 0 0 0 21 3H3a1 1 0 0 0-.7 1.7l7.2 8A2 2 0 0 1 10 14Z" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></svg></g></g><text x="174.42" y="133.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(245,245,247)">No matches</text><text x="115.72" y="160.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(174,174,178)">No tickets match the current filters.</text></svg>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 492 502" width="492" height="502"><defs><clipPath id="cp0"><rect x="16" y="38" width="460" height="220"/></clipPath><clipPath id="cp1"><rect x="16" y="296" width="460" height="190"/></clipPath><clipPath id="ct2"><rect x="16" y="16" width="460" height="22"/></clipPath><clipPath id="irc3"><rect x="16" y="38" width="460" height="220" rx="0"/></clipPath><clipPath id="ct5"><rect x="16" y="274" width="460" height="22"/></clipPath><clipPath id="irc6"><rect x="16" y="296" width="460" height="190" rx="0"/></clipPath></defs><rect x="0" y="0" width="492" height="502" rx="0" fill="rgb(28,28,30)"/><text x="16" y="28" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="12" font-weight="600" fill="rgb(174,174,178)">Icon, title, detail, and action</text><g clip-path="url(#cp0)"><g clip-path="url(#irc3)"><clipPath id="svgimg4vclip"><rect x="16" y="38" width="460" height="220"/></clipPath><g clip-path="url(#svgimg4vclip)"><g transform="translate(16 38)"><defs><clipPath id="svgimg4cp0"><rect x="214" y="53" width="32" height="32"/></clipPath><clipPath id="svgimg4ct2"><rect x="157.7" y="101" width="144.7" height="23"/></clipPath><clipPath id="svgimg4ct3"><rect x="73.7" y="132" width="312.7" height="20.3"/></clipPath><clipPath id="svgimg4ct4"><rect x="178.6" y="168.3" width="102.8" height="32"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="212" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#svgimg4cp0)"><g color="rgb(174, 174, 178)"><clipPath id="svgimg4svgic1"><rect x="214" y="53" width="32" height="32"/></clipPath><g clip-path="url(#svgimg4svgic1)"><g transform="translate(214 53)scale(1.33333)"><polyline points="22 12 16 12 14 15 10 15 8 12 2 12" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M5.5 5.1 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.4-6.9A2 2 0 0 0 16.8 4H7.2a2 2 0 0 0-1.7 1.1" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></g></g></g></g><text x="157.67" y="120" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(245,245,247)">No open tickets</text><text x="73.67" y="147" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(174,174,178)">When someone files a ticket it will show up here.</text><rect x="178.6" y="168.3" width="102.8" height="32" rx="16" fill="rgb(28,28,30)"/><rect x="179.5" y="168.5" width="101" height="31" rx="15.5" fill="none" stroke="rgb(72,72,74)" stroke-width="1"/><text x="191.63" y="190.3" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(245,245,247)">New ticket</text></g></g></g></g><text x="16" y="286" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="12" font-weight="600" fill="rgb(174,174,178)">No results for a filter</text><g clip-path="url(#cp1)"><g clip-path="url(#irc6)"><clipPath id="svgimg7vclip"><rect x="16" y="296" width="460" height="190"/></clipPath><g clip-path="url(#svgimg7vclip)"><g transform="translate(16 296)"><defs><clipPath id="svgimg7cp0"><rect x="214" y="66" width="32" height="32.3"/></clipPath><clipPath id="svgimg7ct2"><rect x="174.4" y="114.3" width="111.2" height="23"/></clipPath><clipPath id="svgimg7ct3"><rect x="115.7" y="145.3" width="228.6" height="20.3"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="191" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#svgimg7cp0)"><g color="rgb(174, 174, 178)"><clipPath id="svgimg7svgic1"><rect x="214" y="66.3" width="32" height="32"/></clipPath><g clip-path="url(#svgimg7svgic1)"><g transform="translate(214 66.344)scale(1.33333)"><path d="M10 20a1 1 0 0 0 .6.9l2 1A1 1 0 0 0 14 21v-7a2 2 0 0 1 .5-1.3l7.2-8A1 1 0 0 0 21 3H3a1 1 0 0 0-.7 1.7l7.2 8A2 2 0 0 1 10 14Z" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(174, 174, 178)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></g></g></g></g><text x="174.42" y="133.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(245,245,247)">No matches</text><text x="115.72" y="160.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(174,174,178)">No tickets match the current filters.</text></g></g></g></g></svg>

package/docs/design/templates/empty-state.svg

@@ -1,7 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="492" height="502" viewBox="0 0 492 502">
-  <rect width="492" height="502" fill="#ffffff"/>
-  <text x="16" y="30" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#6e6e73">Icon, title, detail, and action</text>
-  <svg x="16" y="38" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 220" width="460" height="220"><defs><clipPath id="v0-cp0"><rect x="214" y="53" width="32" height="32"/></clipPath><clipPath id="v0-ct1"><rect x="157.7" y="101" width="144.7" height="23"/></clipPath><clipPath id="v0-ct2"><rect x="73.7" y="132" width="312.7" height="20.3"/></clipPath><clipPath id="v0-ct3"><rect x="178.6" y="168.3" width="102.8" height="32"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="212" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#v0-cp0)"><g transform="translate(214 53)" color="rgb(110, 110, 115)"><svg data-lucide="inbox" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="rgb(110, 110, 115)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" font-family="system-ui, -apple-system, sans-serif" style="overflow:hidden" width="32" height="32"><polyline points="22 12 16 12 14 15 10 15 8 12 2 12" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M5.5 5.1 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.4-6.9A2 2 0 0 0 16.8 4H7.2a2 2 0 0 0-1.7 1.1" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></svg></g></g><text x="157.67" y="120" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(29,29,31)">No open tickets</text><text x="73.67" y="147" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(110,110,115)">When someone files a ticket it will show up here.</text><rect x="178.6" y="168.3" width="102.8" height="32" rx="16" fill="rgb(255,255,255)"/><rect x="179.5" y="168.5" width="101" height="31" rx="15.5" fill="none" stroke="rgb(209,209,214)" stroke-width="1"/><text x="191.63" y="190.3" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(29,29,31)">New ticket</text></svg>
-  <text x="16" y="288" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#6e6e73">No results for a filter</text>
-  <svg x="16" y="296" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 190" width="460" height="190"><defs><clipPath id="v1-cp0"><rect x="214" y="66" width="32" height="32.3"/></clipPath><clipPath id="v1-ct1"><rect x="174.4" y="114.3" width="111.2" height="23"/></clipPath><clipPath id="v1-ct2"><rect x="115.7" y="145.3" width="228.6" height="20.3"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="191" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#v1-cp0)"><g transform="translate(214 66.3)" color="rgb(110, 110, 115)"><svg data-lucide="filter" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="rgb(110, 110, 115)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" font-family="system-ui, -apple-system, sans-serif" style="overflow:hidden" width="32" height="32"><path d="M10 20a1 1 0 0 0 .6.9l2 1A1 1 0 0 0 14 21v-7a2 2 0 0 1 .5-1.3l7.2-8A1 1 0 0 0 21 3H3a1 1 0 0 0-.7 1.7l7.2 8A2 2 0 0 1 10 14Z" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></svg></g></g><text x="174.42" y="133.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(29,29,31)">No matches</text><text x="115.72" y="160.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(110,110,115)">No tickets match the current filters.</text></svg>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 492 502" width="492" height="502"><defs><clipPath id="cp0"><rect x="16" y="38" width="460" height="220"/></clipPath><clipPath id="cp1"><rect x="16" y="296" width="460" height="190"/></clipPath><clipPath id="ct2"><rect x="16" y="16" width="460" height="22"/></clipPath><clipPath id="irc3"><rect x="16" y="38" width="460" height="220" rx="0"/></clipPath><clipPath id="ct5"><rect x="16" y="274" width="460" height="22"/></clipPath><clipPath id="irc6"><rect x="16" y="296" width="460" height="190" rx="0"/></clipPath></defs><rect x="0" y="0" width="492" height="502" rx="0" fill="rgb(255,255,255)"/><text x="16" y="28" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="12" font-weight="600" fill="rgb(110,110,115)">Icon, title, detail, and action</text><g clip-path="url(#cp0)"><g clip-path="url(#irc3)"><clipPath id="svgimg4vclip"><rect x="16" y="38" width="460" height="220"/></clipPath><g clip-path="url(#svgimg4vclip)"><g transform="translate(16 38)"><defs><clipPath id="svgimg4cp0"><rect x="214" y="53" width="32" height="32"/></clipPath><clipPath id="svgimg4ct2"><rect x="157.7" y="101" width="144.7" height="23"/></clipPath><clipPath id="svgimg4ct3"><rect x="73.7" y="132" width="312.7" height="20.3"/></clipPath><clipPath id="svgimg4ct4"><rect x="178.6" y="168.3" width="102.8" height="32"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="212" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#svgimg4cp0)"><g color="rgb(110, 110, 115)"><clipPath id="svgimg4svgic1"><rect x="214" y="53" width="32" height="32"/></clipPath><g clip-path="url(#svgimg4svgic1)"><g transform="translate(214 53)scale(1.33333)"><polyline points="22 12 16 12 14 15 10 15 8 12 2 12" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/><path d="M5.5 5.1 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.4-6.9A2 2 0 0 0 16.8 4H7.2a2 2 0 0 0-1.7 1.1" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></g></g></g></g><text x="157.67" y="120" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(29,29,31)">No open tickets</text><text x="73.67" y="147" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(110,110,115)">When someone files a ticket it will show up here.</text><rect x="178.6" y="168.3" width="102.8" height="32" rx="16" fill="rgb(255,255,255)"/><rect x="179.5" y="168.5" width="101" height="31" rx="15.5" fill="none" stroke="rgb(209,209,214)" stroke-width="1"/><text x="191.63" y="190.3" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" fill="rgb(29,29,31)">New ticket</text></g></g></g></g><text x="16" y="286" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="12" font-weight="600" fill="rgb(110,110,115)">No results for a filter</text><g clip-path="url(#cp1)"><g clip-path="url(#irc6)"><clipPath id="svgimg7vclip"><rect x="16" y="296" width="460" height="190"/></clipPath><g clip-path="url(#svgimg7vclip)"><g transform="translate(16 296)"><defs><clipPath id="svgimg7cp0"><rect x="214" y="66" width="32" height="32.3"/></clipPath><clipPath id="svgimg7ct2"><rect x="174.4" y="114.3" width="111.2" height="23"/></clipPath><clipPath id="svgimg7ct3"><rect x="115.7" y="145.3" width="228.6" height="20.3"/></clipPath></defs><rect x="28.5" y="20.5" width="403" height="191" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><g clip-path="url(#svgimg7cp0)"><g color="rgb(110, 110, 115)"><clipPath id="svgimg7svgic1"><rect x="214" y="66.3" width="32" height="32"/></clipPath><g clip-path="url(#svgimg7svgic1)"><g transform="translate(214 66.344)scale(1.33333)"><path d="M10 20a1 1 0 0 0 .6.9l2 1A1 1 0 0 0 14 21v-7a2 2 0 0 1 .5-1.3l7.2-8A1 1 0 0 0 21 3H3a1 1 0 0 0-.7 1.7l7.2 8A2 2 0 0 1 10 14Z" style="marker:none;vector-effect:none;color-interpolation:srgb" fill="none" stroke="rgb(110, 110, 115)" stroke-width="1.5px" stroke-dasharray="none" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="1" fill-opacity="1" opacity="1"/></g></g></g></g><text x="174.42" y="133.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="20" font-weight="650" fill="rgb(29,29,31)">No matches</text><text x="115.72" y="160.34" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" fill="rgb(110,110,115)">No tickets match the current filters.</text></g></g></g></g></svg>