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

package/ai/component-catalog.json

@@ -328,11 +328,7 @@
       ],
       "alternatives": [
         {
-          "id": "page-header",
-          "relationship": "nearest"
-        },
-        {
-          "id": "dialog-header",
+          "id": "panel-header",
           "relationship": "nearest"
         }
       ],
@@ -478,7 +474,7 @@
       ],
       "alternatives": [
         {
-          "id": "page-header",
+          "id": "panel-header",
           "relationship": "nearest"
         }
       ],
@@ -489,7 +485,8 @@
       "variants": [
         "large",
         "default",
-        "small"
+        "small",
+        "placeholder (loading)"
       ],
       "accessibility": [],
       "delivery": {
@@ -524,8 +521,7 @@
       "source": "kerf",
       "description": "Page, dialog, and definition-list hierarchy.",
       "uses": [
-        "page-header",
-        "dialog-header",
+        "panel-header",
         "value-table"
       ],
       "purpose": "Page, dialog, and definition-list hierarchy.",
@@ -542,11 +538,7 @@
           "relationship": "nearest"
         },
         {
-          "id": "page-header",
-          "relationship": "nearest"
-        },
-        {
-          "id": "dialog-header",
+          "id": "panel-header",
           "relationship": "nearest"
         }
       ],
@@ -578,96 +570,31 @@
       }
     },
     {
-      "id": "page-header",
-      "name": "PageHeader",
-      "category": "Structure",
-      "kind": "component",
-      "source": "kerf",
-      "description": "Page identity with an optional trailing action.",
-      "uses": [],
-      "purpose": "Page identity with an optional trailing action.",
-      "publicExports": [
-        "PageHeader"
-      ],
-      "useWhen": [
-        "Identify a page with its primary heading and optional trailing action."
-      ],
-      "avoidWhen": [
-        "Do not use for persistent app chrome or a modal task."
-      ],
-      "alternatives": [
-        {
-          "id": "toolbar",
-          "relationship": "nearest"
-        },
-        {
-          "id": "dialog-header",
-          "relationship": "nearest"
-        }
-      ],
-      "appOwns": [
-        "title",
-        "action",
-        "responsive placement"
-      ],
-      "variants": [
-        "title",
-        "title with action"
-      ],
-      "accessibility": [
-        "Use once for the page primary heading."
-      ],
-      "delivery": {
-        "browserImport": "@kerfjs/ui/page-header",
-        "manualCssImport": "@kerfjs/ui/page-header.css",
-        "sideEffects": [
-          "browser-condition-css"
-        ]
-      },
-      "wiring": [],
-      "publicClasses": [
-        "kui-page-header",
-        "kui-page-header__action"
-      ],
-      "publicTokens": [
-        "--kui-color-text",
-        "--kui-font-2xl",
-        "--kui-font-l",
-        "--kui-page-header-background",
-        "--kui-page-header-border",
-        "--kui-page-header-foreground"
-      ],
-      "links": {
-        "catalogRoute": "?component=page-header",
-        "documentation": "docs/component-selection.md",
-        "recipe": "docs/component-selection.md#ambiguous-choices"
-      }
-    },
-    {
-      "id": "dialog-header",
-      "name": "DialogHeader",
+      "id": "panel-header",
+      "name": "PanelHeader",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Dialog toolbar with aligned icon, title, grouped actions, and a subtitle row.",
+      "description": "A plain Toolbar as a panel, dialog, or page heading: optional icon group, an extra-large title, trailing actions, and an optional subtitle row.",
       "uses": [
         "lucide-icon",
         "toolbar",
-        "toolbar-control-group"
+        "toolbar-control-group",
+        "toolbar-text"
       ],
-      "purpose": "Dialog toolbar with aligned icon, title, grouped actions, and a subtitle row.",
+      "purpose": "A plain Toolbar as a panel, dialog, or page heading: optional icon group, an extra-large title, trailing actions, and an optional subtitle row.",
       "publicExports": [
-        "DialogHeader"
+        "PanelHeader"
       ],
       "useWhen": [
-        "Label a focused dialog task with a toolbar-aligned title, icon, actions, and subtitle."
+        "Give a panel, dialog, or page a heading with an extra-large title, optional icon and subtitle, and trailing actions."
       ],
       "avoidWhen": [
-        "Do not use as the page heading or as a replacement for modal behavior."
+        "Do not use it as persistent application chrome; use Toolbar. It supplies header structure, not modal behavior."
       ],
       "alternatives": [
         {
-          "id": "page-header",
+          "id": "toolbar",
           "relationship": "nearest"
         },
         {
@@ -680,49 +607,42 @@
         "focus lifecycle",
         "dismissal",
         "copy",
-        "localized action-group label"
+        "the trailing action controls"
       ],
       "variants": [
         "title",
         "optional summary",
         "icon",
         "actions",
-        "actionsLabel"
+        "placeholder (loading)"
       ],
       "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."
+        "Connect the title id and any provided summary id to the dialog or panel host.",
+        "Pass the trailing actions as a labeled ToolbarControlGroup when the group needs an accessible name."
       ],
       "delivery": {
-        "browserImport": "@kerfjs/ui/dialog-header",
-        "manualCssImport": "@kerfjs/ui/dialog-header.css",
+        "browserImport": "@kerfjs/ui/panel-header",
+        "manualCssImport": "@kerfjs/ui/panel-header.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-panel-header",
+        "kui-panel-header__icon",
+        "kui-panel-header__summary"
       ],
       "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-panel-header-icon-background",
+        "--kui-panel-header-icon-border",
+        "--kui-panel-header-icon-foreground"
       ],
       "links": {
-        "catalogRoute": "?component=dialog-header",
+        "catalogRoute": "?component=panel-header",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#ambiguous-choices"
       }
@@ -756,7 +676,8 @@
       ],
       "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."
@@ -881,11 +802,7 @@
       ],
       "alternatives": [
         {
-          "id": "page-header",
-          "relationship": "nearest"
-        },
-        {
-          "id": "dialog-header",
+          "id": "panel-header",
           "relationship": "nearest"
         }
       ],
@@ -903,7 +820,8 @@
         "count",
         "badge",
         "action",
-        "toggle"
+        "toggle",
+        "placeholder (loading)"
       ],
       "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.",
@@ -992,7 +910,8 @@
         "pressed",
         "disabled primary",
         "disabled trailing action",
-        "multiline"
+        "multiline",
+        "placeholder (loading)"
       ],
       "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.",
@@ -1082,7 +1001,8 @@
         "pressed",
         "disabled",
         "trailing",
-        "multiline"
+        "multiline",
+        "placeholder (loading)"
       ],
       "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."
@@ -1347,7 +1267,8 @@
         "rounded",
         "pill",
         "equal width",
-        "small"
+        "small",
+        "placeholder (loading)"
       ],
       "accessibility": [
         "Keep choice labels meaningful and every enabled native button in sequential Tab order."
@@ -1433,7 +1354,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",
@@ -1445,7 +1366,7 @@
         "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."
+        "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."
       ],
       "delivery": {
         "browserImport": "@kerfjs/ui/token-search-field",
@@ -1652,7 +1573,8 @@
         "disabled",
         "fit menu",
         "grouped",
-        "custom selected content"
+        "custom selected content",
+        "placeholder (loading)"
       ],
       "accessibility": [
         "Verify the live value, standard events, focus, and rendered output."
@@ -1803,7 +1725,8 @@
         "warning",
         "danger",
         "status",
-        "alert"
+        "alert",
+        "placeholder (loading)"
       ],
       "accessibility": [
         "Use alert urgency only for an attention-requiring failure."
@@ -2005,6 +1928,66 @@
         "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"
+      ],
+      "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."
+      ],
+      "avoidWhen": [
+        "Do not use for known progress or a busy spinner; use LoadingSpinner.",
+        "Do not animate it or use it as decorative filler."
+      ],
+      "alternatives": [
+        {
+          "id": "wa-skeleton",
+          "relationship": "prefer-over"
+        }
+      ],
+      "appOwns": [
+        "loading lifecycle",
+        "which slots are unknown",
+        "announcing the loading region"
+      ],
+      "variants": [
+        "block",
+        "lines",
+        "labeled"
+      ],
+      "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."
+      ],
+      "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",
@@ -4371,13 +4354,42 @@
       "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",
+        "menu-header",
+        "menu-item",
+        "panel-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"
+      }
     },
     {
       "id": "recipe-navigation-sidebar",
@@ -4386,13 +4398,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": [
+        "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"
+      }
     },
     {
       "id": "recipe-workspace-header",
@@ -4401,13 +4437,36 @@
       "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": [
+        "panel-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 PanelHeader 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"
+      }
     },
     {
       "id": "recipe-master-detail-dialog",
@@ -4415,14 +4474,41 @@
       "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 PanelHeader, navigable record master list, and ValueTable detail.",
+      "uses": [
+        "panel-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 PanelHeader 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"
+      }
     },
     {
       "id": "recipe-composer-form",
@@ -4430,14 +4516,42 @@
       "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 PanelHeader hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.",
+      "uses": [
+        "panel-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 PanelHeader'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"
+      }
     },
     {
       "id": "recipe-list-workspace-states",
@@ -4446,13 +4560,38 @@
       "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": [
+        "panel-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"
+      }
     },
     {
       "id": "recipe-compact-toolbar",
@@ -4461,13 +4600,79 @@
       "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": [
+        "menu-header",
+        "menu-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"
+      }
     }
   ]
 }