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

package/ai/component-catalog.json

@@ -248,6 +248,160 @@
         "recipe": "docs/webawesome-theme.md#component-selection-guidance"
       }
     },
+    {
+      "id": "foundation",
+      "name": "Foundation tokens",
+      "category": "Foundation",
+      "kind": "composition",
+      "source": "kerf",
+      "description": "The complete public typography, spacing, breakpoint, geometry, radius, color, focus, and shadow token surface shipped by foundation.css.",
+      "uses": [],
+      "purpose": "Provide the shared semantic token foundation for application themes and every styled Kerf UI component.",
+      "publicExports": [],
+      "useWhen": [
+        "Theme a Kerf application globally or reuse the shipped semantic typography, spacing, geometry, color, focus, and shadow values in application-owned composition CSS."
+      ],
+      "avoidWhen": [
+        "Do not replace a component-specific prop or token with a broad foundation override when only one component instance should change."
+      ],
+      "alternatives": [],
+      "appOwns": [
+        "application theme overrides",
+        "responsive policy at the cataloged device-class breakpoints"
+      ],
+      "variants": [
+        "light",
+        "dark"
+      ],
+      "accessibility": [
+        "Preserve semantic contrast relationships and the visible focus ring when overriding foundation colors."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
+      "delivery": {
+        "manualCssImport": "@kerfjs/ui/foundation.css",
+        "sideEffects": [
+          "css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [],
+      "publicTokens": [
+        "--kui-font-sans",
+        "--kui-font-mono",
+        "--kui-font-2xs",
+        "--kui-font-xs",
+        "--kui-font-s",
+        "--kui-font-m",
+        "--kui-font-l",
+        "--kui-font-2xl",
+        "--kui-font-weight-semibold",
+        "--kui-space-none",
+        "--kui-space-2xs",
+        "--kui-space-xs",
+        "--kui-space-s",
+        "--kui-space-m",
+        "--kui-space-l",
+        "--kui-space-xl",
+        "--kui-bp-mobile",
+        "--kui-bp-tablet",
+        "--kui-bp-desktop",
+        "--kui-bp-xl-desktop",
+        "--kui-layout-inline-margin",
+        "--kui-layout-item-border-width",
+        "--kui-layout-item-padding",
+        "--kui-layout-item-gap",
+        "--kui-layout-content-gap",
+        "--kui-layout-control-gap",
+        "--kui-layout-metadata-gap",
+        "--kui-layout-rounded-radius",
+        "--kui-layout-pill-radius",
+        "--kui-toolbar-group-inner-size",
+        "--kui-toolbar-group-size",
+        "--kui-toolbar-gap",
+        "--kui-radius-s",
+        "--kui-radius-m",
+        "--kui-radius-l",
+        "--kui-radius-circle",
+        "--kui-radius-pill",
+        "--kui-disclosure-icon-scale",
+        "--kui-color-surface",
+        "--kui-color-surface-raised",
+        "--kui-color-surface-lowered",
+        "--kui-color-text",
+        "--kui-color-text-quiet",
+        "--kui-color-text-link",
+        "--kui-color-neutral-fill-quiet",
+        "--kui-color-neutral-fill-normal",
+        "--kui-color-neutral-fill-loud",
+        "--kui-color-neutral-border-quiet",
+        "--kui-color-neutral-border-normal",
+        "--kui-color-neutral-border-loud",
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-neutral-on-normal",
+        "--kui-color-neutral-on-loud",
+        "--kui-color-brand-fill-loud",
+        "--kui-color-brand-fill-quiet",
+        "--kui-color-brand-fill-normal",
+        "--kui-color-brand-border-quiet",
+        "--kui-color-brand-border-normal",
+        "--kui-color-brand-border-loud",
+        "--kui-color-brand-on-quiet",
+        "--kui-color-brand-on-normal",
+        "--kui-color-brand-on-loud",
+        "--kui-color-brand-on-fill",
+        "--kui-color-success-fill-loud",
+        "--kui-color-success-fill-quiet",
+        "--kui-color-success-fill-normal",
+        "--kui-color-success-border-quiet",
+        "--kui-color-success-border-normal",
+        "--kui-color-success-border-loud",
+        "--kui-color-success-on-quiet",
+        "--kui-color-success-on-normal",
+        "--kui-color-success-on-loud",
+        "--kui-color-success-on-fill",
+        "--kui-color-warning-fill-loud",
+        "--kui-color-warning-fill-quiet",
+        "--kui-color-warning-fill-normal",
+        "--kui-color-warning-border-quiet",
+        "--kui-color-warning-border-normal",
+        "--kui-color-warning-border-loud",
+        "--kui-color-warning-on-quiet",
+        "--kui-color-warning-on-normal",
+        "--kui-color-warning-on-loud",
+        "--kui-color-warning-on-fill",
+        "--kui-color-danger-fill-loud",
+        "--kui-color-danger-fill-quiet",
+        "--kui-color-danger-fill-normal",
+        "--kui-color-danger-border-quiet",
+        "--kui-color-danger-border-normal",
+        "--kui-color-danger-border-loud",
+        "--kui-color-danger-on-quiet",
+        "--kui-color-danger-on-normal",
+        "--kui-color-danger-on-loud",
+        "--kui-color-border",
+        "--kui-color-border-quiet",
+        "--kui-color-accent",
+        "--kui-color-accent-text",
+        "--kui-color-success",
+        "--kui-color-success-text",
+        "--kui-color-warning",
+        "--kui-color-warning-text",
+        "--kui-color-danger",
+        "--kui-color-danger-text",
+        "--kui-focus-ring",
+        "--kui-shadow-s",
+        "--kui-shadow-l"
+      ],
+      "links": {
+        "catalogRoute": "?component=foundation",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#foundation-tokens"
+      }
+    },
     {
       "id": "layout",
       "name": "Application layout",
@@ -401,20 +555,104 @@
         "recipe": "docs/layout.md#anatomy"
       }
     },
+    {
+      "id": "workbench",
+      "name": "Workbench",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A desktop-class multi-panel workspace with independently collapsible left and right rails and a bottom drawer around one central work area.",
+      "uses": [],
+      "purpose": "Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.",
+      "publicExports": [
+        "Workbench",
+        "WorkbenchPanel",
+        "WorkbenchProps"
+      ],
+      "useWhen": [
+        "A desktop-class tool needs a central work area plus independently collapsible navigator, inspector, or console regions."
+      ],
+      "avoidWhen": [
+        "Do not shrink the full multi-panel shell onto compact devices; present peripheral content through NavStack or overlay drawers instead.",
+        "Do not use Workbench for one standalone collapsible rail or drawer; use CollapsiblePanel."
+      ],
+      "alternatives": [
+        {
+          "id": "pane",
+          "relationship": "composes-with",
+          "when": "Use Pane inside Workbench regions when fixed header/footer chrome must surround one scroll owner."
+        }
+      ],
+      "appOwns": [
+        "panel presence and content",
+        "collapsed state",
+        "panel sizes",
+        "responsive replacement below desktop",
+        "collapse controls and focus policy"
+      ],
+      "variants": [
+        "main only",
+        "left rail",
+        "right rail",
+        "bottom drawer",
+        "all panels",
+        "independently collapsed panels"
+      ],
+      "accessibility": [
+        "Give the Workbench and each meaningful rail or drawer an accessible label.",
+        "Keep collapse controls outside the disappearing region and move focus when a controlled rerender replaces a collapse control with its restore control."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "child",
+        "notes": [
+          "Workbench owns the rail and drawer separators; each region's content owns its internal padding and scroll behavior."
+        ]
+      },
+      "delivery": {
+        "moduleImport": "@kerfjs/ui/workbench",
+        "manualCssImport": "@kerfjs/ui/workbench.css",
+        "sideEffects": [
+          "manual-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-workbench",
+        "kui-workbench__rail",
+        "kui-workbench__rail--left",
+        "kui-workbench__rail--right",
+        "kui-workbench__center",
+        "kui-workbench__main",
+        "kui-workbench__drawer",
+        "kui-workbench__panel-content"
+      ],
+      "publicTokens": [
+        "--kui-workbench-rail-width",
+        "--kui-workbench-drawer-height"
+      ],
+      "links": {
+        "catalogRoute": "?component=workbench",
+        "documentation": "docs/workbench.md",
+        "recipe": "docs/workbench.md#state-lives-in-the-app"
+      }
+    },
     {
       "id": "sunken-panel",
       "name": "SunkenPanel",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "A lowered application surface with one compact inset and a vertical content stack.",
+      "description": "A rounded or square-corner lowered application surface with one compact inset and a vertical content stack.",
       "uses": [],
-      "purpose": "Group a vertical list of application content on a visually lowered surface with one owned 8px inset.",
+      "purpose": "Group a vertical list of application content on a visually lowered surface with one owned 8px inset and an explicit rounded or square-corner shape.",
       "publicExports": [
         "SunkenPanel"
       ],
       "useWhen": [
-        "A main content region or nested work area needs a darker/lowered background and one compact inset around a vertical stack."
+        "A main content region or nested work area needs a darker/lowered background and one compact inset around a vertical stack.",
+        "Use the default rounded shape for an inset surface; choose square for a flush or edge-to-edge application area."
       ],
       "avoidWhen": [
         "Do not use it merely to add padding, as a substitute for Pane anatomy, or around children that already own the same outer surface."
@@ -428,10 +666,13 @@
       ],
       "appOwns": [
         "region semantics and accessible name",
+        "corner shape",
         "scroll ownership",
         "child ordering and content"
       ],
       "variants": [
+        "rounded surface",
+        "square-corner surface",
         "unnamed surface",
         "named region"
       ],
@@ -503,8 +744,9 @@
         "responsive relocation"
       ],
       "variants": [
-        "divider",
-        "no divider",
+        "bottom divider (default)",
+        "no dividers",
+        "top/right/bottom/left divider combinations",
         "centered content"
       ],
       "accessibility": [
@@ -515,7 +757,7 @@
         "border": "conditional",
         "padding": "self",
         "notes": [
-          "Padding belongs to the toolbar; the optional divider variant also owns its border."
+          "Padding belongs to the toolbar; dividerSides selects any canonical combination of its physical top, right, bottom, and left edges."
         ]
       },
       "delivery": {
@@ -534,7 +776,8 @@
       ],
       "publicTokens": [
         "--kui-color-border",
-        "--kui-font-sans"
+        "--kui-font-sans",
+        "--kui-toolbar-divider-color"
       ],
       "links": {
         "catalogRoute": "?component=toolbar",
@@ -989,63 +1232,69 @@
     },
     {
       "id": "list",
-      "name": "List composition",
+      "name": "List",
       "category": "Navigation",
-      "kind": "composition",
+      "kind": "component",
       "source": "kerf",
-      "description": "Navigation rows and section headers composed as ordinary content items inside a pane.",
+      "description": "A stretch-aligned vertical stack with optional gap, flex growth, vertical scrolling, and independently selectable divider edges.",
       "uses": [
         "list-header",
         "list-action-row",
         "list-item"
       ],
-      "purpose": "Compose navigation with the same pane, content stack, item, and toolbar geometry used throughout the application, including a controlled ListHeader disclosure only when it reveals real content.",
-      "publicExports": [],
+      "purpose": "Standardize vertical component layout and its scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.",
+      "publicExports": [
+        "List"
+      ],
       "useWhen": [
-        "Compose navigation sections in a .kui-content stack, using ListHeader, ListItem, and ListActionRow children plus optional .kui-content-item surfaces."
+        "Arrange component rows or sections in a vertical stretch-aligned stack.",
+        "Let one bounded list own vertical scrolling, flex growth, or one or more physical-edge dividers."
       ],
       "avoidWhen": [
-        "Do not add sidebar-specific wrapper padding or use the pattern for unrelated inline controls.",
-        "Do not place a disclosure chevron on navigation that does not expand content."
+        "Do not use List as semantic list markup; use ul/ol when list semantics are required and apply layout deliberately.",
+        "Do not create nested scroll owners or use divider sides as a substitute for meaningful grouping."
       ],
       "alternatives": [],
       "appOwns": [
-        "information architecture",
-        "routing",
-        "responsive shell behavior"
+        "child semantics and content",
+        "the bounded height needed for scrolling",
+        "gap, flex, and divider choices"
       ],
       "variants": [
-        "section",
-        "icon rows",
-        "iconless rows",
-        "content item",
-        "pane toolbar or footer"
+        "no gap",
+        "standard or custom gap",
+        "boolean or custom flex",
+        "scrollable",
+        "top/right/bottom/left divider combinations"
       ],
       "accessibility": [
-        "Use native links for link navigation, retain ListItem button semantics for actions, and keep standalone header and toolbar actions at least 44px square.",
-        "A ListHeader disclosure controls real content, keeps a stable accessible name and aria-expanded state, and uses the production DisclosureArrow visual."
+        "List adds layout only and no list role; children retain responsibility for their native or ARIA semantics.",
+        "Give a scrollable List a bounded block size and keep keyboard focus visible as its contents scroll."
       ],
       "geometry": {
-        "margin": "child",
-        "border": "child",
-        "padding": "child"
+        "margin": "none",
+        "border": "conditional",
+        "padding": "none",
+        "notes": [
+          "List adds no margin or padding; dividerSides draws only the selected physical edges without changing box geometry."
+        ]
       },
       "delivery": {
-        "manualCssImport": "@kerfjs/ui/layout.css",
+        "browserImport": "@kerfjs/ui/list",
+        "manualCssImport": "@kerfjs/ui/list.css",
         "sideEffects": [
-          "css"
+          "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-content",
-        "kui-content-item"
+        "kui-list"
       ],
       "publicTokens": [
-        "--kui-layout-content-gap",
-        "--kui-layout-inline-margin",
-        "--kui-layout-item-padding",
-        "--kui-layout-rounded-radius"
+        "--kui-color-border",
+        "--kui-layout-item-gap",
+        "--kui-list-divider-color",
+        "--kui-list-gap"
       ],
       "links": {
         "catalogRoute": "?component=list",
@@ -2148,6 +2397,7 @@
         }
       ],
       "appOwns": [
+        "badge content",
         "state mapping",
         "message lifetime",
         "retry behavior",
@@ -2161,10 +2411,12 @@
         "danger",
         "status",
         "alert",
+        "badge",
         "placeholder (loading)"
       ],
       "accessibility": [
-        "Use alert urgency only for an attention-requiring failure."
+        "Use alert urgency only for an attention-requiring failure.",
+        "Keep optional badge content terse and do not rely on its tone alone for meaning."
       ],
       "geometry": {
         "margin": "self",
@@ -2182,7 +2434,9 @@
       "publicClasses": [
         "kui-state-banner",
         "kui-state-banner__action",
+        "kui-state-banner__badge",
         "kui-state-banner__copy",
+        "kui-state-banner__detail",
         "kui-state-banner__icon"
       ],
       "publicTokens": [
@@ -2209,6 +2463,8 @@
         "--kui-state-banner-action-background",
         "--kui-state-banner-action-hover-background",
         "--kui-state-banner-background",
+        "--kui-state-banner-badge-background",
+        "--kui-state-banner-badge-foreground",
         "--kui-state-banner-border",
         "--kui-state-banner-danger-background",
         "--kui-state-banner-danger-border",

package/ai/component-catalog.schema.json

@@ -76,6 +76,7 @@
       "type": "object",
       "required": ["sideEffects"],
       "properties": {
+        "moduleImport": { "type": "string" },
         "browserImport": { "type": "string" },
         "manualCssImport": { "type": "string" },
         "registrationImport": { "type": "string" },

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.22` and `kerfjs@5.0.0-beta.22`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.24` and `kerfjs@5.0.0-beta.24`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/disclosure-arrow`
 
@@ -25,18 +25,20 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { D as DividerSides } from './divider-sides-267FA7sY.js';
 
 interface ToolbarProps {
     leading?: SafeHtml;
     center?: SafeHtml;
     trailing?: SafeHtml;
     label?: string;
-    divider?: boolean;
+    /** Physical divider edges in canonical top/right/bottom/left order. Defaults to bottom. */
+    dividerSides?: DividerSides;
     className?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, divider, className, }: ToolbarProps): SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, dividerSides, className, }: ToolbarProps): SafeHtml;
 
-export { Toolbar, type ToolbarProps };
+export { DividerSides, Toolbar, type ToolbarProps };
 ```
 
 ## `@kerfjs/ui/toolbar-text`
@@ -1087,10 +1089,10 @@ interface CatalogProps {
     /** Status line content shown at the start of the detail footer. */
     status?: SafeHtml;
     /**
-     * Whether to highlight transparent specimens' outer bounds and non-zero
-     * margins. Pass a boolean (rather than omitting the prop) when the active
-     * entry can switch between component and composition previews;
-     * `wireCatalogGeometryOverlay` keeps the overlay synchronized.
+     * Whether to highlight specimens' computed borders (or transparent outer
+     * bounds) and non-zero margins. Pass a boolean (rather than omitting the
+     * prop) when the active entry can switch between component and composition
+     * previews; `wireCatalogGeometryOverlay` keeps the overlay synchronized.
      */
     geometryOverlay?: boolean;
     selectAction?: string;
@@ -1120,11 +1122,15 @@ type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
 type CatalogExampleRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-catalog-example'?: never;
     'data-catalog-example-stack'?: never;
+    'data-catalog-example-label'?: never;
+    'data-catalog-example-note'?: never;
     'data-align'?: never;
 }>;
 type CatalogExampleStackRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-catalog-example'?: never;
     'data-catalog-example-stack'?: never;
+    'data-catalog-example-label'?: never;
+    'data-catalog-example-note'?: never;
     'data-align'?: never;
 }>;
 interface CatalogExampleProps {
@@ -1249,8 +1255,10 @@ interface CatalogRevealOptions {
 declare function revealCatalogEntry(root: HTMLElement, id: string, { block, inline, behavior, media, }?: CatalogRevealOptions): () => void;
 /**
  * Keep a Catalog's opt-in geometry overlay synchronized with its preview.
- * Transparent specimens receive a dashed outer bound and positive margins use
- * devtools-style orange bands. Returns a disposer.
+ * Specimens receive computed border highlights (or a dashed bound when they
+ * have no border and are transparent), while positive computed margins use
+ * devtools-style orange bands. CSS/stylesheet-only changes are observed too.
+ * Returns a disposer.
  */
 declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
 /**
@@ -1352,15 +1360,17 @@ type StateBannerUrgency = 'status' | 'alert';
 interface StateBannerProps {
     title: string;
     detail?: string;
+    /** Optional compact status or count shown beside the title. */
+    badge?: string;
     icon?: SafeHtml;
     action?: SafeHtml;
     tone?: StateBannerTone;
     urgency?: StateBannerUrgency;
     className?: string;
-    /** Render the title and detail as unanimated loading skeletons, keeping the icon and tone. */
+    /** Render the title, badge, and detail as unanimated loading skeletons, keeping the icon and tone. */
     placeholder?: boolean;
 }
-declare function StateBanner({ title, detail, icon, action, tone, urgency, className, placeholder, }: StateBannerProps): SafeHtml;
+declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, className, placeholder, }: StateBannerProps): SafeHtml;
 
 export { StateBanner, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
 ```
@@ -1404,7 +1414,7 @@ export { LoadingSpinner, type LoadingSpinnerProps };
 import * as kerfjs from 'kerfjs';
 
 interface SkeletonProps {
-    /** Width as any CSS length (e.g. `remify(120px)`, `60%`). Defaults to filling its slot. */
+    /** Width as any browser CSS length (e.g. `7.5rem`, `60%`). Defaults to filling its slot. */
     width?: string;
     /** Height as any CSS length. Defaults to a single text line. */
     height?: string;
@@ -1432,10 +1442,13 @@ export { Skeleton, type SkeletonProps };
 ```ts
 import { SafeHtml } from 'kerfjs';
 
+type SunkenPanelShape = 'rounded' | 'square';
 interface SunkenPanelProps {
     children?: SafeHtml | readonly SafeHtml[];
     /** Optional accessible landmark name for a distinct application region. */
     ariaLabel?: string;
+    /** Corner shape: a rounded rectangle (default) or square corners. */
+    shape?: SunkenPanelShape;
     className?: string;
 }
 /**
@@ -1443,9 +1456,9 @@ interface SunkenPanelProps {
  * stack. The panel owns its background and padding; children own their own
  * borders and internal geometry.
  */
-declare function SunkenPanel({ children, ariaLabel, className, }: SunkenPanelProps): SafeHtml;
+declare function SunkenPanel({ children, ariaLabel, shape, className, }: SunkenPanelProps): SafeHtml;
 
-export { SunkenPanel, type SunkenPanelProps };
+export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ```
 
 ## `@kerfjs/ui/token-search-field`
@@ -1578,7 +1591,7 @@ interface TokenSearchCollapsibleOptions {
     collapseOnEmptyBlur?: boolean;
     /** Collapse an empty field on Escape and restore focus to its trigger. Default: true. */
     collapseOnEscape?: boolean;
-    /** Focus the editor on expand and the trigger on Escape-collapse. Default: true. */
+    /** Focus the editor on expand/controlled clear and the trigger on Escape-collapse. Default: true. */
     manageFocus?: boolean;
     /**
      * Keep an empty field expanded when focus moves to a caller-owned surface

package/ai/skill.md

@@ -69,7 +69,7 @@ Quick routing:
 | Navigation row with a trailing action | `ListActionRow`                                            | Use `ListItem` when the trailing region is dormant; never put controls inside either component's SafeHtml slots. Multiline leading icons stay aligned with the first text line.                                                                                                                                                                                                                                                                                                                                             |
 | Page, panel, or dialog heading        | `Toolbar` or `PanelHeader`                                 | Toolbar is persistent chrome; `PanelHeader` heads a panel, dialog, or page.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Exclusive choice                      | `TabBar`, `SegmentedControl`, or `Select`                  | Tabs switch tabpanels; segments expose a few choices; Select handles a longer value list.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| Status or absent content              | `StateBanner` or `EmptyState`                              | Web Awesome callouts suit ecosystem content; toasts are transient and never the only record of important state.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Status or absent content              | `StateBanner` or `EmptyState`                              | `StateBanner` accepts an optional terse, tone-tinted `badge` beside its title for a count or compact status; do not rely on color alone. Web Awesome callouts suit ecosystem content; toasts are transient and never the only record of important state.                                                                                                                                                                                                                                                                    |
 | Loading placeholder                   | a component's `placeholder` prop, or `Skeleton`            | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render its real chrome with value slots as subtle **unanimated** skeletons and interactivity disabled — do not hand-rebuild an empty state. `Skeleton` is the standalone block for a custom slot. Use `LoadingSpinner` for known busy activity, not a skeleton; never animate a skeleton; prefer it over `wa-skeleton`. |
 | Adjustable or static columns          | `ResizableRegion` or CSS grid                              | Use the component only for a user-operable controlled separator.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Structured or ordinary search         | `TokenSearchField` or an input                             | Use token search only when text and ordered filter chips form one editor.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
@@ -101,12 +101,12 @@ Hard rules:
 7. Decorative icons are hidden; controls are named; focus is visible; state never relies on color alone; reduced motion and increased contrast remain usable. `DisclosureArrow` defaults to an 18px root-scaled visual and exposes `--kui-disclosure-arrow-size` for consumer sizing; it never becomes the interaction or accessible-name owner. Put it in an owning native control with a stable accessible name and controlled `aria-expanded`. `ListHeader` toggle mode supplies it when `actionIcon` is omitted, but the app must reveal matching content; a custom icon replaces it. Author replacement icon content facing right before its configured direction transform is applied. Direction changes take the shortest rotation path, with counterclockwise chosen for a 180-degree closed-to-open tie. Kerf `Select` separately keeps its intrinsic Web Awesome expand glyph at `--kui-disclosure-icon-scale: .5`.
 8. `ResizableRegion` uses `wireResizableRegions()` for Arrow, Shift+Arrow, Home/End, and pointer behavior. The app owns size persistence. `handleIcon` replaces decorative dormant glyph content only.
 9. Use controlled `SegmentedControl` for a small exclusive choice set. Select `appearance="toolbar"` when nesting it inside `ToolbarControlGroup`; use rounded or pill shapes for standalone contexts. Handle its action, update `value`, keep meaningful choice labels, and preserve every enabled native button in sequential Tab order.
-10. Compose `AppTab` inside controlled `TabBar`; call `wireTabBars()` once and retain its disposer. It owns same-bar drag mechanics, including proximity-based horizontal edge autoscroll, while the app applies `onReorder` and owns order, selection, panels, close policy, routing, and persistence. Arrow/Home/End select on move by default; pass `activation: 'manual'` (or `TabBar activation="manual"` per strip) so arrow keys move focus only and the user selects with Enter/Space/click — use it when selecting a tab is a heavy action. Use runtime-filtered `rootAttributes` for domain metadata and keep an optional `closeIcon` decorative and noninteractive.
-11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. The app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded, and `wireTokenSearchFields()` 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 returned handle's `expanded(id)` signal or adopt your own via `collapsible.signals`; opt a behavior out only when the app must own it. Do not hand-roll the open handler, the focusout collapse, or a clear-button mousedown guard — the helper owns them. For real-app adoption it also provides a focusout keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn(target)`, so a sibling suggestions/date/help surface does not collapse an empty field), opt-in atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — reach for these instead of re-adding hand-rolled keydown/input handlers around the field.
+10. Compose `AppTab` inside controlled `TabBar`; call `wireTabBars()` once and retain its disposer. It owns same-bar drag mechanics, including proximity-based horizontal edge autoscroll, while the app applies `onReorder` and owns order, selection, panels, close policy, routing, and persistence. Arrow/Home/End select on move by default and restore focus by bar/tab identity when controlled activation replaces the strip; pass `activation: 'manual'` (or `TabBar activation="manual"` per strip) so arrow keys move focus only and the user selects with Enter/Space/click — use it when selecting a tab is a heavy action. Use runtime-filtered `rootAttributes` for domain metadata and keep an optional `closeIcon` decorative and noninteractive.
+11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. The app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded, and `wireTokenSearchFields()` 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 returned handle's `expanded(id)` signal or adopt your own via `collapsible.signals`; opt a behavior out only when the app must own it. Do not hand-roll the open handler, the focusout collapse, a clear-button mousedown guard, or reopening after controlled clear — the helper keeps the replacement editor open and focused. For real-app adoption it also provides a focusout keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn(target)`, so a sibling suggestions/date/help surface does not collapse an empty field), opt-in atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — reach for these instead of re-adding hand-rolled keydown/input handlers around the field.
 12. Demo work uses public production component subpaths and their browser-selected CSS. Give every public visual component its own category-grouped catalog route; list themed third-party components under a clearly labeled collapsible ecosystem section, with a focused route for each. For the complete focused/composition decision, `CatalogExample` / `CatalogExampleStack` row/group nesting, exact specimen selection, geometry-overlay legend and exclusions, skip-marker behavior, and metadata ownership, follow the single [Catalog demo authoring contract](../docs/catalog.md#catalog-demo-authoring-contract), discovered machine-readably through [`catalog-authoring.json`](./catalog-authoring.json). Never infer structure from private `kui-catalog-*` classes. Project each component's deterministic repository-relative demo source and existing documentation path so the detail can expose `View demo source` and `Read guidance` links without a runtime export; also derive first-party component implementation paths from their canonical browser imports, and label Web Awesome documentation as Kerf integration guidance. Declare direct `uses` relationships so `Used by` stays derivable, and theme shell chrome through the same semantic tokens as the stage instead of drawing a substitute. Enable `wireCatalog({ revealSelection: true })` for long desktop sidebars so controlled selections remain visible without moving focus; keep its default compact media guard unless compact scrolling is an explicit product behavior, and use `revealCatalogEntry` for an initial deep link.
 13. The Web Awesome theme makes Tooltip and Popover arrowless by default. Keep that default unless a pointer materially clarifies the anchor; opt back in with `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or a popover's public `--arrow-size`, and use `without-arrow` when local no-arrow intent should survive theme changes. Its non-field chrome uses `--kui-wa-control-inset` (8px controls/items), `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside Accordion, Card, Details, Callout, and Include), and `--kui-wa-container-inset` (16px Tab Panel content); override those tiers instead of restyling individual parts. Checkbox and Radio Group option regions, the Color Picker trigger, and Slider's complete interactive region receive the shared 8px logical inline outer inset because those controls have no bordered field shell. Known Date field captions and bordered text-like field hints align with values at the 9px border-plus-padding inset. OTP Input's label uses the same uppercase xs/650 treatment as other field labels, and both its label and hint use that 9px inset.
 14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Its UX sidebar marks superseded and exceptional entries `Discouraged`. Consider Popup when it replaces custom anchored positioning. Prefer Kerf `Select` over direct Dropdown/Dropdown Item/Select/Option composition, `SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over Split Panel. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame.
-15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Add `.kui-content` for 24px major vertical separation and `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells or duplicate item geometry in wrappers.
+15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Use `List` instead of a hand-written flex-column wrapper when rows or sections need stretch alignment, standard/custom gap, flex growth, one vertical scroll owner, or physical-edge dividers; `dividerSides` uses canonical `t`/`r`/`b`/`l` order. Add `.kui-content` for 24px major vertical separation and `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells, duplicate item geometry in wrappers, or create nested scroll owners.
 16. Keep a visible collapsible pane's collapse control in its own toolbar. When hidden, move its restore control into the adjacent main toolbar on the corresponding logical edge: leading for an inline-start sidebar and trailing for an inline-end inspector. Collapse the pane completely; do not preserve an empty icon-only rail.
 17. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a `ToolbarControlGroup`. For an ordinary icon/action control inside a group, use a plain `<button>` (the group styles `> button` fully) — that is the default; reach for `wa-button` only when you need a Web Awesome feature, chiefly a `wa-dropdown` popup trigger. A popup menu in a toolbar is a `single` `ToolbarControlGroup` wrapping a `wa-dropdown` whose `slot="trigger"` `wa-button` is the toolbar button and whose `wa-dropdown-item`s are the menu, with the dropdown kept under `data-morph-skip-children`. `PanelHeader` composes these for you as a panel/dialog/page heading. Wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `ListHeader` fills the available inline width and keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end 44px action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; never shrink the target to match it. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling 44px native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets.
 18. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, `PanelHeader` title/summary ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.