@kerfjs/ui 5.0.0-beta.4 → 5.0.0-beta.41

package/ai/component-catalog.json

@@ -39,6 +39,11 @@
       "accessibility": [
         "Decorative icons are aria-hidden; meaningful icons require a label."
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/lucide-icon",
         "manualCssImport": "@kerfjs/ui/lucide-icon.css",
@@ -90,6 +95,11 @@
       "accessibility": [
         "The arrow is decorative; expose expanded state through aria-expanded on its owning control and keep that control's accessible name stable."
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/disclosure-arrow",
         "manualCssImport": "@kerfjs/ui/disclosure-arrow.css",
@@ -211,6 +221,11 @@
       "accessibility": [
         "Preserve Web Awesome semantics and Kerf focus/contrast tokens."
       ],
+      "geometry": {
+        "margin": "child",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "manualCssImport": "@kerfjs/ui/webawesome.css",
         "sideEffects": [
@@ -233,6 +248,174 @@
         "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",
+        "increased contrast"
+      ],
+      "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-highlight-inset",
+        "--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-pop-fill-loud",
+        "--kui-color-pop-fill-quiet",
+        "--kui-color-pop-fill-normal",
+        "--kui-color-pop-border-quiet",
+        "--kui-color-pop-border-normal",
+        "--kui-color-pop-border-loud",
+        "--kui-color-pop-on-quiet",
+        "--kui-color-pop-on-normal",
+        "--kui-color-pop-on-loud",
+        "--kui-color-pop-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-pop",
+        "--kui-color-pop-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",
@@ -270,6 +453,11 @@
         "Keep reading and focus order coherent when controls wrap or panes relocate, and preserve one scroll owner per pane.",
         "When collapse replaces one control with its counterpart in another toolbar, move focus to the newly rendered restore or collapse control."
       ],
+      "geometry": {
+        "margin": "child",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "manualCssImport": "@kerfjs/ui/layout.css",
         "sideEffects": [
@@ -283,10 +471,6 @@
         "kui-content-item--pill",
         "kui-control-cluster",
         "kui-inline-metadata",
-        "kui-pane",
-        "kui-pane__content",
-        "kui-pane__footer",
-        "kui-pane__toolbar",
         "kui-scroll-owner"
       ],
       "publicTokens": [
@@ -306,423 +490,1129 @@
       }
     },
     {
-      "id": "toolbar",
-      "name": "Toolbar",
+      "id": "pane",
+      "name": "Pane",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Leading, centered, and trailing toolbar composition.",
-      "uses": [
-        "toolbar-text",
-        "toolbar-control-group"
-      ],
-      "purpose": "Leading, centered, and trailing toolbar composition.",
+      "description": "An unpadded application column with optional vertical header/footer slots, one scrolling vertical content stack, and independent logical-edge separators.",
+      "uses": [],
+      "purpose": "Organize a sidebar, main area, inspector, or dialog column into fixed vertical header/footer chrome around one scrolling content owner.",
       "publicExports": [
-        "Toolbar"
+        "Pane"
       ],
       "useWhen": [
-        "Compose persistent application chrome with leading, center, and trailing regions."
+        "An application column needs shared header, content, and optional footer organization with exactly one scrolling content owner.",
+        "A pane boundary needs an opt-in separator on any combination of logical sides."
       ],
       "avoidWhen": [
-        "Do not use for a page title or dialog heading."
+        "Do not use Pane as a padded card or add a competing scroll owner around its content slot.",
+        "Do not enable separators merely as decoration; use them only where the pane owns a real boundary."
       ],
       "alternatives": [
         {
-          "id": "page-header",
-          "relationship": "nearest"
-        },
-        {
-          "id": "dialog-header",
-          "relationship": "nearest"
+          "id": "layout",
+          "relationship": "composes-with",
+          "when": "Use the layout content-item and control classes inside Pane when children need shared geometry."
         }
       ],
       "appOwns": [
-        "actions",
-        "command availability",
-        "responsive relocation"
+        "root and content semantics",
+        "accessible labels",
+        "header, content, and footer children",
+        "which logical boundaries show separators",
+        "responsive placement and visibility"
       ],
       "variants": [
-        "divider",
-        "no divider",
-        "centered content"
+        "content only",
+        "header + content",
+        "header + content + footer",
+        "block-start separator",
+        "block-end separator",
+        "inline-start separator",
+        "inline-end separator"
       ],
       "accessibility": [
-        "Supply a label when the toolbar needs an accessible name."
-      ],
+        "Choose semantic root and content elements that match the region and provide labels for landmark elements.",
+        "Keep fixed header/footer chrome outside the single scrolling content slot so reading and focus order remain coherent."
+      ],
+      "geometry": {
+        "margin": "child",
+        "border": "conditional",
+        "padding": "child",
+        "notes": [
+          "The pane is unpadded; separators are independently opt-in on logical edges and default off."
+        ]
+      },
       "delivery": {
-        "browserImport": "@kerfjs/ui/toolbar",
-        "manualCssImport": "@kerfjs/ui/toolbar.css",
+        "browserImport": "@kerfjs/ui/pane",
+        "manualCssImport": "@kerfjs/ui/pane.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-toolbar",
-        "kui-toolbar__center",
-        "kui-toolbar__leading",
-        "kui-toolbar__trailing"
+        "kui-pane",
+        "kui-pane__content",
+        "kui-pane__footer",
+        "kui-pane__header",
+        "kui-pane__toolbar"
       ],
       "publicTokens": [
-        "--kui-color-border",
-        "--kui-font-sans"
+        "--kui-pane-separator-color",
+        "--kui-pane-separator-width"
       ],
       "links": {
-        "catalogRoute": "?component=toolbar",
+        "catalogRoute": "?component=pane",
         "documentation": "docs/component-selection.md",
-        "recipe": "docs/component-selection.md#ambiguous-choices"
+        "recipe": "docs/layout.md#anatomy"
       }
     },
     {
-      "id": "toolbar-control-group",
-      "name": "ToolbarControlGroup",
+      "id": "nav-stack",
+      "name": "NavStack",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Contained, borderless, pressed, and single-control toolbar groups.",
+      "description": "A controlled one-pane navigation stack that keeps prior views mounted, slides content on push and pop, cross-fades per-view chrome, and moves/restores focus.",
       "uses": [
-        "lucide-icon",
-        "segmented-control"
+        "toolbar-text"
       ],
-      "purpose": "Contained, borderless, pressed, and single-control toolbar groups.",
+      "purpose": "Present a single linear or drill-down flow while preserving each prior view's state, scroll position, and place in the stack.",
       "publicExports": [
-        "ToolbarControlGroup"
+        "NavStackView",
+        "NavStackProps",
+        "NavStack"
       ],
       "useWhen": [
-        "Group related controls inside a toolbar with a supported visual treatment."
+        "A compact surface shows one view at a time and navigation pushes into details or pops back.",
+        "A simple single-pane screen needs the same stable app-layout contract without any nested navigation."
       ],
       "avoidWhen": [
-        "Do not use merely to align unrelated buttons or to imitate an exclusive choice."
+        "Do not use NavStack when a list and detail should remain visible together; use SplitView.",
+        "Do not use it for co-equal top-level destinations on compact devices; wrap one stack per destination in TabScaffold."
       ],
       "alternatives": [
         {
-          "id": "segmented-control",
-          "relationship": "nearest"
+          "id": "split-view",
+          "relationship": "roomy-alternative",
+          "when": "Promote a list-to-detail stack to SplitView once both regions fit together."
         },
         {
-          "id": "wa-button-group",
-          "relationship": "prefer-over"
+          "id": "tab-scaffold",
+          "relationship": "composes-with",
+          "when": "Use one NavStack as each TabScaffold tab's persistent content."
         }
       ],
       "appOwns": [
-        "actions",
-        "pressed state",
-        "expanded state"
+        "ordered view stack and stable keys",
+        "view content and titles",
+        "push and pop actions",
+        "preferred initial focus targets when DOM order is insufficient",
+        "per-view bottom toolbar content or a persistent fallback"
       ],
       "variants": [
-        "contained",
-        "borderless",
-        "pressed",
-        "single"
+        "single root view",
+        "pushed detail view",
+        "toolbar hidden",
+        "per-view bottom toolbar",
+        "persistent bottom-toolbar fallback"
       ],
       "accessibility": [
-        "Name the group when its relationship is not evident from context."
-      ],
+        "Give the stack region an accessible label and every back control a stable action label.",
+        "Use wireNavStack so each controlled push moves focus into the new top view and each pop restores the revealed view's remembered descendant.",
+        "Mark a preferred initial heading or control with data-nav-focus when the first enabled focusable descendant is not the right target."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "conditional",
+        "padding": "child",
+        "notes": [
+          "The stack owns its full-height chrome and viewport; each view owns its internal content padding and scrollable content."
+        ]
+      },
       "delivery": {
-        "browserImport": "@kerfjs/ui/toolbar-control-group",
-        "manualCssImport": "@kerfjs/ui/toolbar-control-group.css",
+        "moduleImport": "@kerfjs/ui/nav-stack",
+        "manualCssImport": "@kerfjs/ui/nav-stack.css",
         "sideEffects": [
-          "browser-condition-css"
+          "manual-css"
         ]
       },
-      "wiring": [],
+      "wiring": [
+        {
+          "export": "wireNavStack",
+          "import": "@kerfjs/ui/wire-nav-stack",
+          "required": true
+        }
+      ],
       "publicClasses": [
-        "kui-toolbar-control-group"
+        "kui-nav-stack",
+        "kui-nav-stack__chrome",
+        "kui-nav-stack__bottom",
+        "kui-nav-stack__chrome--entering",
+        "kui-nav-stack__chrome-copy",
+        "kui-nav-stack__chrome-copy--bottom",
+        "kui-nav-stack__chrome-copy--exiting",
+        "kui-nav-stack__lead",
+        "kui-nav-stack__back",
+        "kui-nav-stack__back-icon",
+        "kui-nav-stack__title",
+        "kui-nav-stack__actions",
+        "kui-nav-stack__viewport",
+        "kui-nav-stack__view",
+        "kui-nav-stack__view--entering",
+        "kui-nav-stack__view--exiting"
       ],
       "publicTokens": [
-        "--kui-color-brand-on-quiet",
-        "--kui-color-neutral-border-loud",
-        "--kui-color-neutral-border-normal",
-        "--kui-color-neutral-fill-loud",
-        "--kui-color-neutral-fill-normal",
-        "--kui-color-neutral-on-loud",
-        "--kui-color-neutral-on-quiet",
-        "--kui-color-surface",
-        "--kui-focus-ring",
-        "--kui-shadow-s",
-        "--kui-toolbar-control-background",
-        "--kui-toolbar-control-border",
-        "--kui-toolbar-control-color",
-        "--kui-toolbar-control-dark-border",
-        "--kui-toolbar-control-hover-background",
-        "--kui-toolbar-control-pressed-background",
-        "--kui-toolbar-control-pressed-border",
-        "--kui-toolbar-control-pressed-color",
-        "--kui-toolbar-control-selected-background",
-        "--kui-toolbar-control-selected-color",
-        "--kui-toolbar-control-selected-shadow"
+        "--kui-nav-stack-transition-duration"
       ],
       "links": {
-        "catalogRoute": "?component=toolbar-control-group",
-        "documentation": "docs/component-selection.md",
-        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+        "catalogRoute": "?component=nav-stack",
+        "documentation": "docs/nav-stack.md",
+        "recipe": "docs/app-layouts.md#decision-matrix"
       }
     },
     {
-      "id": "toolbar-text",
-      "name": "ToolbarText",
+      "id": "split-view",
+      "name": "SplitView",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Large, default, and compact toolbar identity text.",
-      "uses": [],
-      "purpose": "Large, default, and compact toolbar identity text.",
+      "description": "A responsive list-detail layout that shows both panes on roomy device classes and collapses to a navigation stack on compact classes.",
+      "uses": [
+        "nav-stack",
+        "resize"
+      ],
+      "purpose": "Present a selectable list and its detail together when space permits, with a one-pane drill-down replacement on compact devices.",
       "publicExports": [
-        "ToolbarText"
+        "SplitView",
+        "SplitViewProps",
+        "SplitViewResizable"
       ],
       "useWhen": [
-        "Render toolbar identity text at a supported hierarchy size."
+        "Selection in a primary list updates a related detail pane and both should remain visible on roomy device classes.",
+        "The same list-detail flow must become a navigation stack on a handset or portrait tablet."
       ],
       "avoidWhen": [
-        "Do not substitute it for document heading semantics."
+        "Do not use SplitView for a single linear flow; use NavStack.",
+        "Do not use it for a complex desktop tool with multiple peripheral panels; use Workbench."
       ],
       "alternatives": [
         {
-          "id": "page-header",
-          "relationship": "nearest"
+          "id": "recipe-navigation-stack",
+          "relationship": "responsive-alternative",
+          "when": "SplitView renders the one-pane navigation-stack form on compact device classes."
+        },
+        {
+          "id": "workbench",
+          "relationship": "nearest",
+          "when": "Use Workbench when a desktop-class tool needs more than the list and detail regions."
         }
       ],
       "appOwns": [
-        "text",
-        "responsive priority"
+        "device-class policy",
+        "selected item and detail-active state",
+        "list and detail content",
+        "optional list width and persistence",
+        "back action"
       ],
       "variants": [
-        "large",
-        "default",
-        "small"
+        "fixed roomy split",
+        "resizable roomy split",
+        "compact list",
+        "compact detail"
       ],
-      "accessibility": [],
+      "accessibility": [
+        "Give the overall split and both meaningful panes accessible labels.",
+        "Wire the compact back action and optional separator keyboard behavior, and restore focus when controlled navigation replaces a view."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "child",
+        "notes": [
+          "The root owns the two-column split and the list pane owns its separator; list and detail content own their internal padding and scroll behavior."
+        ]
+      },
       "delivery": {
-        "browserImport": "@kerfjs/ui/toolbar-text",
-        "manualCssImport": "@kerfjs/ui/toolbar-text.css",
+        "moduleImport": "@kerfjs/ui/split-view",
+        "manualCssImport": "@kerfjs/ui/split-view.css",
         "sideEffects": [
-          "browser-condition-css"
+          "manual-css"
         ]
       },
-      "wiring": [],
+      "wiring": [
+        {
+          "export": "wireResizableRegions",
+          "import": "@kerfjs/ui/wire-resizable-regions",
+          "required": false
+        },
+        {
+          "export": "wireNavStack",
+          "import": "@kerfjs/ui/wire-nav-stack",
+          "required": true
+        }
+      ],
       "publicClasses": [
-        "kui-toolbar-text"
+        "kui-split-view",
+        "kui-split-view__list",
+        "kui-resizable-region",
+        "kui-split-view__detail",
+        "kui-split-view--compact"
       ],
       "publicTokens": [
-        "--kui-color-neutral-on-quiet",
-        "--kui-font-m",
-        "--kui-font-mono",
-        "--kui-font-s",
-        "--kui-font-xs"
+        "--kui-split-view-list-width"
       ],
       "links": {
-        "catalogRoute": "?component=toolbar-text",
-        "documentation": "docs/component-selection.md",
-        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+        "catalogRoute": "?component=split-view",
+        "documentation": "docs/split-view.md",
+        "recipe": "docs/app-layouts.md#decision-matrix"
       }
     },
     {
-      "id": "headers",
-      "name": "Header composition",
+      "id": "tab-scaffold",
+      "name": "TabScaffold",
       "category": "Structure",
-      "kind": "composition",
+      "kind": "component",
       "source": "kerf",
-      "description": "Page, dialog, and definition-list hierarchy.",
-      "uses": [
-        "page-header",
-        "dialog-header",
-        "value-table"
+      "description": "A controlled compact-device bottom tab scaffold that keeps every tab scene mounted so its navigation and scroll state survive selection changes.",
+      "uses": [],
+      "purpose": "Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.",
+      "publicExports": [
+        "TabScaffoldTab",
+        "TabScaffoldProps",
+        "TabScaffold"
       ],
-      "purpose": "Page, dialog, and definition-list hierarchy.",
-      "publicExports": [],
       "useWhen": [
-        "Compose page, dialog, and definition-list hierarchy from their distinct primitives."
+        "A handset or portrait-tablet app has two to five co-equal top-level destinations.",
+        "Each destination must stay mounted so its NavStack and scroll position survive tab switches."
       ],
       "avoidWhen": [
-        "Do not reuse one header primitive only because its typography looks similar."
+        "Do not use TabScaffold for document tabs or reorderable work items; use TabBar.",
+        "Do not retain the bottom bar on desktop when the same destinations should be promoted to a Workbench rail or sidebar."
       ],
       "alternatives": [
         {
-          "id": "toolbar",
-          "relationship": "nearest"
-        },
-        {
-          "id": "page-header",
-          "relationship": "nearest"
+          "id": "tabs",
+          "relationship": "semantic-alternative",
+          "when": "Use TabBar and AppTab for document-style tabpanels, overflow, closing, or reordering."
         },
         {
-          "id": "dialog-header",
-          "relationship": "nearest"
+          "id": "workbench",
+          "relationship": "roomy-alternative",
+          "when": "Promote top-level destinations to a rail or sidebar on desktop-class layouts."
         }
       ],
       "appOwns": [
-        "scope hierarchy",
-        "copy",
-        "actions"
+        "controlled active tab id",
+        "tab labels, icons, and content",
+        "routing and persistence",
+        "responsive replacement on larger device classes"
       ],
       "variants": [
-        "page",
-        "dialog",
-        "key/value"
+        "text-only tabs",
+        "icon and text tabs",
+        "one NavStack per tab"
       ],
       "accessibility": [
-        "Preserve heading and description relationships for the containing surface."
-      ],
+        "Give the tablist an accessible label and keep exactly the active tab in the sequential focus order.",
+        "Wire selection through the controlled active id while leaving inactive scenes mounted and hidden."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self",
+        "notes": [
+          "The scaffold owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry."
+        ]
+      },
       "delivery": {
+        "moduleImport": "@kerfjs/ui/tab-scaffold",
+        "manualCssImport": "@kerfjs/ui/tab-scaffold.css",
         "sideEffects": [
-          "css"
+          "manual-css"
         ]
       },
-      "wiring": [],
-      "publicClasses": [],
+      "wiring": [
+        {
+          "export": "wireTabScaffold",
+          "import": "@kerfjs/ui/wire-tab-scaffold",
+          "required": true
+        }
+      ],
+      "publicClasses": [
+        "kui-tab-scaffold",
+        "kui-tab-scaffold__scenes",
+        "kui-tab-scaffold__scene",
+        "kui-tab-scaffold__bar",
+        "kui-tab-scaffold__tab",
+        "kui-tab-scaffold__tab-icon",
+        "kui-tab-scaffold__tab-label"
+      ],
       "publicTokens": [],
       "links": {
-        "catalogRoute": "?component=headers",
-        "documentation": "docs/component-selection.md",
-        "recipe": "docs/component-selection.md#ambiguous-choices"
+        "catalogRoute": "?component=tab-scaffold",
+        "documentation": "docs/tab-scaffold.md",
+        "recipe": "docs/app-layouts.md#decision-matrix"
       }
     },
     {
-      "id": "page-header",
-      "name": "PageHeader",
+      "id": "workbench",
+      "name": "Workbench",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Page identity with an optional trailing action.",
+      "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": "Page identity with an optional trailing action.",
+      "purpose": "Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.",
       "publicExports": [
-        "PageHeader"
+        "Workbench",
+        "WorkbenchPanel",
+        "WorkbenchProps"
       ],
       "useWhen": [
-        "Identify a page with its primary heading and optional trailing action."
+        "A desktop-class tool needs a central work area plus independently collapsible navigator, inspector, or console regions."
       ],
       "avoidWhen": [
-        "Do not use for persistent app chrome or a modal task."
+        "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": "toolbar",
-          "relationship": "nearest"
+          "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",
+        "hidden separator",
+        "slide, fade-slide, or instant content",
+        "clipped, scrolling, or popup-visible content",
+        "inline, overlay, or hidden responsive presentation",
+        "safe-area restore control"
+      ],
+      "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__drawer",
+        "kui-workbench__center",
+        "kui-workbench__main",
+        "kui-workbench__panel-content",
+        "kui-workbench__restore"
+      ],
+      "publicTokens": [
+        "--kui-workbench-rail-width",
+        "--kui-workbench-drawer-height",
+        "--kui-workbench-popup-z",
+        "--kui-workbench-overlay-z",
+        "--kui-workbench-overlay-max-width",
+        "--kui-workbench-overlay-max-height",
+        "--kui-workbench-restore-z",
+        "--kui-workbench-restore-inset"
+      ],
+      "links": {
+        "catalogRoute": "?component=workbench",
+        "documentation": "docs/workbench.md",
+        "recipe": "docs/workbench.md#state-lives-in-the-app"
+      }
+    },
+    {
+      "id": "collapsible-panel",
+      "name": "CollapsiblePanel",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A standalone controlled left or right rail or bottom drawer with standard collapse icons and optional compact-overlay behavior through wireSidebar.",
+      "uses": [
+        "lucide-icon"
+      ],
+      "purpose": "Add one independently collapsible peripheral panel without adopting the complete multi-panel Workbench shell.",
+      "publicExports": [
+        "CollapsiblePanelSide",
+        "collapsiblePanelToggleIcon",
+        "CollapsiblePanelToggleProps",
+        "CollapsiblePanelToggle",
+        "CollapsiblePanelProps",
+        "CollapsiblePanel"
+      ],
+      "useWhen": [
+        "An application needs one collapsible side rail or bottom drawer outside a full Workbench.",
+        "The panel should become a dismissable, focus-managed overlay on compact devices."
+      ],
+      "avoidWhen": [
+        "Do not use CollapsiblePanel for a complete editor shell with multiple coordinated rails and a drawer; use Workbench.",
+        "Do not preserve an empty icon-only rail when collapsed; move the restore control into adjacent visible chrome."
+      ],
+      "alternatives": [
+        {
+          "id": "workbench",
+          "relationship": "larger-composition",
+          "when": "Use Workbench when the central work area coordinates multiple peripheral panels."
         },
         {
-          "id": "dialog-header",
-          "relationship": "nearest"
+          "id": "recipe-collapsible-sidebar",
+          "relationship": "recipe",
+          "when": "Use the production recipe for collapse, restore, compact overlay, focus, and persistence ownership."
         }
       ],
       "appOwns": [
-        "title",
-        "action",
-        "responsive placement"
+        "controlled collapsed state",
+        "panel content and size",
+        "toggle placement",
+        "persistence policy",
+        "compact-device policy"
       ],
       "variants": [
-        "title",
-        "title with action"
+        "left rail",
+        "right rail",
+        "bottom drawer",
+        "collapsed",
+        "compact overlay",
+        "compact responsive replacement",
+        "hidden separator",
+        "slide, fade-slide, or instant content",
+        "clipped, scrolling, or popup-visible content",
+        "safe-area restore control"
       ],
       "accessibility": [
-        "Use once for the page primary heading."
+        "Give the panel region and every collapse or restore control an accessible label.",
+        "Keep the restore control outside the disappearing panel and use wireSidebar for focus transfer, Escape, backdrop dismissal, and compact focus trapping."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "child",
+        "notes": [
+          "The panel owns its dock-edge separator and size track; its child content owns internal padding and scrolling."
+        ]
+      },
+      "delivery": {
+        "moduleImport": "@kerfjs/ui/collapsible-panel",
+        "manualCssImport": "@kerfjs/ui/collapsible-panel.css",
+        "sideEffects": [
+          "manual-css"
+        ]
+      },
+      "wiring": [
+        {
+          "export": "wireSidebar",
+          "import": "@kerfjs/ui/wire-sidebar",
+          "required": true
+        }
+      ],
+      "publicClasses": [
+        "kui-collapsible-panel",
+        "kui-collapsible-panel--left",
+        "kui-collapsible-panel--right",
+        "kui-collapsible-panel--bottom",
+        "kui-collapsible-panel__content",
+        "kui-collapsible-panel__restore",
+        "kui-collapsible-panel__backdrop",
+        "kui-collapsible-panel__toggle"
+      ],
+      "publicTokens": [
+        "--kui-collapsible-panel-width",
+        "--kui-collapsible-panel-height",
+        "--kui-collapsible-panel-popup-z",
+        "--kui-collapsible-panel-overlay-z",
+        "--kui-collapsible-panel-restore-z",
+        "--kui-collapsible-panel-restore-inset",
+        "--kui-collapsible-panel-backdrop-z"
+      ],
+      "links": {
+        "catalogRoute": "?component=collapsible-panel",
+        "documentation": "docs/collapsible-panel.md",
+        "recipe": "docs/collapsible-panel.md#recipe-and-coverage"
+      }
+    },
+    {
+      "id": "sunken-panel",
+      "name": "SunkenPanel",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "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 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.",
+        "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."
+      ],
+      "alternatives": [
+        {
+          "id": "layout",
+          "relationship": "composes-with",
+          "when": "Use layout roles for pane, toolbar, scroll, and ordinary content-stack ownership."
+        }
+      ],
+      "appOwns": [
+        "region semantics and accessible name",
+        "corner shape",
+        "scroll ownership",
+        "child ordering and content"
+      ],
+      "variants": [
+        "rounded surface",
+        "square-corner surface",
+        "unnamed surface",
+        "named region"
       ],
+      "accessibility": [
+        "Pass ariaLabel only when the surface is a distinct named region; otherwise it remains a non-landmark grouping."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "self",
+        "notes": [
+          "The root owns one 8px inset and vertical gap; children own their borders and internal geometry."
+        ]
+      },
       "delivery": {
-        "browserImport": "@kerfjs/ui/page-header",
-        "manualCssImport": "@kerfjs/ui/page-header.css",
+        "browserImport": "@kerfjs/ui/sunken-panel",
+        "manualCssImport": "@kerfjs/ui/sunken-panel.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-page-header",
-        "kui-page-header__action"
+        "kui-sunken-panel"
       ],
       "publicTokens": [
-        "--kui-color-text",
-        "--kui-font-2xl",
-        "--kui-font-l",
-        "--kui-page-header-background",
-        "--kui-page-header-border",
-        "--kui-page-header-foreground"
+        "--kui-sunken-panel-background",
+        "--kui-sunken-panel-foreground",
+        "--kui-sunken-panel-gap",
+        "--kui-sunken-panel-padding",
+        "--kui-sunken-panel-radius"
+      ],
+      "links": {
+        "catalogRoute": "?component=sunken-panel",
+        "documentation": "docs/sunken-panel.md",
+        "recipe": "docs/sunken-panel.md#ownership"
+      }
+    },
+    {
+      "id": "toolbar",
+      "name": "Toolbar",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Leading, centered, and trailing toolbar composition.",
+      "uses": [
+        "toolbar-text",
+        "toolbar-control-group"
+      ],
+      "purpose": "Leading, centered, and trailing toolbar composition.",
+      "publicExports": [
+        "Toolbar"
+      ],
+      "useWhen": [
+        "Compose application chrome or a page, panel, or dialog heading with leading, center, and trailing regions."
+      ],
+      "avoidWhen": [
+        "Do not use it as a generic wrapper when no toolbar or heading relationship exists."
+      ],
+      "alternatives": [],
+      "appOwns": [
+        "actions",
+        "command availability",
+        "responsive relocation"
+      ],
+      "variants": [
+        "bottom divider (default)",
+        "no dividers",
+        "top/right/bottom/left divider combinations",
+        "centered content"
+      ],
+      "accessibility": [
+        "Supply a label when the toolbar needs an accessible name."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "conditional",
+        "padding": "self",
+        "notes": [
+          "Padding belongs to the toolbar; dividerSides selects any canonical combination of its physical top, right, bottom, and left edges."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/toolbar",
+        "manualCssImport": "@kerfjs/ui/toolbar.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-toolbar",
+        "kui-toolbar__center",
+        "kui-toolbar__leading",
+        "kui-toolbar__trailing"
+      ],
+      "publicTokens": [
+        "--kui-color-border",
+        "--kui-font-sans",
+        "--kui-toolbar-divider-color"
       ],
       "links": {
-        "catalogRoute": "?component=page-header",
+        "catalogRoute": "?component=toolbar",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#ambiguous-choices"
       }
     },
     {
-      "id": "dialog-header",
-      "name": "DialogHeader",
+      "id": "toolbar-control-group",
+      "name": "ToolbarControlGroup",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Dialog toolbar with aligned icon, title, grouped actions, and a subtitle row.",
+      "description": "Typed toolbar groups for compact, mixed, selected, dropdown, and avatar controls.",
       "uses": [
         "lucide-icon",
-        "toolbar",
-        "toolbar-control-group"
+        "segmented-control"
       ],
-      "purpose": "Dialog toolbar with aligned icon, title, grouped actions, and a subtitle row.",
+      "purpose": "Typed toolbar groups for compact, mixed, selected, dropdown, and avatar controls.",
       "publicExports": [
-        "DialogHeader"
+        "ToolbarControlGroup"
       ],
       "useWhen": [
-        "Label a focused dialog task with a toolbar-aligned title, icon, actions, and subtitle."
+        "Group related controls inside a toolbar with a supported visual treatment.",
+        "Fill it with plain <button> controls (the group styles > button fully); use wa-button only for a Web Awesome feature such as a wa-dropdown popup trigger.",
+        "For an avatar control, set content=avatar and avatarImage instead of inserting an img; one button paints the group and multiple buttons paint only the pressed highlight."
       ],
       "avoidWhen": [
-        "Do not use as the page heading or as a replacement for modal behavior."
+        "Do not use merely to align unrelated buttons or to imitate an exclusive choice.",
+        "Do not reach for wa-button for an ordinary control inside the group — a plain <button> is the default and avoids the Web Awesome dependency."
       ],
       "alternatives": [
         {
-          "id": "page-header",
+          "id": "segmented-control",
           "relationship": "nearest"
         },
         {
-          "id": "wa-dialog",
+          "id": "wa-button-group",
           "relationship": "prefer-over"
         }
       ],
+      "appOwns": [
+        "actions",
+        "pressed state",
+        "expanded state",
+        "avatar image URL"
+      ],
+      "variants": [
+        "contained",
+        "borderless",
+        "pressed",
+        "single",
+        "default or compact size",
+        "comfortable or tight density",
+        "icon, text, mixed, or avatar content",
+        "raised, filled, or outline selected chrome",
+        "brand, neutral, or pop selected tone",
+        "nested dropdown trigger",
+        "avatar scrim",
+        "contained avatar background on a single group or selected multi-button highlight"
+      ],
+      "accessibility": [
+        "Name the group when its relationship is not evident from context."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/toolbar-control-group",
+        "manualCssImport": "@kerfjs/ui/toolbar-control-group.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-toolbar-control-group"
+      ],
+      "publicTokens": [
+        "--kui-color-brand-on-quiet",
+        "--kui-color-pop-border-normal",
+        "--kui-color-pop-fill-normal",
+        "--kui-color-pop-on-normal",
+        "--kui-color-pop-on-quiet",
+        "--kui-color-neutral-border-loud",
+        "--kui-color-neutral-border-normal",
+        "--kui-color-neutral-fill-loud",
+        "--kui-color-neutral-fill-normal",
+        "--kui-color-neutral-on-loud",
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-surface",
+        "--kui-focus-ring",
+        "--kui-shadow-s",
+        "--kui-toolbar-control-background",
+        "--kui-toolbar-control-border",
+        "--kui-toolbar-control-color",
+        "--kui-toolbar-control-dark-border",
+        "--kui-toolbar-control-hover-background",
+        "--kui-toolbar-control-pressed-background",
+        "--kui-toolbar-control-pressed-border",
+        "--kui-toolbar-control-pressed-color",
+        "--kui-toolbar-control-selected-background",
+        "--kui-toolbar-control-selected-color",
+        "--kui-toolbar-control-selected-shadow"
+      ],
+      "links": {
+        "catalogRoute": "?component=toolbar-control-group",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "surface-scaffold",
+      "name": "Surface scaffolds",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Typed Web Awesome dialog and popup surface sizing, presentation, and inset composition.",
+      "uses": [
+        "wa-dialog",
+        "wa-dropdown",
+        "wa-dropdown-item"
+      ],
+      "purpose": "Configure recurring dialog and popup geometry without consumer ::part() overrides.",
+      "publicExports": [
+        "DialogSurface",
+        "PopupSurface"
+      ],
+      "useWhen": [
+        "A Web Awesome dialog or dropdown needs a standard size, presentation, body/footer inset, or list-compatible menu inset.",
+        "A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText."
+      ],
+      "avoidWhen": [
+        "Do not use it as a generic layout wrapper or to replace application-owned modal state and focus lifecycle.",
+        "Do not stack a dialog body inset around children that already own List or content-item geometry; use bodyInset none."
+      ],
+      "alternatives": [],
       "appOwns": [
         "open state",
         "focus lifecycle",
-        "dismissal",
-        "copy",
-        "localized action-group label"
+        "dismissal policy",
+        "content",
+        "outer placement"
       ],
       "variants": [
-        "title",
-        "optional summary",
-        "icon",
-        "actions",
-        "actionsLabel"
+        "small, medium, or large dialog",
+        "modal, side-sheet, or fullscreen dialog",
+        "none, compact, or comfortable body and footer inset",
+        "standard, compact, or zero-inset popup menu"
       ],
       "accessibility": [
-        "Connect the title id and any provided summary id to the dialog host.",
-        "Pass a localized actionsLabel when the automatic action group needs an accessible name."
+        "Supply the wrapped wa-dialog label and retain Web Awesome's native modal and focus behavior.",
+        "Use popup surfaces only for real dropdown menus with named triggers."
       ],
+      "geometry": {
+        "margin": "parent",
+        "border": "child",
+        "padding": "self"
+      },
       "delivery": {
-        "browserImport": "@kerfjs/ui/dialog-header",
-        "manualCssImport": "@kerfjs/ui/dialog-header.css",
+        "browserImport": "@kerfjs/ui/surface-scaffold",
+        "manualCssImport": "@kerfjs/ui/surface-scaffold.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-dialog-header",
-        "kui-dialog-header__actions",
-        "kui-dialog-header__copy",
-        "kui-dialog-header__icon",
-        "kui-dialog-header__identity",
-        "kui-dialog-header__summary",
-        "kui-dialog-header__toolbar"
+        "kui-dialog-surface",
+        "kui-popup-surface"
       ],
       "publicTokens": [
-        "--kui-color-brand-fill-quiet",
-        "--kui-color-brand-on-quiet",
-        "--kui-color-text",
-        "--kui-color-text-quiet",
-        "--kui-dialog-header-border",
-        "--kui-dialog-header-icon-background",
-        "--kui-dialog-header-icon-foreground",
-        "--kui-font-l",
-        "--kui-radius-circle"
+        "--kui-radius-l",
+        "--kui-wa-container-inset",
+        "--kui-wa-surface-inset"
       ],
       "links": {
-        "catalogRoute": "?component=dialog-header",
+        "catalogRoute": "?component=surface-scaffold",
+        "documentation": "docs/surface-scaffold.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "floating-toolbar",
+      "name": "FloatingToolbar",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A transparent, forced-dark toolbar that floats over its container's content.",
+      "uses": [],
+      "purpose": "A transparent, forced-dark toolbar that floats over its container's content.",
+      "publicExports": [
+        "FloatingToolbar"
+      ],
+      "useWhen": [
+        "Float a small cluster of controls (e.g. a drawer restore) over scrolling content without covering dialogs."
+      ],
+      "avoidWhen": [
+        "Do not use for a primary page or panel toolbar, or for anything that must sit above overlays (it is not top-layer)."
+      ],
+      "alternatives": [
+        {
+          "id": "toolbar",
+          "relationship": "nearest"
+        }
+      ],
+      "appOwns": [
+        "controls",
+        "position",
+        "visibility"
+      ],
+      "variants": [
+        "bottom-end",
+        "bottom-start",
+        "bottom",
+        "top-end",
+        "top-start",
+        "top"
+      ],
+      "accessibility": [
+        "Give the toolbar an accessible name (label is required — it exposes role=\"toolbar\")."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/floating-toolbar",
+        "manualCssImport": "@kerfjs/ui/floating-toolbar.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-floating-toolbar"
+      ],
+      "publicTokens": [
+        "--kui-floating-toolbar-inset",
+        "--kui-space-m",
+        "--kui-space-xs"
+      ],
+      "links": {
+        "catalogRoute": "?component=floating-toolbar",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "toolbar-text",
+      "name": "ToolbarText",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Large, default, and compact toolbar identity text.",
+      "uses": [],
+      "purpose": "Large, default, and compact toolbar identity text.",
+      "publicExports": [
+        "ToolbarText"
+      ],
+      "useWhen": [
+        "Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics."
+      ],
+      "avoidWhen": [
+        "Do not omit headingLevel when the text is the page or section heading."
+      ],
+      "alternatives": [],
+      "appOwns": [
+        "text",
+        "responsive priority"
+      ],
+      "variants": [
+        "large",
+        "default",
+        "small",
+        "placeholder (loading)"
+      ],
+      "accessibility": [
+        "Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/toolbar-text",
+        "manualCssImport": "@kerfjs/ui/toolbar-text.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-toolbar-text"
+      ],
+      "publicTokens": [
+        "--kui-color-neutral-on-quiet",
+        "--kui-font-m",
+        "--kui-font-mono",
+        "--kui-font-s",
+        "--kui-font-xs"
+      ],
+      "links": {
+        "catalogRoute": "?component=toolbar-text",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "text",
+      "name": "Text",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Semantic native heading and paragraph text with standard padded content geometry.",
+      "uses": [],
+      "purpose": "Render h1 through h6 or paragraph semantics while consistently supplying the standard transparent border and content padding.",
+      "publicExports": ["Text"],
+      "useWhen": [
+        "Render ordinary application headings or paragraphs that should use native document semantics and the standard text-box inset."
+      ],
+      "avoidWhen": [
+        "Do not use Text for toolbar identity or title content; use ToolbarText inside a Toolbar zone.",
+        "Do not choose a heading variant for visual size alone; preserve the document heading hierarchy."
+      ],
+      "alternatives": [
+        {
+          "id": "toolbar-text",
+          "relationship": "toolbar-specific"
+        },
+        {
+          "id": "list-inset-text",
+          "relationship": "list-geometry-specific"
+        }
+      ],
+      "appOwns": ["semantic variant", "copy", "document heading hierarchy"],
+      "variants": ["h1", "h2", "h3", "h4", "h5", "h6", "p"],
+      "accessibility": [
+        "Text renders the selected native element; choose heading levels by document outline rather than appearance.",
+        "Ordinary global, data, and ARIA attributes pass through to the native element."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self",
+        "notes": [
+          "Text resets the native variant's margin and adds a 1px transparent border plus the standard 8px item padding."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/text",
+        "manualCssImport": "@kerfjs/ui/text.css",
+        "sideEffects": ["browser-condition-css"]
+      },
+      "wiring": [],
+      "publicClasses": ["kui-text"],
+      "publicTokens": ["--kui-layout-item-padding"],
+      "links": {
+        "catalogRoute": "?component=text",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "headers",
+      "name": "Header composition",
+      "category": "Structure",
+      "kind": "composition",
+      "source": "kerf",
+      "description": "Page, dialog, and definition-list hierarchy.",
+      "uses": [
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
+        "value-table"
+      ],
+      "purpose": "Page, dialog, and definition-list hierarchy.",
+      "publicExports": [],
+      "useWhen": [
+        "Compose page, dialog, and definition-list hierarchy from their distinct primitives."
+      ],
+      "avoidWhen": [
+        "Do not reuse one header primitive only because its typography looks similar."
+      ],
+      "alternatives": [],
+      "appOwns": [
+        "scope hierarchy",
+        "copy",
+        "actions"
+      ],
+      "variants": [
+        "page",
+        "dialog",
+        "key/value"
+      ],
+      "accessibility": [
+        "Preserve heading and description relationships for the containing surface."
+      ],
+      "geometry": {
+        "margin": "child",
+        "border": "child",
+        "padding": "child"
+      },
+      "delivery": {
+        "sideEffects": [
+          "css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=headers",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#ambiguous-choices"
       }
@@ -756,11 +1646,17 @@
       ],
       "variants": [
         "icon rows",
-        "iconless rows"
+        "iconless rows",
+        "placeholder (loading)"
       ],
       "accessibility": [
         "Name ValueTable with its label; ValueTableRow supplies dt/dd semantics, and row icons stay decorative unless meaning requires an accessible label."
       ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/value-table",
         "manualCssImport": "@kerfjs/ui/value-table.css",
@@ -796,81 +1692,323 @@
       }
     },
     {
-      "id": "menu",
-      "name": "Menu composition",
+      "id": "row",
+      "name": "Row",
+    "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A horizontal flex row with physical-axis alignment, side-selectable text/control insets, a typed xs gap by default, flex participation, and opt-in wrapping.",
+      "uses": [],
+      "purpose": "Arrange related content horizontally with consistent spacing, optional physical-side text/control insets, and explicit left/center/right/full plus top/middle/bottom/full alignment instead of application-owned flex wrappers.",
+    "publicExports": ["Row"],
+      "cssValueProps": [
+        {
+          "path": "gap",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": ["gap=\"xs\"", "gap={space(\"m\")}", "gap={calc(plus(rem(0.25), pct(10)))}"]
+        },
+        {
+          "path": "flex",
+          "grammar": "flex",
+          "helpers": ["flex"],
+          "shorthands": ["none", "auto", "initial"],
+          "canonicalShorthands": ["none", "auto", "initial"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["flex", "flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
+        }
+      ],
+      "useWhen": [
+        "Arrange a group of sibling components horizontally.",
+        "Choose physical horizontal distribution and vertical alignment without writing one-off flex CSS.",
+        "Use a finite flex keyword or the flex() builder when Row participates in a flexible parent layout.",
+        "Allow a bounded group to wrap while retaining the same typed gap and alignment contract."
+        ,"Apply the standard text or control inset to selected physical sides without an application wrapper."
+      ],
+      "avoidWhen": [
+        "Do not use Row when content belongs in a semantic list or when a named-zone component such as Toolbar owns the composition.",
+        "Do not pass raw CSS strings to gap or flex, mix their distinct grammars, or use s/xl spacing steps without a deliberate exception.",
+        "Do not use alignment to replace semantic grouping or responsive relocation."
+      ],
+    "alternatives": [
+      {
+        "id": "list",
+        "relationship": "axis-alternative",
+        "when": "Use List when the main layout axis is vertical."
+      },
+      {
+        "id": "toolbar",
+        "relationship": "semantic-alternative",
+        "when": "Use Toolbar when content belongs to named leading, center, and trailing application-chrome zones."
+      }
+    ],
+      "appOwns": [
+        "child semantics and content",
+        "alignment and wrapping policy",
+        "typed gap and flex choices"
+      ],
+      "variants": [
+        "left/center/right/full horizontal alignment with l/c/r/f and flex aliases",
+        "top/middle/bottom/full vertical alignment with t/m/c/b/f and flex aliases",
+        "named none/2xs/xs/s/m/l/xl token gap",
+        "typed CssLength gap",
+        "boolean, finite-keyword, or typed CssFlex flex",
+        "nowrap or wrapping",
+        "top/right/bottom/left text and control inset combinations"
+      ],
+      "accessibility": [
+        "Row adds layout only and no grouping role; children retain responsibility for native or ARIA semantics.",
+        "Wrapping must preserve a readable source and focus order."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "conditional",
+        "notes": [
+          "Row adds no margin or border. textInsets adds the full 17px content inset and controlInsets adds 8px on selected physical sides; text wins when both select a side."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/row",
+        "manualCssImport": "@kerfjs/ui/row.css",
+        "sideEffects": ["browser-condition-css"]
+      },
+      "wiring": [],
+      "publicClasses": ["kui-row"],
+      "publicTokens": ["--kui-layout-item-gap", "--kui-row-gap"],
+      "links": {
+        "catalogRoute": "?component=row",
+        "documentation": "docs/layout.md",
+        "recipe": "docs/layout.md#row-and-list-alignment"
+      }
+    },
+    {
+      "id": "spacer",
+      "name": "Spacer",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A decorative, non-shrinking fixed gap or flexible main-axis spacer with typed physical width and height.",
+      "uses": [],
+      "purpose": "Express an intentional empty dimension or consume remaining flex space without application-owned spacer markup or raw CSS lengths.",
+      "publicExports": ["Spacer"],
+      "cssValueProps": [
+        {
+          "path": "width",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": ["width=\"m\"", "width={space(\"m\")}", "width={calc(plus(rem(0.25), pct(10)))}"]
+        },
+        {
+          "path": "height",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": ["height=\"xs\"", "height={rem(1)}"]
+        }
+      ],
+      "useWhen": [
+        "Reserve a fixed empty width or height from the UI spacing scale inside a layout.",
+        "Push siblings to opposite ends of a Row or other flex container by passing flex.",
+        "Use a typed CssLength when the finite spacing scale cannot express the required dimension."
+      ],
+      "avoidWhen": [
+        "Do not use Spacer for ordinary rhythm between siblings; prefer Row.gap or List.gap so the parent owns repeated spacing.",
+        "Do not use Spacer to compensate for component-owned padding, margin, alignment, or responsive layout defects.",
+        "Do not pass raw CSS strings to width or height."
+      ],
+      "alternatives": [
+        {
+          "id": "row",
+          "relationship": "parent-spacing-alternative",
+          "when": "Use Row.gap when every horizontal sibling needs the same repeated separation."
+        },
+        {
+          "id": "list",
+          "relationship": "parent-spacing-alternative",
+          "when": "Use List.gap when every vertical sibling needs the same repeated separation."
+        }
+      ],
+      "appOwns": [
+        "whether the empty space carries structural meaning",
+        "the named or typed dimensions",
+        "whether the spacer fills the flex main axis"
+      ],
+      "variants": [
+        "fixed named width and/or height",
+        "fixed typed CssLength width and/or height",
+        "flexible main-axis space"
+      ],
+      "accessibility": [
+        "Spacer is always decorative and hidden from the accessibility tree.",
+        "Spacer must not contain content or become an interaction target."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none",
+        "notes": [
+          "A fixed Spacer does not shrink. flex changes its flex shorthand from 0 0 auto to 1 1 auto; width and height remain physical dimensions."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/spacer",
+        "manualCssImport": "@kerfjs/ui/spacer.css",
+        "sideEffects": ["browser-condition-css"]
+      },
+      "wiring": [],
+      "publicClasses": ["kui-spacer"],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=spacer",
+        "documentation": "docs/layout.md",
+        "recipe": "docs/layout.md#spacer"
+      }
+    },
+    {
+      "id": "list",
+      "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 vertical stack with physical-axis alignment, side-selectable text/control insets, optional typed token/length gap, flex growth, vertical scrolling, and independently selectable divider edges.",
       "uses": [
-        "menu-header",
-        "menu-action-row",
-        "menu-item"
+        "list-header",
+        "list-action-row",
+        "list-item"
+      ],
+      "purpose": "Standardize vertical component layout, optional physical-side text/control insets, and scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.",
+      "publicExports": [
+        "List",
+        "px",
+        "rem",
+        "em",
+        "pct",
+        "space",
+        "lengthVar",
+        "plus",
+        "calc",
+        "flex"
+      ],
+      "cssValueProps": [
+        {
+          "path": "gap",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": ["gap=\"xs\"", "gap={rem(0.25)}", "gap={calc(plus(rem(0.25), pct(10)))}"]
+        },
+        {
+          "path": "flex",
+          "grammar": "flex",
+          "helpers": ["flex"],
+          "shorthands": ["none", "auto", "initial"],
+          "canonicalShorthands": ["none", "auto", "initial"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
+        }
       ],
-      "purpose": "Compose navigation with the same pane, content stack, item, and toolbar geometry used throughout the application, including a controlled MenuHeader disclosure only when it reveals real content.",
-      "publicExports": [],
       "useWhen": [
-        "Compose navigation sections in a .kui-content stack, using MenuHeader, MenuItem, and MenuActionRow 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.",
+        "Choose a finite gap shorthand such as xs or m, or compose a typed length with @kerfjs/ui/css-values when the spacing scale is insufficient.",
+        "Use a finite flex keyword or the flex() builder when List participates in flexible layout.",
+        "Apply the standard text or control inset to selected physical sides without an application wrapper."
+        ,"Align children horizontally or distribute them vertically with the same physical alignment vocabulary as Row."
       ],
       "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.",
+        "Do not pass raw CSS strings to gap or flex, mix their distinct grammars, or use the off-rhythm s/xl spacing steps without a deliberate exception."
       ],
       "alternatives": [],
       "appOwns": [
-        "information architecture",
-        "routing",
-        "responsive shell behavior"
+        "child semantics and content",
+        "the bounded height needed for scrolling",
+        "typed gap, flex, alignment, and divider choices"
       ],
-      "variants": [
-        "section",
-        "icon rows",
-        "iconless rows",
-        "content item",
-        "pane toolbar or footer"
+      "variants": [
+        "no gap",
+        "standard boolean gap",
+        "named none/2xs/xs/s/m/l/xl token gap",
+        "typed CssLength gap",
+        "boolean, finite-keyword, or typed CssFlex flex",
+        "scrollable",
+        "left/center/right/full horizontal alignment",
+        "top/middle/bottom/full vertical alignment",
+        "top/right/bottom/left divider combinations",
+        "top/right/bottom/left text and control inset combinations"
       ],
       "accessibility": [
-        "Use native links for link navigation, retain MenuItem button semantics for actions, and keep standalone header and toolbar actions at least 44px square.",
-        "A MenuHeader 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": "none",
+        "border": "conditional",
+        "padding": "conditional",
+        "notes": [
+          "List adds no margin. dividerSides draws selected physical edges without changing geometry; textInsets adds the full 17px content inset and controlInsets adds 8px on selected sides, with text winning on overlap."
+        ]
+      },
       "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-pane"
+        "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=menu",
+        "catalogRoute": "?component=list",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#correct-composition-and-duplicated-markup-trap"
       }
     },
     {
-      "id": "menu-header",
-      "name": "MenuHeader",
+      "id": "list-header",
+      "name": "ListHeader",
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Full-width section headings with a semantic neutral count pill or non-count badge, a logical-end action, disclosure states, and protected native-popover trigger metadata.",
+      "description": "Configurable section headings with full-width or shrink-wrapped inline presentation, semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.",
       "uses": [
         "lucide-icon",
-        "disclosure-arrow"
+        "disclosure-arrow",
+        "text"
       ],
-      "purpose": "Fill the available section width while splitting a dormant title and mutually exclusive semantic count or legacy badge from an optional logical-end 44px action with an 18px visual, or render that title cluster as a disclosure button with a default production DisclosureArrow.",
+      "purpose": "Fill the available section width by default, or shrink-wrap without outer geometry when inline, while splitting a dormant title and mutually exclusive semantic count or legacy badge from an optional logical-end action with an 18px visual; disclosure mode renders the title cluster as a button with a default production DisclosureArrow.",
       "publicExports": [
-        "MenuHeader"
+        "ListHeader"
       ],
       "useWhen": [
         "Label a navigation section with an optional semantic count, non-count badge, action, or disclosure state; toggle mode supplies an 18px DisclosureArrow unless actionIcon replaces it."
@@ -881,11 +2019,7 @@
       ],
       "alternatives": [
         {
-          "id": "page-header",
-          "relationship": "nearest"
-        },
-        {
-          "id": "dialog-header",
+          "id": "toolbar",
           "relationship": "nearest"
         }
       ],
@@ -903,29 +2037,39 @@
         "count",
         "badge",
         "action",
-        "toggle"
+        "toggle",
+        "placeholder (loading)",
+        "inline shrink-wrapped presentation",
+        "compact density",
+        "neutral, accent, pop, or danger indicator tone",
+        "before, after, or paired group divider"
       ],
       "accessibility": [
         "A valid count is hidden as duplicate visual text and its required localized countLabel joins the owned heading or disclosure-button accessible name; zero remains visible.",
         "The application controls and updates disclosure state and the revealed content; the default DisclosureArrow mirrors expanded while the button name stays stable. triggerAttributes can describe the controlled relationship but cannot replace the owned accessible name or expanded state."
       ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
-        "browserImport": "@kerfjs/ui/menu-header",
-        "manualCssImport": "@kerfjs/ui/menu-header.css",
+        "browserImport": "@kerfjs/ui/list-header",
+        "manualCssImport": "@kerfjs/ui/list-header.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-menu-header",
-        "kui-menu-header__action",
-        "kui-menu-header__action-layer",
-        "kui-menu-header__badge",
-        "kui-menu-header__count",
-        "kui-menu-header__label",
-        "kui-menu-header__title",
-        "kui-menu-header__toggle"
+        "kui-list-header",
+        "kui-list-header__action",
+        "kui-list-header__action-layer",
+        "kui-list-header__badge",
+        "kui-list-header__count",
+        "kui-list-header__label",
+        "kui-list-header__title",
+        "kui-list-header__toggle"
       ],
       "publicTokens": [
         "--kui-color-neutral-border-quiet",
@@ -933,44 +2077,64 @@
         "--kui-color-neutral-on-quiet",
         "--kui-focus-ring",
         "--kui-font-xs",
-        "--kui-menu-header-action-icon-size",
-        "--kui-menu-header-color",
+        "--kui-list-header-action-icon-size",
+        "--kui-list-header-color",
         "--kui-layout-inline-margin",
         "--kui-layout-item-gap",
         "--kui-layout-item-padding",
         "--kui-layout-pill-radius",
-        "--kui-menu-header-count-font-size",
-        "--kui-menu-header-hover-background"
+        "--kui-list-header-count-font-size",
+        "--kui-list-header-hover-background",
+        "--kui-list-group-divider-color",
+        "--kui-color-brand-on-normal",
+        "--kui-color-pop-fill-normal",
+        "--kui-color-pop-on-normal",
+        "--kui-color-danger-fill-normal",
+        "--kui-color-danger-on-normal"
       ],
       "links": {
-        "catalogRoute": "?component=menu-header",
+        "catalogRoute": "?component=list-header",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
     {
-      "id": "menu-action-row",
-      "name": "MenuActionRow",
+      "id": "list-action-row",
+      "name": "ListActionRow",
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Full-width navigation rows with sibling primary and trailing native-button actions.",
+      "description": "Configurable navigation rows with structured labels, status/busy metadata, density, group dividers, and sibling primary/trailing native-button actions.",
       "uses": [
-        "lucide-icon"
+        "lucide-icon",
+        "loading-spinner"
       ],
       "purpose": "Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.",
       "publicExports": [
-        "MenuActionRow"
+        "ListActionRow"
+      ],
+      "cssValueProps": [
+        {
+          "path": "style",
+          "grammar": "declarations",
+          "helpers": [],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["className=\"app-row\""]
+        }
       ],
       "useWhen": [
         "A navigation or item row needs both a primary selectable action and an independently focusable trailing action."
       ],
       "avoidWhen": [
-        "Use MenuItem when trailing content is dormant metadata; use AppTab only for tablist semantics and ToolbarControlGroup only for toolbar controls."
+        "Use ListItem when trailing content is dormant metadata; use AppTab only for tablist semantics and ToolbarControlGroup only for toolbar controls.",
+        "Do not inject declaration strings; use className, public tokens, and cataloged component props for application styling."
       ],
       "alternatives": [
         {
-          "id": "menu-item",
+          "id": "list-item",
           "relationship": "nearest",
           "when": "Trailing content is noninteractive."
         },
@@ -992,80 +2156,111 @@
         "pressed",
         "disabled primary",
         "disabled trailing action",
-        "multiline"
+        "multiline",
+        "placeholder (loading)",
+        "compact density",
+        "description and status",
+        "busy while retaining content",
+        "interaction-revealed trailing action",
+        "before, after, or paired group divider"
       ],
       "accessibility": [
         "The noninteractive root contains two sibling native buttons in primary-then-trailing focus order; each button has its own action, item identity, accessible name, and disabled state.",
-        "Selection semantics are exposed only by the primary button; label, icon, and trailingActionIcon are dormant SafeHtml and must not contain interactive descendants; never place an interactive descendant in MenuItem.trailing."
+        "Selection semantics are exposed only by the primary button; label, icon, and trailingActionIcon are dormant SafeHtml and must not contain interactive descendants; never place an interactive descendant in ListItem.trailing."
       ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
-        "browserImport": "@kerfjs/ui/menu-action-row",
-        "manualCssImport": "@kerfjs/ui/menu-action-row.css",
+        "browserImport": "@kerfjs/ui/list-action-row",
+        "manualCssImport": "@kerfjs/ui/list-action-row.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-menu-action-row",
-        "kui-menu-action-row__icon",
-        "kui-menu-action-row__label",
-        "kui-menu-action-row__primary",
-        "kui-menu-action-row__trailing-action"
+        "kui-list-action-row",
+        "kui-list-action-row__icon",
+        "kui-list-action-row__label",
+        "kui-list-action-row__primary-label",
+        "kui-list-action-row__description",
+        "kui-list-action-row__status",
+        "kui-list-action-row__primary",
+        "kui-list-action-row__trailing-action"
       ],
       "publicTokens": [
         "--kui-color-brand-border-quiet",
         "--kui-color-brand-fill-normal",
-        "--kui-color-brand-on-quiet",
         "--kui-color-neutral-border-normal",
         "--kui-color-neutral-fill-normal",
         "--kui-color-neutral-fill-quiet",
         "--kui-color-neutral-on-normal",
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-neutral-border-quiet",
         "--kui-focus-ring",
         "--kui-layout-inline-margin",
         "--kui-layout-item-gap",
         "--kui-layout-item-padding",
         "--kui-layout-rounded-radius",
         "--kui-radius-pill",
-        "--kui-menu-action-row-background",
-        "--kui-menu-action-row-border",
-        "--kui-menu-action-row-color",
-        "--kui-menu-action-row-hover-background",
-        "--kui-menu-action-row-hover-border",
-        "--kui-menu-action-row-selected-background",
-        "--kui-menu-action-row-selected-border",
-        "--kui-menu-action-row-selected-color",
-        "--kui-menu-action-row-trailing-hover-background"
+        "--kui-list-action-row-background",
+        "--kui-list-action-row-border",
+        "--kui-list-action-row-color",
+        "--kui-list-action-row-hover-background",
+        "--kui-list-action-row-hover-border",
+        "--kui-list-action-row-selected-background",
+        "--kui-list-action-row-selected-border",
+        "--kui-list-action-row-selected-color",
+        "--kui-list-action-row-trailing-hover-background",
+        "--kui-list-group-divider-color",
+        "--kui-font-xs"
       ],
       "links": {
-        "catalogRoute": "?component=menu-action-row",
+        "catalogRoute": "?component=list-action-row",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
     {
-      "id": "menu-item",
-      "name": "MenuItem",
+      "id": "list-item",
+      "name": "ListItem",
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Selectable, disabled, trailing, and multiline native-button navigation rows with protected domain metadata hooks.",
+      "description": "Configurable native-button navigation rows with structured labels, status/busy metadata, density, group dividers, protected domain metadata hooks, and rounded-boundary overflow clipping.",
       "uses": [
-        "lucide-icon"
+        "lucide-icon",
+        "loading-spinner"
       ],
       "purpose": "Selectable, disabled, trailing, and multiline navigation rows.",
       "publicExports": [
-        "MenuItem"
+        "ListItem"
+      ],
+      "cssValueProps": [
+        {
+          "path": "style",
+          "grammar": "declarations",
+          "helpers": [],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["className=\"app-row\""]
+        }
       ],
       "useWhen": [
-        "Render a selectable, disabled, trailing, or multiline sidebar/navigation action row."
+        "Render a selectable, disabled, trailing, or multiline sidebar/navigation action row whose descendants must remain clipped to the rounded row boundary."
       ],
       "avoidWhen": [
-        "Do not use for an ordinary inline link, form button, isolated ARIA menuitem, or an interactive trailing action; use MenuActionRow for sibling row actions."
+        "Do not use for an ordinary inline link, form button, isolated ARIA menuitem, or an interactive trailing action; use ListActionRow for sibling row actions.",
+        "Do not inject declaration strings; use className, public tokens, and cataloged component props for application styling."
       ],
       "alternatives": [
         {
-          "id": "menu-action-row",
+          "id": "list-action-row",
           "relationship": "nearest",
           "when": "The trailing region must be independently interactive."
         }
@@ -1082,58 +2277,246 @@
         "pressed",
         "disabled",
         "trailing",
-        "multiline"
+        "multiline",
+        "placeholder (loading)",
+        "compact density",
+        "description and status",
+        "busy while retaining content",
+        "before, after, or paired group divider"
       ],
       "accessibility": [
         "Uses native button activation; selected maps to aria-current and pressed to aria-pressed; rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls."
       ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
-        "browserImport": "@kerfjs/ui/menu-item",
-        "manualCssImport": "@kerfjs/ui/menu-item.css",
+        "browserImport": "@kerfjs/ui/list-item",
+        "manualCssImport": "@kerfjs/ui/list-item.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-menu-item",
-        "kui-menu-item__icon",
-        "kui-menu-item__label",
-        "kui-menu-item__trailing"
+        "kui-list-item",
+        "kui-list-item__icon",
+        "kui-list-item__label",
+        "kui-list-item__primary-label",
+        "kui-list-item__description",
+        "kui-list-item__status",
+        "kui-list-item__trailing"
       ],
       "publicTokens": [
         "--kui-color-brand-fill-normal",
-        "--kui-color-brand-on-quiet",
         "--kui-color-neutral-fill-quiet",
         "--kui-color-neutral-on-normal",
         "--kui-color-neutral-on-quiet",
+        "--kui-color-neutral-border-quiet",
         "--kui-focus-ring",
-        "--kui-menu-item-color",
-        "--kui-menu-item-hover-background",
-        "--kui-menu-item-selected-background",
-        "--kui-menu-item-selected-color",
+        "--kui-list-item-color",
+        "--kui-list-item-hover-background",
+        "--kui-list-item-selected-background",
+        "--kui-list-item-selected-color",
+        "--kui-list-group-divider-color",
+        "--kui-font-xs",
         "--kui-layout-inline-margin",
         "--kui-layout-item-gap",
         "--kui-layout-item-padding",
         "--kui-layout-rounded-radius"
       ],
       "links": {
-        "catalogRoute": "?component=menu-item",
+        "catalogRoute": "?component=list-item",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "list-inset-control",
+      "name": "ListInsetControl",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Insets selected physical sides of a self-bordered control in a pane/list content region.",
+      "uses": [],
+      "purpose": "Apply the standard 8px outer margin to all physical sides of a self-bordered control by default, or only the sides selected with the canonical Sides contract.",
+      "publicExports": [
+        "ListInsetControl"
+      ],
+      "useWhen": [
+        "Place a control that carries its own border and padding (an input, a wa-* control) in a pane/list content region so its edges align with .kui-content items."
+      ],
+      "avoidWhen": [
+        "Do not wrap a component that already owns its content-item margin (ListItem, StateBanner, …) — that double-insets it. Use ListInsetText for bare text."
+      ],
+      "alternatives": [
+        {
+          "id": "list-inset-text",
+          "relationship": "nearest"
+        }
+      ],
+      "appOwns": [
+        "the wrapped control and its behavior"
+      ],
+      "variants": [
+        "all-side inset by default",
+        "top/right/bottom/left inset combinations"
+      ],
+      "accessibility": [
+        "A layout wrapper only; it adds no role or name — the wrapped control keeps its own."
+      ],
+      "geometry": {
+        "margin": "self",
+        "border": "child",
+        "padding": "child"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/list-inset-control",
+        "manualCssImport": "@kerfjs/ui/list-inset-control.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-list-inset-control"
+      ],
+      "publicTokens": [
+        "--kui-layout-inline-margin"
+      ],
+      "links": {
+        "catalogRoute": "?component=list-inset-control",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "list-inset-text",
+      "name": "ListInsetText",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Gives selected physical sides of bare text the content-item geometry so it lines up with bordered items.",
+      "uses": [],
+      "purpose": "Apply the full 8px margin + 1px transparent border + 8px padding to all physical sides of bare text by default, or only the sides selected with the canonical Sides contract.",
+      "publicExports": [
+        "ListInsetText"
+      ],
+      "useWhen": [
+        "Line a plain text element up with bordered .kui-content items — it adds the 8px margin, 1px transparent border, and 8px padding the text lacks."
+      ],
+      "avoidWhen": [
+        "Do not use it to wrap an interactive control (use ListInsetControl), or a component that already owns its content-item geometry."
+      ],
+      "alternatives": [
+        {
+          "id": "list-inset-control",
+          "relationship": "nearest"
+        }
+      ],
+      "appOwns": [
+        "the text content"
+      ],
+      "variants": [
+        "all-side inset by default",
+        "top/right/bottom/left inset combinations",
+        "deprecated horizontalOnly compatibility alias for sides=\"rl\""
+      ],
+      "accessibility": [
+        "A layout wrapper only; it adds no role or name."
+      ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/list-inset-text",
+        "manualCssImport": "@kerfjs/ui/list-inset-text.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-list-inset-text",
+        "kui-list-inset-text--horizontal"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=list-inset-text",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
+    {
+      "id": "application-tabs",
+      "name": "Application tabs composition",
+      "category": "Navigation",
+      "kind": "composition",
+      "source": "kerf",
+      "description": "Controlled document tabs with application-owned state and panels.",
+      "uses": [
+        "tabs",
+        "tab-bar",
+        "toolbar-control-group"
+      ],
+      "purpose": "Show AppTab and TabBar in a complete controlled composition.",
+      "publicExports": [],
+      "useWhen": [
+        "Compose application state, panels, actions, overflow, and reordering around TabBar and AppTab."
+      ],
+      "avoidWhen": [
+        "Use SegmentedControl instead for a compact local choice."
+      ],
+      "alternatives": [],
+      "appOwns": [
+        "ordered tabs",
+        "selected tab",
+        "tabpanels",
+        "add and close policy",
+        "routing and persistence"
+      ],
+      "variants": [
+        "overflow",
+        "keyboard and pointer reordering",
+        "adding and closing documents"
+      ],
+      "accessibility": [
+        "Keep one selected tab synchronized with one named tabpanel and retain the wireTabBars disposer."
+      ],
+      "geometry": {
+        "margin": "child",
+        "border": "child",
+        "padding": "child"
+      },
+      "delivery": {
+        "sideEffects": [
+          "css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=application-tabs",
+        "documentation": "docs/accessibility.md",
+        "recipe": "docs/accessibility.md#tabs"
+      }
+    },
     {
       "id": "tabs",
       "name": "AppTab",
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Roving-tabindex-ready tabs with protected application metadata and customizable close affordances.",
+      "description": "Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.",
       "uses": [
         "lucide-icon"
       ],
-      "purpose": "Roving-tabindex-ready tabs with protected application metadata and customizable close affordances.",
+      "purpose": "Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.",
       "publicExports": [
         "AppTab"
       ],
@@ -1154,7 +2537,8 @@
         "selection",
         "close policy",
         "content",
-        "application data attribute values"
+        "application data attribute values",
+        "outer placement"
       ],
       "variants": [
         "selected",
@@ -1163,13 +2547,22 @@
         "leading",
         "trailing",
         "custom close icon",
-        "root metadata"
+        "root metadata",
+        "compact size",
+        "segmented presentation",
+        "icon-only accessible presentation",
+        "label maximum width and truncation"
       ],
       "accessibility": [
         "Compose in a tablist and pair with an application-owned tabpanel.",
         "Keep closeIcon decorative and free of interactive descendants; the owning close button supplies its accessible name and interaction.",
         "Use rootAttributes only for application data-* metadata; component-owned identity, state, action, and role semantics are protected at runtime."
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/app-tab",
         "manualCssImport": "@kerfjs/ui/app-tab.css",
@@ -1218,12 +2611,12 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Controlled, reorderable tab strips with horizontal overflow.",
+      "description": "Controlled tab strips with typed rail, segmented, and inspector presentation plus intrinsic or fill allocation.",
       "uses": [
         "tabs",
         "toolbar-control-group"
       ],
-      "purpose": "Controlled, reorderable tab strips with horizontal overflow.",
+      "purpose": "Controlled tab strips with typed rail, segmented, and inspector presentation plus intrinsic or fill allocation.",
       "publicExports": [
         "TabBar",
         "wireTabBars",
@@ -1254,17 +2647,26 @@
         "selection",
         "panels",
         "routing",
-        "persistence"
+        "persistence",
+        "outer placement"
       ],
       "variants": [
         "leading",
         "trailing",
         "overflow",
-        "reorderable"
+        "reorderable",
+        "rail, segmented, and inspector presentation",
+        "intrinsic or fill allocation",
+        "separate or adjacent trailing action"
       ],
       "accessibility": [
         "Keep exactly one selected tab at tabindex 0 and preserve the wiring keyboard model."
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/tab-bar",
         "manualCssImport": "@kerfjs/ui/tab-bar.css",
@@ -1347,11 +2749,17 @@
         "rounded",
         "pill",
         "equal width",
-        "small"
+        "small",
+        "placeholder (loading)"
       ],
       "accessibility": [
         "Keep choice labels meaningful and every enabled native button in sequential Tab order."
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/segmented-control",
         "manualCssImport": "@kerfjs/ui/segmented-control.css",
@@ -1433,7 +2841,7 @@
         "tokens",
         "query execution",
         "results",
-        "transient focused/open state and focus transfer"
+        "optional override of the collapsible expand/collapse/focus, which wireTokenSearchFields manages by default (adopt an app expanded signal, opt out per behavior, or drive it via the returned handle)"
       ],
       "variants": [
         "tokens",
@@ -1443,10 +2851,15 @@
       ],
       "accessibility": [
         "Announce result changes when useful and keep tokens atomic during editing.",
-        "Keep leading and trailing controls aligned to the first text line while content wraps.",
-        "Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion; visual wrapping remains available.",
-        "In collapsible mode, transfer focus from the named trigger into the revealed searchbox and clear expanded only after focus leaves the component."
-      ],
+        "Keep leading and trailing controls aligned to the first text line while content wraps. Managed Clear restores replacement focus before the next input task, preserving immediate typing and later focus handoffs without a frame delay.",
+        "Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion before the next keystroke. Select All deletion preserves managed open state and replacement focus; persist both edited query and tokens. Visual wrapping remains available.",
+        "In collapsible mode, wireTokenSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/token-search-field",
         "manualCssImport": "@kerfjs/ui/token-search-field.css",
@@ -1552,12 +2965,25 @@
         "start edge",
         "end edge",
         "collapsed",
-        "custom handle icon"
+        "custom handle icon",
+        "hidden separator",
+        "slide, fade-slide, or instant content",
+        "clipped, scrolling, or popup-visible content",
+        "inline, overlay, or hidden responsive presentation",
+        "safe-area restore control"
       ],
       "accessibility": [
         "Preserve separator naming, value ARIA, and keyboard behavior.",
         "Keep handleIcon decorative and free of interactive descendants; the separator owns focus, naming, and pointer/keyboard interaction."
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "conditional",
+        "padding": "conditional",
+        "notes": [
+          "The region delegates visible separator geometry and hit-area padding to its orientation-specific handle."
+        ]
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/resizable-region",
         "manualCssImport": "@kerfjs/ui/resizable-region.css",
@@ -1586,7 +3012,8 @@
         "kui-resizable-region",
         "kui-resizable-region__content",
         "kui-resizable-region__handle",
-        "kui-resizable-region__handle-icon"
+        "kui-resizable-region__handle-icon",
+        "kui-resizable-region__restore"
       ],
       "publicTokens": [
         "--kui-color-border",
@@ -1596,6 +3023,10 @@
         "--kui-radius-s",
         "--kui-resizable-region-handle-active-color",
         "--kui-resizable-region-handle-color",
+        "--kui-resizable-region-overlay-z",
+        "--kui-resizable-region-popup-z",
+        "--kui-resizable-region-restore-inset",
+        "--kui-resizable-region-restore-z",
         "--kui-resizable-region-separator-color",
         "--kui-resizable-region-size"
       ],
@@ -1611,18 +3042,33 @@
       "category": "Controls",
       "kind": "component",
       "source": "kerf",
-      "description": "Controlled Web Awesome select with grouped choices and rerender-stable icon slots.",
+      "description": "Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.",
       "uses": [
         "lucide-icon",
         "wa-select",
         "wa-option"
       ],
-      "purpose": "Controlled Web Awesome select with grouped choices and rerender-stable icon slots.",
+      "purpose": "Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.",
       "publicExports": [
-        "Select"
+        "Select",
+        "uiColor",
+        "colorVar"
+      ],
+      "cssValueProps": [
+        {
+          "path": "choices[].color",
+          "grammar": "color",
+          "helpers": ["uiColor", "colorVar"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["color: uiColor(\"success\")", "color: colorVar(\"--app-choice-color\")"]
+        }
       ],
       "useWhen": [
-        "Choose a controlled value from a moderate or long list, including grouped and icon-bearing choices."
+        "Choose a controlled value from a moderate or long list, including grouped and icon-bearing choices.",
+        "Color an optional choice icon with uiColor() or colorVar(); the CssColor contract intentionally rejects lengths and raw color strings."
       ],
       "avoidWhen": [
         "Do not use for commands or a small choice set that should stay visible."
@@ -1645,18 +3091,35 @@
         "value",
         "validation",
         "choices",
-        "domain mapping"
+        "hint copy",
+        "domain mapping",
+        "outer placement"
       ],
       "variants": [
         "placeholder",
         "disabled",
         "fit menu",
         "grouped",
-        "custom selected content"
+        "custom selected content",
+        "hint text",
+        "placeholder (loading)",
+        "form, toolbar-borderless, or navigation presentation",
+        "default or compact size",
+        "label or icon-only selected presentation",
+        "select- or group-owned focus ring",
+        "label maximum width and truncation"
       ],
       "accessibility": [
-        "Verify the live value, standard events, focus, and rendered output."
-      ],
+        "Verify the live value, standard events, focus, and rendered output.",
+        "A nonempty label names the internal combobox; otherwise ariaLabel supplies a visually hidden label without adding control height, including custom selected content.",
+        "Hint text is visible below the control through Web Awesome's native hint relationship; placeholderText remains the empty value inside the closed control.",
+        "Import select/register once; its scoped lifecycle adapter keeps the latest open/close request authoritative across animation reversals, canceled transitions, and removal. Do not add consumer popup timing or position repairs."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/select",
         "manualCssImport": "@kerfjs/ui/select.css",
@@ -1670,6 +3133,7 @@
         "kui-select",
         "kui-select--custom-selected",
         "kui-select--fit-menu",
+        "kui-select--label-hidden",
         "kui-select__custom-selected",
         "kui-select__group",
         "kui-select__group--separated",
@@ -1678,7 +3142,7 @@
       ],
       "publicTokens": [
         "--kui-color-brand-fill-normal",
-        "--kui-color-brand-on-quiet",
+        "--kui-color-brand-on-fill",
         "--kui-color-neutral-border-quiet",
         "--kui-color-neutral-on-quiet",
         "--kui-disclosure-icon-scale",
@@ -1742,6 +3206,11 @@
       "accessibility": [
         "Choose polite status versus assertive alert deliberately."
       ],
+      "geometry": {
+        "margin": "child",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "sideEffects": [
           "css"
@@ -1762,11 +3231,11 @@
       "category": "Feedback",
       "kind": "component",
       "source": "kerf",
-      "description": "Polite status and assertive alert feedback with semantic tones.",
+      "description": "Polite status and assertive alert feedback with semantic tones, plus non-status pop emphasis for featured or novel content.",
       "uses": [
         "lucide-icon"
       ],
-      "purpose": "Polite status and assertive alert feedback with semantic tones.",
+      "purpose": "Present persistent inline feedback or attractive non-status emphasis with a named semantic tone.",
       "publicExports": [
         "StateBanner"
       ],
@@ -1774,7 +3243,8 @@
         "Place persistent inline semantic status beside affected work."
       ],
       "avoidWhen": [
-        "Do not use for an absent-content screen or transient confirmation."
+        "Do not use for an absent-content screen or transient confirmation.",
+        "Do not use pop as a substitute for success, warning, or danger."
       ],
       "alternatives": [
         {
@@ -1791,6 +3261,7 @@
         }
       ],
       "appOwns": [
+        "badge content",
         "state mapping",
         "message lifetime",
         "retry behavior",
@@ -1799,15 +3270,24 @@
       "variants": [
         "neutral",
         "info",
+        "pop",
         "success",
         "warning",
         "danger",
         "status",
-        "alert"
+        "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",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/state-banner",
         "manualCssImport": "@kerfjs/ui/state-banner.css",
@@ -1819,13 +3299,18 @@
       "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": [
         "--kui-color-brand-border-quiet",
         "--kui-color-brand-fill-quiet",
-        "--kui-color-brand-on-quiet",
+        "--kui-color-brand-on-fill",
+        "--kui-color-pop-border-normal",
+        "--kui-color-pop-fill-quiet",
+        "--kui-color-pop-on-fill",
         "--kui-color-danger-border-quiet",
         "--kui-color-danger-fill-quiet",
         "--kui-color-danger-on-quiet",
@@ -1834,18 +3319,20 @@
         "--kui-color-neutral-on-normal",
         "--kui-color-success-border-normal",
         "--kui-color-success-fill-quiet",
-        "--kui-color-success-on-quiet",
+        "--kui-color-success-on-fill",
         "--kui-color-surface",
         "--kui-color-text-link",
         "--kui-color-warning-border-normal",
         "--kui-color-warning-fill-quiet",
-        "--kui-color-warning-on-quiet",
+        "--kui-color-warning-on-fill",
         "--kui-font-2xs",
         "--kui-font-xs",
         "--kui-radius-pill",
         "--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",
@@ -1855,6 +3342,9 @@
         "--kui-state-banner-info-background",
         "--kui-state-banner-info-border",
         "--kui-state-banner-info-foreground",
+        "--kui-state-banner-pop-background",
+        "--kui-state-banner-pop-border",
+        "--kui-state-banner-pop-foreground",
         "--kui-state-banner-neutral-background",
         "--kui-state-banner-neutral-border",
         "--kui-state-banner-neutral-foreground",
@@ -1915,6 +3405,11 @@
       "accessibility": [
         "Busy state uses aria-busy; the illustration never supplies the only label."
       ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/empty-state",
         "manualCssImport": "@kerfjs/ui/empty-state.css",
@@ -1987,6 +3482,11 @@
       "accessibility": [
         "Labeled spinners use role img; decorative spinners are hidden and stop for reduced motion."
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "browserImport": "@kerfjs/ui/loading-spinner",
         "manualCssImport": "@kerfjs/ui/loading-spinner.css",
@@ -2005,6 +3505,109 @@
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
+    {
+      "id": "skeleton",
+      "name": "Skeleton",
+      "category": "Feedback",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A subtle, unanimated loading placeholder block for a not-yet-known value slot.",
+      "uses": [],
+      "purpose": "A subtle, unanimated loading placeholder block for a not-yet-known value slot.",
+      "publicExports": [
+        "Skeleton"
+      ],
+      "cssValueProps": [
+        {
+          "path": "width",
+          "grammar": "size",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["auto", "min-content", "max-content", "fit-content"],
+          "canonicalShorthands": ["auto", "min-content", "max-content", "fit-content"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["width={em(12)}", "width=\"fit-content\""]
+        },
+        {
+          "path": "height",
+          "grammar": "size",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["auto", "min-content", "max-content", "fit-content"],
+          "canonicalShorthands": ["auto", "min-content", "max-content", "fit-content"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["height={em(1.5)}"]
+        },
+        {
+          "path": "radius",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["radius={px(999)}"]
+        }
+      ],
+      "useWhen": [
+        "Stand in for a value that is still loading, on its own or via a component's placeholder prop, keeping the surrounding layout stable.",
+        "Placeholder a custom or free-text slot with the same visual the components' placeholder mode uses.",
+        "Set width and height with typed length builders or finite intrinsic-size keywords; set radius with a typed length."
+      ],
+      "avoidWhen": [
+        "Do not use for known progress or a busy spinner; use LoadingSpinner.",
+        "Do not animate it or use it as decorative filler.",
+        "Do not pass raw CSS strings or cross property grammars into width, height, or radius."
+      ],
+      "alternatives": [
+        {
+          "id": "wa-skeleton",
+          "relationship": "prefer-over"
+        }
+      ],
+      "appOwns": [
+        "loading lifecycle",
+        "which slots are unknown",
+        "announcing the loading region"
+      ],
+      "variants": [
+        "block",
+        "lines",
+        "labeled",
+        "typed width, height, and radius"
+      ],
+      "accessibility": [
+        "Decorative by default (aria-hidden); pass label to announce it as an image. A component in placeholder mode marks itself aria-busy and disables its own controls."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/skeleton",
+        "manualCssImport": "@kerfjs/ui/skeleton.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-skeleton",
+        "kui-skeleton-lines"
+      ],
+      "publicTokens": [
+        "--kui-skeleton-radius"
+      ],
+      "links": {
+        "catalogRoute": "?component=skeleton",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "wa-button",
       "name": "Button",
@@ -2026,6 +3629,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/button/button.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2064,6 +3672,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/button-group/button-group.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2098,6 +3711,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/copy-button/copy-button.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2137,6 +3755,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/dropdown/dropdown.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2175,6 +3798,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2208,6 +3836,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/checkbox/checkbox.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2241,6 +3874,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "self",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/checkbox-group/checkbox-group.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2277,6 +3915,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/color-picker/color-picker.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2315,6 +3958,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/input/input.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2346,6 +3994,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/known-date/known-date.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2379,6 +4032,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/number-input/number-input.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2417,6 +4075,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/option/option.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2448,6 +4111,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/otp-input/otp-input.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2481,6 +4149,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/radio/radio.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2514,6 +4187,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "self",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/radio-group/radio-group.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2547,6 +4225,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/rating/rating.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2588,6 +4271,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/select/select.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2621,6 +4309,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "self",
+        "border": "none",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/slider/slider.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2652,6 +4345,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/switch/switch.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2683,6 +4381,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/textarea/textarea.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2717,6 +4420,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/time-input/time-input.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2750,6 +4458,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/accordion/accordion.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2783,6 +4496,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/accordion-item/accordion-item.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2814,6 +4532,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/card/card.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2847,6 +4570,15 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "publicTokens": [
+        "--kui-wa-surface-margin",
+        "--kui-wa-surface-inset"
+      ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/details/details.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2880,6 +4612,14 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "publicClasses": [
+        "hide-actions"
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/dialog/dialog.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2911,6 +4651,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "parent",
+        "border": "self",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/divider/divider.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2944,6 +4689,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/drawer/drawer.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -2975,6 +4725,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/page/page.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3006,6 +4761,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/scroller/scroller.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3042,6 +4802,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/split-panel/split-panel.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3076,6 +4841,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/breadcrumb/breadcrumb.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3107,6 +4877,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/breadcrumb-item/breadcrumb-item.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3140,6 +4915,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/pagination/pagination.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3180,6 +4960,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/tab/tab.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3224,6 +5009,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/tab-group/tab-group.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3260,6 +5050,14 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "conditional",
+        "notes": [
+          "Container-mode tab panels own the themed container inset; uncontained panels do not."
+        ]
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/tab-panel/tab-panel.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3293,6 +5091,11 @@
       ],
       "recommendation": "exceptional",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/tree/tree.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3328,6 +5131,11 @@
       ],
       "recommendation": "exceptional",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/tree-item/tree-item.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3359,6 +5167,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/badge/badge.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3395,6 +5208,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/callout/callout.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3426,6 +5244,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/progress-bar/progress-bar.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3457,6 +5280,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/progress-ring/progress-ring.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3488,6 +5316,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/skeleton/skeleton.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3524,6 +5357,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/spinner/spinner.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3562,6 +5400,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/tag/tag.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3604,6 +5447,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/toast/toast.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3647,6 +5495,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/toast-item/toast-item.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3680,6 +5533,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/tooltip/tooltip.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3713,6 +5571,11 @@
       ],
       "recommendation": "exceptional",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/animated-image/animated-image.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3746,6 +5609,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/avatar/avatar.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3780,6 +5648,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/carousel/carousel.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3811,6 +5684,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/carousel-item/carousel-item.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3844,6 +5722,11 @@
       ],
       "recommendation": "exceptional",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/comparison/comparison.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3880,6 +5763,11 @@
           "relationship": "prefer-kerf"
         }
       ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/icon/icon.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3911,6 +5799,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/markdown/markdown.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3942,6 +5835,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/qr-code/qr-code.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -3975,6 +5873,11 @@
       ],
       "recommendation": "avoid",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/zoomable-frame/zoomable-frame.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4008,6 +5911,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/animation/animation.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4039,6 +5947,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/format-bytes/format-bytes.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4070,6 +5983,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/format-date/format-date.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4101,6 +6019,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/format-number/format-number.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4132,6 +6055,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/include/include.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4163,6 +6091,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/intersection-observer/intersection-observer.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4194,6 +6127,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/mutation-observer/mutation-observer.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4227,6 +6165,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/popover/popover.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4258,6 +6201,11 @@
       ],
       "recommendation": "conditional",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/popup/popup.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4289,6 +6237,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/random-content/random-content.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4320,6 +6273,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/relative-time/relative-time.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4351,6 +6309,11 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
       "delivery": {
         "registrationImport": "@awesome.me/webawesome/dist/components/resize-observer/resize-observer.js",
         "themeCssImport": "@kerfjs/ui/webawesome.css",
@@ -4371,13 +6334,41 @@
       "kind": "recipe",
       "source": "kerf",
       "purpose": "Toolbar, navigation, content, and inspector shell with controlled resizing and explicit pane scroll owners.",
-      "uses": ["toolbar", "toolbar-text", "toolbar-control-group", "menu-header", "menu-item", "page-header", "resize", "value-table", "layout"],
-      "useWhen": ["A desktop workspace needs persistent chrome and user-adjustable navigation or inspector panes."],
-      "avoidWhen": ["Use ordinary CSS grid when panes are static or the product does not need a user-operable separator."],
-      "appOwns": ["routing", "pane visibility", "pane sizes and persistence", "workspace data"],
-      "accessibility": ["Each pane has one scroll owner and each resize handle keeps its separator keyboard contract."],
-      "delivery": { "sideEffects": ["lazy-recipe-css"] },
-      "links": { "catalogRoute": "?component=recipe-app-shell", "documentation": "docs/recipes.md#desktop-application-shell", "recipe": "docs/recipes.md#desktop-application-shell" }
+      "uses": [
+        "toolbar",
+        "toolbar-text",
+        "toolbar-control-group",
+        "list-header",
+        "list-item",
+        "resize",
+        "value-table",
+        "layout"
+      ],
+      "useWhen": [
+        "A desktop workspace needs persistent chrome and user-adjustable navigation or inspector panes."
+      ],
+      "avoidWhen": [
+        "Use ordinary CSS grid when panes are static or the product does not need a user-operable separator."
+      ],
+      "appOwns": [
+        "routing",
+        "pane visibility",
+        "pane sizes and persistence",
+        "workspace data"
+      ],
+      "accessibility": [
+        "Each pane has one scroll owner and each resize handle keeps its separator keyboard contract."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-app-shell",
+        "documentation": "docs/recipes.md#desktop-application-shell",
+        "recipe": "docs/recipes.md#desktop-application-shell"
+      }
     },
     {
       "id": "recipe-navigation-sidebar",
@@ -4386,13 +6377,37 @@
       "kind": "recipe",
       "source": "kerf",
       "purpose": "Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.",
-      "uses": ["menu-header", "menu-item", "toolbar", "toolbar-control-group"],
-      "useWhen": ["A workspace sidebar needs the shared toolbar/content/footer pane model, 24px major section rhythm, and 44px row and utility-action targets."],
-      "avoidWhen": ["Use ordinary links when menu selection, section, and sidebar anatomy do not apply."],
-      "appOwns": ["information architecture", "routing", "permissions", "disclosure state"],
-      "accessibility": ["Native buttons retain names, current state, sequential focus, and disclosure state; rows and standalone footer actions remain at least 44px tall."],
-      "delivery": { "sideEffects": ["lazy-recipe-css"] },
-      "links": { "catalogRoute": "?component=recipe-navigation-sidebar", "documentation": "docs/recipes.md#navigation-sidebar", "recipe": "docs/recipes.md#navigation-sidebar" }
+      "uses": [
+        "list-header",
+        "list-item",
+        "toolbar",
+        "toolbar-control-group"
+      ],
+      "useWhen": [
+        "A workspace sidebar needs the shared toolbar/content/footer pane model, 24px major section rhythm, and 44px row and utility-action targets."
+      ],
+      "avoidWhen": [
+        "Use ordinary links when menu selection, section, and sidebar anatomy do not apply."
+      ],
+      "appOwns": [
+        "information architecture",
+        "routing",
+        "permissions",
+        "disclosure state"
+      ],
+      "accessibility": [
+        "Native buttons retain names, current state, sequential focus, and disclosure state; rows and standalone footer actions remain at least 44px tall."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-navigation-sidebar",
+        "documentation": "docs/recipes.md#navigation-sidebar",
+        "recipe": "docs/recipes.md#navigation-sidebar"
+      }
     },
     {
       "id": "recipe-workspace-header",
@@ -4401,28 +6416,82 @@
       "kind": "recipe",
       "source": "kerf",
       "purpose": "Page identity with primary, secondary, and overflow actions that relocate at narrow widths.",
-      "uses": ["page-header", "state-banner", "layout"],
-      "useWhen": ["A workspace page needs one primary heading and a small prioritized action set."],
-      "avoidWhen": ["Use Toolbar for persistent application chrome or DialogHeader for a focused modal task."],
-      "appOwns": ["authorization", "command behavior", "breadcrumbs", "product copy"],
-      "accessibility": ["Heading order and action focus order remain stable when controls wrap."],
-      "delivery": { "sideEffects": ["lazy-recipe-css"] },
-      "links": { "catalogRoute": "?component=recipe-workspace-header", "documentation": "docs/recipes.md#workspace-header", "recipe": "docs/recipes.md#workspace-header" }
+      "uses": [
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
+        "state-banner",
+        "layout"
+      ],
+      "useWhen": [
+        "A workspace page needs one primary heading and a small prioritized action set."
+      ],
+      "avoidWhen": [
+        "Use a smaller local heading when the page does not need actions or persistent identity."
+      ],
+      "appOwns": [
+        "authorization",
+        "command behavior",
+        "breadcrumbs",
+        "product copy"
+      ],
+      "accessibility": [
+        "Heading order and action focus order remain stable when controls wrap."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-workspace-header",
+        "documentation": "docs/recipes.md#workspace-header",
+        "recipe": "docs/recipes.md#workspace-header"
+      }
     },
     {
-      "id": "recipe-master-detail-dialog",
-      "name": "Master-detail dialog",
+      "id": "recipe-list-detail-dialog",
+      "name": "List-detail dialog",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
-      "purpose": "Production modal containing a DialogHeader, navigable record master list, and ValueTable detail.",
-      "uses": ["dialog-header", "menu-header", "menu-item", "value-table", "wa-dialog", "wa-button"],
-      "useWhen": ["A focused task compares several records without leaving the current workspace."],
-      "avoidWhen": ["Use a page when the task needs a durable route or substantially more working space."],
-      "appOwns": ["open state", "selected record", "dismiss policy", "record actions"],
-      "accessibility": ["Web Awesome owns modal focus and Escape; the application adapter restores the invoking control after hide, and DialogHeader supplies the visible hierarchy."],
-      "delivery": { "sideEffects": ["lazy-recipe-css", "individual-custom-element-registration"] },
-      "links": { "catalogRoute": "?component=recipe-master-detail-dialog", "documentation": "docs/recipes.md#master-detail-dialog", "recipe": "docs/recipes.md#master-detail-dialog" }
+      "purpose": "Production modal containing a Toolbar heading, navigable record master list, and ValueTable detail.",
+      "uses": [
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
+        "list-header",
+        "list-item",
+        "value-table",
+        "wa-dialog",
+        "wa-button"
+      ],
+      "useWhen": [
+        "A focused task compares several records without leaving the current workspace."
+      ],
+      "avoidWhen": [
+        "Use a page when the task needs a durable route or substantially more working space."
+      ],
+      "appOwns": [
+        "open state",
+        "selected record",
+        "dismiss policy",
+        "record actions"
+      ],
+      "accessibility": [
+        "Web Awesome owns modal focus and Escape; the application adapter restores the invoking control after hide, and Toolbar plus ToolbarText supply the visible hierarchy."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css",
+          "individual-custom-element-registration"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-list-detail-dialog",
+        "documentation": "docs/recipes.md#list-detail-dialog",
+        "recipe": "docs/recipes.md#list-detail-dialog"
+      }
     },
     {
       "id": "recipe-composer-form",
@@ -4430,14 +6499,44 @@
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
-      "purpose": "One visible publishing-form surface with DialogHeader hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.",
-      "uses": ["dialog-header", "select", "state-banner", "wa-input", "wa-textarea", "wa-button", "layout"],
-      "useWhen": ["A short form needs one coherent surface, consistent field/action rhythm, and persistent validation feedback."],
-      "avoidWhen": ["Do not turn each form section into another visible card or use the recipe as a generic form engine or transport abstraction."],
-      "appOwns": ["validation rules", "draft persistence", "permissions", "transport"],
-      "accessibility": ["The form references DialogHeader's title and summary ids; production fields own labels and help; invalid submission creates an assertive persistent StateBanner while successful submission creates a polite persistent banner."],
-      "delivery": { "sideEffects": ["lazy-recipe-css", "individual-custom-element-registration"] },
-      "links": { "catalogRoute": "?component=recipe-composer-form", "documentation": "docs/recipes.md#composer-form", "recipe": "docs/recipes.md#composer-form" }
+      "purpose": "One visible publishing-form surface with Toolbar heading hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.",
+      "uses": [
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
+        "select",
+        "state-banner",
+        "wa-input",
+        "wa-textarea",
+        "wa-button",
+        "layout"
+      ],
+      "useWhen": [
+        "A short form needs one coherent surface, consistent field/action rhythm, and persistent validation feedback."
+      ],
+      "avoidWhen": [
+        "Do not turn each form section into another visible card or use the recipe as a generic form engine or transport abstraction."
+      ],
+      "appOwns": [
+        "validation rules",
+        "draft persistence",
+        "permissions",
+        "transport"
+      ],
+      "accessibility": [
+        "The form references its ToolbarText title and supporting-summary ids; production fields own labels and help; invalid submission creates an assertive persistent StateBanner while successful submission creates a polite persistent banner."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css",
+          "individual-custom-element-registration"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-composer-form",
+        "documentation": "docs/recipes.md#composer-form",
+        "recipe": "docs/recipes.md#composer-form"
+      }
     },
     {
       "id": "recipe-list-workspace-states",
@@ -4446,13 +6545,40 @@
       "kind": "recipe",
       "source": "kerf",
       "purpose": "Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.",
-      "uses": ["page-header", "state-banner", "empty-state", "loading-spinner", "layout"],
-      "useWhen": ["A list surface must communicate initial load, absence, background refresh, failure, and recovery."],
-      "avoidWhen": ["Do not replace domain rows with a generic component or use transient toasts as the only error record."],
-      "appOwns": ["fetching", "cache age", "retry policy", "domain rows"],
-      "accessibility": ["Busy, polite, and assertive states use the appropriate production feedback semantics."],
-      "delivery": { "sideEffects": ["lazy-recipe-css"] },
-      "links": { "catalogRoute": "?component=recipe-list-workspace-states", "documentation": "docs/recipes.md#list-workspace-states", "recipe": "docs/recipes.md#list-workspace-states" }
+      "uses": [
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
+        "state-banner",
+        "empty-state",
+        "loading-spinner",
+        "layout"
+      ],
+      "useWhen": [
+        "A list surface must communicate initial load, absence, background refresh, failure, and recovery."
+      ],
+      "avoidWhen": [
+        "Do not replace domain rows with a generic component or use transient toasts as the only error record."
+      ],
+      "appOwns": [
+        "fetching",
+        "cache age",
+        "retry policy",
+        "domain rows"
+      ],
+      "accessibility": [
+        "Busy, polite, and assertive states use the appropriate production feedback semantics."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-list-workspace-states",
+        "documentation": "docs/recipes.md#list-workspace-states",
+        "recipe": "docs/recipes.md#list-workspace-states"
+      }
     },
     {
       "id": "recipe-compact-toolbar",
@@ -4461,13 +6587,164 @@
       "kind": "recipe",
       "source": "kerf",
       "purpose": "A compact toolbar that distinguishes grouped commands, a visible exclusive choice, a longer Select, and one ordinary action.",
-      "uses": ["toolbar", "toolbar-text", "toolbar-control-group", "segmented-control", "select", "lucide-icon"],
-      "useWhen": ["A dense workspace toolbar mixes a few distinct control semantics."],
-      "avoidWhen": ["Do not group unrelated actions or use buttons to imitate selection controls."],
-      "appOwns": ["controlled values", "actions", "persistence", "responsive priority"],
-      "accessibility": ["Each control retains its own native name, pressed/value state, and keyboard contract."],
-      "delivery": { "sideEffects": ["lazy-recipe-css", "individual-custom-element-registration"] },
-      "links": { "catalogRoute": "?component=recipe-compact-toolbar", "documentation": "docs/recipes.md#compact-toolbar-choices-and-actions", "recipe": "docs/recipes.md#compact-toolbar-choices-and-actions" }
+      "uses": [
+        "toolbar",
+        "toolbar-text",
+        "toolbar-control-group",
+        "segmented-control",
+        "select",
+        "lucide-icon"
+      ],
+      "useWhen": [
+        "A dense workspace toolbar mixes a few distinct control semantics."
+      ],
+      "avoidWhen": [
+        "Do not group unrelated actions or use buttons to imitate selection controls."
+      ],
+      "appOwns": [
+        "controlled values",
+        "actions",
+        "persistence",
+        "responsive priority"
+      ],
+      "accessibility": [
+        "Each control retains its own native name, pressed/value state, and keyboard contract."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css",
+          "individual-custom-element-registration"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-compact-toolbar",
+        "documentation": "docs/recipes.md#compact-toolbar-choices-and-actions",
+        "recipe": "docs/recipes.md#compact-toolbar-choices-and-actions"
+      }
+    },
+    {
+      "id": "recipe-navigation-stack",
+      "name": "Navigation stack",
+      "category": "Recipes",
+      "kind": "recipe",
+      "source": "kerf",
+      "purpose": "A push/pop navigation stack drill-down with animated slides and a live device class.",
+      "uses": [
+        "list-header",
+        "list-item",
+        "lucide-icon",
+        "layout"
+      ],
+      "useWhen": [
+        "A flow drills from a list into detail and back on one pane, at any device size or inside a dialog."
+      ],
+      "avoidWhen": [
+        "Use SplitView when a list and its detail should show together on roomy classes."
+      ],
+      "appOwns": [
+        "the stack (a signal of views)",
+        "selection",
+        "routing",
+        "data"
+      ],
+      "accessibility": [
+        "The back control is a real button; reduced motion collapses the slide to instant."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-navigation-stack",
+        "documentation": "docs/recipes.md#navigation-stack",
+        "recipe": "docs/recipes.md#navigation-stack"
+      }
+    },
+    {
+      "id": "recipe-loading-inspector",
+      "name": "Loading inspector",
+      "category": "Recipes",
+      "kind": "recipe",
+      "source": "kerf",
+      "purpose": "A record inspector whose per-record values load asynchronously — every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.",
+      "uses": [
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
+        "value-table",
+        "select",
+        "segmented-control",
+        "list-item",
+        "state-banner",
+        "skeleton",
+        "lucide-icon"
+      ],
+      "useWhen": [
+        "A detail or inspector view must render its real chrome while its per-record values are still loading, then swap to the populated record without duplicating markup."
+      ],
+      "avoidWhen": [
+        "Do not hand-build a separate empty-state layout, and do not use it for known progress — use LoadingSpinner for that."
+      ],
+      "appOwns": [
+        "loading lifecycle",
+        "which values are unknown",
+        "fetching, transport, and domain data"
+      ],
+      "accessibility": [
+        "Each component marks itself aria-busy and disables its own controls while loading; the composition keeps labels and structure stable across the transition."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css",
+          "individual-custom-element-registration"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-loading-inspector",
+        "documentation": "docs/recipes.md#loading-inspector",
+        "recipe": "docs/recipes.md#loading-inspector"
+      }
+    },
+    {
+      "id": "recipe-collapsible-sidebar",
+      "name": "Collapsible sidebar",
+      "category": "Recipes",
+      "kind": "recipe",
+      "source": "kerf",
+      "purpose": "A mini app frame whose left navigation rail and bottom activity drawer are standalone CollapsiblePanels driven by wireSidebar: per-side collapse/expand toggles, focus move-in and restore, a dismissable compact overlay, and per-panel persistence.",
+      "uses": [
+        "list-header",
+        "list-item",
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text"
+      ],
+      "useWhen": [
+        "A rail or drawer must collapse and expand outside a full Workbench shell, keeping the app's collapsed signals, sizes, and content while the wire owns toggle, focus, the compact overlay, and persistence."
+      ],
+      "avoidWhen": [
+        "Use the Workbench layout when the whole screen is a three-pane shell; use an ordinary always-visible sidebar when it never collapses."
+      ],
+      "appOwns": [
+        "each panel's collapsed signal",
+        "panel sizes",
+        "routing and selection",
+        "content"
+      ],
+      "accessibility": [
+        "Each panel is a labeled aside that is aria-hidden while collapsed; toggles carry aria-expanded and the standard per-side glyph; while compact an open panel is an overlay with a backdrop, Escape and backdrop-click dismiss, and a trapped Tab ring."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-collapsible-sidebar",
+        "documentation": "docs/recipes.md#collapsible-sidebar",
+        "recipe": "docs/recipes.md#collapsible-sidebar"
+      }
     }
   ]
 }