@kerfjs/ui 5.0.0-beta.97 → 5.0.0-beta.99

package/ai/components/nav-stack.md

@@ -26,7 +26,7 @@ Present a single linear or drill-down flow while preserving each prior view's st
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/nav-stack` — exports `NavStackView`, `NavStackToolbarConfig`, `NavStackProps`, `NavStack`.
+- JavaScript: `@kerfjs/ui/nav-stack` — exports `NavStackView`, `NavStackToolbarConfig`, `NavStackProps`, `NavStackChromePresentation`, `NavStackBottomToolbarPresentation`, `NavStack`.
 - CSS: the browser build of `@kerfjs/ui/nav-stack` pulls its CSS automatically; import `@kerfjs/ui/nav-stack.css` manually only without the `browser` export condition.
 - Wiring: `wireNavStack` from `@kerfjs/ui/wire-nav-stack` (required).
 - Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
@@ -48,6 +48,8 @@ Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1
 - persistent bottom-toolbar fallback
 - chrome and bottom-toolbar dividers only while the active view scrolls beneath them (wired by wireScrollDividers)
 - permanent or no chrome dividers (chromeDividers always or none)
+- translucent top chrome laid over the active view (chromePresentation overlay, measured by wireNavStack)
+- translucent bottom toolbar laid over the active view (bottomToolbarPresentation overlay, measured by wireNavStack)
 
 ## Composition
 
@@ -58,7 +60,7 @@ Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1
 
 ## State and wiring
 
-**The app owns:** ordered view stack and stable keys; view content and structured top and bottom toolbar configurations; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar or a persistent structured fallback; per-view leading, center, and trailing top-toolbar groups; per-view header and footer with List and Pane configuration; top-toolbar defaults, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers).
+**The app owns:** ordered view stack and stable keys; view content and structured top and bottom toolbar configurations; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar or a persistent structured fallback; per-view leading, center, and trailing top-toolbar groups; per-view header and footer with List and Pane configuration; top-toolbar defaults, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers); whether the top chrome docks above the active view or lies over it on the translucent chrome material (chromePresentation); whether the bottom toolbar docks below the active view or lies over it on the translucent chrome material (bottomToolbarPresentation).
 
 **Wiring:** `wireNavStack`, `wireScrollDividers` is required.
 
@@ -70,8 +72,11 @@ Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1
 - `data-nav-chrome-copy` on `kui-nav-stack__chrome-copy` (`wireNavStack`): Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade.
 - `data-nav-revealed` on `kui-nav-stack__view` (`wireNavStack`): "true" on the preserved, aria-hidden previous view while an incoming view slides over it.
 - `data-nav-exiting` on `kui-nav-stack__view` (`wireNavStack`): "true" on a popped view the helper briefly re-inserts to slide it out.
+- `data-chrome-overlay` on `kui-nav-stack` (`wireNavStack`): measured once the helper has measured an overlay chrome (chromePresentation: overlay) and published its border-box height on the stack root; the chrome then lies over the active view, which clears it through the block-start edge context. Both are re-applied if a re-render drops them.
+- `data-bottom-toolbar-overlay` on `kui-nav-stack` (`wireNavStack`): measured once the helper has measured an overlay bottom toolbar (bottomToolbarPresentation: overlay) and published its border-box height on the stack root; the toolbar then lies over the active view, which clears it through the block-end edge context. Both are re-applied if a re-render drops them.
 - `data-scroll-overflow` on `the active kui-nav-stack__view, or the kui-pane__content of a sole Pane in it` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
 - `data-scroll-divider` on `kui-nav-stack__chrome and kui-nav-stack__bottom` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it.
 
 ## Geometry
 
@@ -79,6 +84,8 @@ Margin: none · border: conditional · padding: child (layout role: structure).
 
 - The stack owns its full-height chrome and viewport; each view owns its internal content padding and scrollable content.
 - The top chrome's bottom line and the bottom toolbar's top line are scroll state (wireScrollDividers), drawn as an overlaid 1px pseudo-element on the chrome and the bottom toolbar's always-present 1px top border, so neither moves the chrome or the content.
+- chromePresentation overlay: once wireNavStack measures the live chrome (never a cross-fading copy), the chrome lies over the viewport's top edge and its border-box height, top safe area included, becomes the viewport's block-start --kui-edge-inset-\* context, so a plain view, a sole Pane, or a nested layout pads and scroll-pads by it automatically; the chrome ends where a classic scrollbar in the active view begins, so its track stays uncovered; unwired, or with hideToolbar, the chrome stays docked.
+- bottomToolbarPresentation overlay: once wireNavStack measures the live bottom toolbar (never a cross-fading copy), the toolbar lies over the viewport's bottom edge and its border-box height, bottom safe area and divider border included, becomes the viewport's block-end --kui-edge-inset-\* context, so a plain view, a sole Pane (its content, or its footer), or a nested layout pads and scroll-pads by it automatically and the last item rests just above the toolbar; it ends where a classic scrollbar in the active view begins; unwired, or while no bottom toolbar is shown, it stays docked. It is independent of chromePresentation, which governs only the top chrome.
 
 ## Accessibility
 
@@ -86,6 +93,8 @@ Margin: none · border: conditional · padding: child (layout role: structure).
 - Set toolbarConfig.headingLevel when the view title is the page's or section's heading landmark.
 - 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.
+- Overlay chrome (chromePresentation overlay) keeps WCAG AA over content passing beneath the translucent material: an untoned ToolbarText there takes the normal text color for its title and lifts its description halfway toward it; keep other quiet copy in the view. The material turns opaque under reduced transparency, increased contrast, forced colors, or without backdrop-filter.
+- An overlay bottom toolbar (bottomToolbarPresentation overlay) keeps the same AA rule: an untoned ToolbarText there lifts its title and description, and a default-tone ToolbarControlGroup in either overlaid bar takes the normal text color for its controls. Its 1px top edge stays visible in forced colors.
 
 ## Styling boundary
 

package/ai/components/pane.md

@@ -16,15 +16,18 @@ Organize a sidebar, main area, inspector, or dialog column into fixed vertical h
 - A lowered background must cover the scrolling work viewport and blank space after short content without a second scroll container (appearance: sunken).
 - A child table or other component needs edge-to-edge decoration with text aligned to other pane content.
 - An opaque edge-to-edge child needs a reserved vertical scrollbar gutter.
+- Scrolling content must pass beneath chrome laid over the pane edge (a DialogSurface floating footer) while its first and last items still rest clear of it (scrollClearance).
+- The header should float over the scrolling content on a translucent material so content scrolls visibly beneath it, with the first item still resting below the header (headerPresentation: overlay, measured by wireScrollDividers).
 
 **Not when:**
 
 - 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.
+- A ToolbarText description in an overlay header is fine: an untoned ToolbarText there takes the normal text color for its title and lifts its description halfway toward it, keeping AA over the content passing beneath. Do not put other quiet secondary text in an overlay header; keep it in the content.
 
 **Alternatives:**
 
-- [Application layout](./layout.md) (composes-with) — Use the layout content-item and control classes inside Pane when children need shared geometry.
+- [Application Layout](./layout.md) (composes-with) — Use the layout content-item and control classes inside Pane when children need shared geometry.
 
 ## Imports
 
@@ -48,6 +51,8 @@ Exact prop names and types: [`@kerfjs/ui/pane`](../public-api-signatures-v1.md#k
 - inline-end separator
 - chrome dividers only while scrolled (default, wired by wireScrollDividers)
 - always or no chrome dividers
+- scrollClearance block-start, block-end, or both on the scrolling content
+- overlay header on the translucent chrome material (headerPresentation: overlay)
 
 ## Composition
 
@@ -63,7 +68,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 ## State and wiring
 
-**The app owns:** root and content semantics; accessible labels; header, content, and footer children; which logical boundaries show separators; which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges); responsive placement and visibility; whether the chrome dividers follow the scroll, always show, or never show (chromeDividers); default or sunken scrolling work surface (appearance); whether to reserve a vertical scrollbar gutter for opaque edge-to-edge content (--kui-pane-scrollbar-gutter); optional keyboard or programmatic focus (tabIndex) and persistent focus outline (outlined).
+**The app owns:** root and content semantics; accessible labels; header, content, and footer children; which logical boundaries show separators; which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges); responsive placement and visibility; whether the chrome dividers follow the scroll, always show, or never show (chromeDividers); default or sunken scrolling work surface (appearance); whether to reserve a vertical scrollbar gutter for opaque edge-to-edge content (--kui-pane-scrollbar-gutter); optional keyboard or programmatic focus (tabIndex) and persistent focus outline (outlined); whether the scrolling content clears overlaying chrome on its block edges (scrollClearance, also in PaneConfig, so a Workbench mainPane or panel pane, a CollapsiblePanel pane, or a NavStack view pane forwards it); whether the header is docked in its own row or laid over the scrolling content on the translucent chrome material (headerPresentation, also in PaneConfig).
 
 **Wiring:** `wireScrollDividers` is optional.
 
@@ -71,6 +76,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 - `data-scroll-overflow` on `kui-pane__content` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
 - `data-scroll-divider` on `kui-pane__header and kui-pane__footer` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured an overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root (and a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered); the header then lies over the content, which clears it. Both are re-applied if a re-render drops them.
 
 ## Geometry
 
@@ -81,11 +87,14 @@ Margin: child · border: conditional · padding: child (layout role: structure).
 - The scrolling content exposes its resolved logical inline padding to descendants as --kui-pane-content-inset-inline-start/end, including safe areas and deepInset.
 - deepInset adds --kui-space-xs to every side of the scrolling content and its block scroll padding; header/footer chrome still owns safe-area padding at its edge.
 - For opaque edge-to-edge children, --kui-pane-scrollbar-gutter: stable reserves a vertical scrollbar gutter outside the published content insets; the default is auto.
+- scrollClearance adds the inherited --kui-scroll-clearance-block-start/end context, published by overlaying chrome, to the scrolling content block padding and scroll padding alongside safe areas and deepInset.
+- headerPresentation overlay: once wireScrollDividers measures the header, the header shares the content cell above the scroller, its border-box height is published as --kui-scroll-clearance-block-start on the Pane root, and the content clears it automatically; unwired or with chromePlacement auto, the header stays docked.
 
 ## Accessibility
 
 - 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.
+- An overlay header's text uses the normal text color, which keeps WCAG AA over the 80% chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
 
 ## Styling boundary
 
@@ -95,12 +104,12 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-pane`, `kui-pane__content`, `kui-pane__footer`, `kui-pane__header`, `kui-pane__toolbar` on an element you write; render `Pane` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-edge-inset-block-end`, `--kui-edge-inset-block-start`, `--kui-edge-inset-inline-end`, `--kui-edge-inset-inline-start`, `--kui-pane-separator-color`, `--kui-pane-separator-width`, `--kui-pane-chrome-background`, `--kui-pane-content-inset-inline-start`, `--kui-pane-content-inset-inline-end`, `--kui-pane-scrollbar-gutter`, `--kui-sunken-panel-background`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-edge-inset-block-end`, `--kui-edge-inset-block-start`, `--kui-edge-inset-inline-end`, `--kui-edge-inset-inline-start`, `--kui-pane-separator-color`, `--kui-pane-separator-width`, `--kui-pane-chrome-background`, `--kui-pane-content-inset-inline-start`, `--kui-pane-content-inset-inline-end`, `--kui-pane-scrollbar-gutter`, `--kui-sunken-panel-background`, `--kui-chrome-material`, `--kui-chrome-material-filter`, `--kui-scroll-clearance-block-start`. Set a token only where its public contract allows; prefer a prop.
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 
 ## Related
 
-- Components: [Application layout](./layout.md).
+- Components: [Application Layout](./layout.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/layout.md#anatomy`](../../docs/layout.md#anatomy).
 - UX catalog route: `?component=pane`.

package/ai/components/popup-menu.md

@@ -67,7 +67,7 @@ Margin: none · border: child · padding: child (layout role: controls). `self`
 
 ## Accessibility
 
-- An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. Web Awesome provides menu roles, nested arrow-key navigation, typeahead, and Escape.
+- An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. The open menu takes the trigger's name (the context or icon-only label, or the visible text), and each submenu takes its parent item's label, so a screen reader announces a named menu and getByRole('menu', { name }) finds it. Web Awesome provides menu roles, nested arrow-key navigation, typeahead, and Escape.
 - Once registered, an icon-only trigger shows its label as an aria-hidden Web Awesome help tag after a 500ms hover and at once on keyboard focus; it hides while the menu is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip.
 
 ## Usage examples
@@ -113,7 +113,7 @@ Headings separate sort dimensions; trailing safe content marks the active comman
 <PopupMenu
   label="Sort chat"
   items={[
-    { kind: 'heading', label: 'Sort by' },
+    { kind: 'heading', label: 'Sort By' },
     {
       label: 'Updated',
       action: 'sort-updated',
@@ -126,7 +126,7 @@ Headings separate sort dimensions; trailing safe content marks the active comman
     },
     { kind: 'heading', label: 'Order' },
     {
-      label: 'Newest first',
+      label: 'Newest First',
       action: 'order-newest',
       details: order === 'newest' ? tick : undefined,
     },
@@ -141,7 +141,7 @@ Keep the row's visible disabled action separate from the context menu anchor. Fi
 ```tsx
 <PopupMenu
   context
-  label="Demand actions"
+  label="Demand Actions"
   rootAttributes={{ 'data-demand-menu': '' }}
   items={[{ label: 'Open', action: 'open-demand' }]}
 />;

package/ai/components/recipe-app-shell.md

@@ -1,4 +1,4 @@
-# Desktop application shell
+# Desktop Application Shell
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 
@@ -28,7 +28,7 @@ No props: this entry has no JavaScript API.
 - Parents: used at the root of a screen or reference, not nested.
 - Contexts: `application-reference`.
 - Children: unrestricted.
-- Built from: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Workbench](./workbench.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md).
+- Built from: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Workbench](./workbench.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md).
 
 ## State and wiring
 
@@ -52,6 +52,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Workbench](./workbench.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md).
+- Components: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Workbench](./workbench.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md).
 - Docs: [`docs/recipes.md#desktop-application-shell`](../../docs/recipes.md#desktop-application-shell).
 - UX catalog route: `?component=recipe-app-shell`.

package/ai/components/recipe-collapsible-sidebar.md

@@ -1,4 +1,4 @@
-# Collapsible sidebar
+# Collapsible Sidebar
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 
@@ -28,7 +28,7 @@ No props: this entry has no JavaScript API.
 - Parents: used at the root of a screen or reference, not nested.
 - Contexts: `application-reference`.
 - Children: unrestricted.
-- Built from: [CollapsiblePanel](./collapsible-panel.md), [Pane](./pane.md), [Row](./row.md), [List](./list.md), [Grid](./grid.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+- Built from: [CollapsiblePanel](./collapsible-panel.md), [Pane](./pane.md), [Row](./row.md), [List](./list.md), [Grid](./grid.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
 
 ## State and wiring
 
@@ -52,6 +52,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [CollapsiblePanel](./collapsible-panel.md), [Pane](./pane.md), [Row](./row.md), [List](./list.md), [Grid](./grid.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+- Components: [CollapsiblePanel](./collapsible-panel.md), [Pane](./pane.md), [Row](./row.md), [List](./list.md), [Grid](./grid.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
 - Docs: [`docs/recipes.md#collapsible-sidebar`](../../docs/recipes.md#collapsible-sidebar).
 - UX catalog route: `?component=recipe-collapsible-sidebar`.

package/ai/components/recipe-compact-toolbar.md

@@ -1,4 +1,4 @@
-# Compact toolbar choices and actions
+# Compact Toolbar Choices and Actions
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 

package/ai/components/recipe-composer-form.md

@@ -1,4 +1,4 @@
-# Composer form
+# Composer Form
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 
@@ -28,7 +28,7 @@ No props: this entry has no JavaScript API.
 - Parents: used at the root of a screen or reference, not nested.
 - Contexts: `application-reference`.
 - Children: unrestricted.
-- Built from: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [Row](./row.md), [Select](./select.md), [StateBanner](./state-banner.md), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Button](./wa-button.md), [Application layout](./layout.md).
+- Built from: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [Row](./row.md), [Select](./select.md), [StateBanner](./state-banner.md), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Button](./wa-button.md), [Application Layout](./layout.md).
 
 ## State and wiring
 
@@ -52,6 +52,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [Row](./row.md), [Select](./select.md), [StateBanner](./state-banner.md), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Button](./wa-button.md), [Application layout](./layout.md).
+- Components: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [Row](./row.md), [Select](./select.md), [StateBanner](./state-banner.md), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Button](./wa-button.md), [Application Layout](./layout.md).
 - Docs: [`docs/recipes.md#composer-form`](../../docs/recipes.md#composer-form).
 - UX catalog route: `?component=recipe-composer-form`.

package/ai/components/recipe-list-detail-dialog.md

@@ -28,7 +28,7 @@ No props: this entry has no JavaScript API.
 - Parents: used at the root of a screen or reference, not nested.
 - Contexts: `application-reference`.
 - Children: unrestricted.
-- Built from: [Surface scaffolds](./surface-scaffold.md), [SplitView](./split-view.md), [NavStack](./nav-stack.md), [Row](./row.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Dialog](./wa-dialog.md), [Button](./wa-button.md).
+- Built from: [Surface Scaffolds](./surface-scaffold.md), [SplitView](./split-view.md), [NavStack](./nav-stack.md), [Row](./row.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Dialog](./wa-dialog.md), [Button](./wa-button.md).
 
 ## State and wiring
 
@@ -52,6 +52,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Surface scaffolds](./surface-scaffold.md), [SplitView](./split-view.md), [NavStack](./nav-stack.md), [Row](./row.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Dialog](./wa-dialog.md), [Button](./wa-button.md).
+- Components: [Surface Scaffolds](./surface-scaffold.md), [SplitView](./split-view.md), [NavStack](./nav-stack.md), [Row](./row.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Dialog](./wa-dialog.md), [Button](./wa-button.md).
 - Docs: [`docs/recipes.md#list-detail-dialog`](../../docs/recipes.md#list-detail-dialog).
 - UX catalog route: `?component=recipe-list-detail-dialog`.

package/ai/components/recipe-list-workspace-states.md

@@ -1,4 +1,4 @@
-# List workspace states
+# List Workspace States
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 
@@ -28,7 +28,7 @@ No props: this entry has no JavaScript API.
 - Parents: used at the root of a screen or reference, not nested.
 - Contexts: `application-reference`.
 - Children: unrestricted.
-- Built from: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListItem](./list-item.md), [Row](./row.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md), [Application layout](./layout.md).
+- Built from: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListItem](./list-item.md), [Row](./row.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md), [Application Layout](./layout.md).
 
 ## State and wiring
 
@@ -52,6 +52,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListItem](./list-item.md), [Row](./row.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md), [Application layout](./layout.md).
+- Components: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListItem](./list-item.md), [Row](./row.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md), [Application Layout](./layout.md).
 - Docs: [`docs/recipes.md#list-workspace-states`](../../docs/recipes.md#list-workspace-states).
 - UX catalog route: `?component=recipe-list-workspace-states`.

package/ai/components/recipe-loading-inspector.md

@@ -1,4 +1,4 @@
-# Loading inspector
+# Loading Inspector
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 

package/ai/components/recipe-navigation-sidebar.md

@@ -1,4 +1,4 @@
-# Navigation sidebar
+# Navigation Sidebar
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 
@@ -28,7 +28,7 @@ No props: this entry has no JavaScript API.
 - Parents: used at the root of a screen or reference, not nested.
 - Contexts: `application-reference`.
 - Children: unrestricted.
-- Built from: [Pane](./pane.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [List](./list.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+- Built from: [Pane](./pane.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [List](./list.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
 
 ## State and wiring
 
@@ -52,6 +52,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Pane](./pane.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [List](./list.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+- Components: [Pane](./pane.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [List](./list.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
 - Docs: [`docs/recipes.md#navigation-sidebar`](../../docs/recipes.md#navigation-sidebar).
 - UX catalog route: `?component=recipe-navigation-sidebar`.

package/ai/components/recipe-navigation-stack.md

@@ -1,4 +1,4 @@
-# Navigation stack
+# Navigation Stack
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 
@@ -28,7 +28,7 @@ No props: this entry has no JavaScript API.
 - Parents: used at the root of a screen or reference, not nested.
 - Contexts: `application-reference`.
 - Children: unrestricted.
-- Built from: [NavStack](./nav-stack.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Row](./row.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+- Built from: [NavStack](./nav-stack.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Row](./row.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
 
 ## State and wiring
 
@@ -52,6 +52,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [NavStack](./nav-stack.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Row](./row.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+- Components: [NavStack](./nav-stack.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Row](./row.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
 - Docs: [`docs/recipes.md#navigation-stack`](../../docs/recipes.md#navigation-stack).
 - UX catalog route: `?component=recipe-navigation-stack`.

package/ai/components/recipe-workspace-header.md

@@ -1,4 +1,4 @@
-# Workspace header
+# Workspace Header
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 
@@ -28,7 +28,7 @@ No props: this entry has no JavaScript API.
 - Parents: used at the root of a screen or reference, not nested.
 - Contexts: `application-reference`.
 - Children: unrestricted.
-- Built from: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [StateBanner](./state-banner.md), [Application layout](./layout.md).
+- Built from: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [StateBanner](./state-banner.md), [Application Layout](./layout.md).
 
 ## State and wiring
 
@@ -52,6 +52,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [StateBanner](./state-banner.md), [Application layout](./layout.md).
+- Components: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [StateBanner](./state-banner.md), [Application Layout](./layout.md).
 - Docs: [`docs/recipes.md#workspace-header`](../../docs/recipes.md#workspace-header).
 - UX catalog route: `?component=recipe-workspace-header`.

package/ai/components/resize.md

@@ -16,7 +16,7 @@ Pointer and keyboard-operable split region with a customizable handle icon.
 
 **Alternatives:**
 
-- [Application layout](./layout.md) (nearest)
+- [Application Layout](./layout.md) (nearest)
 - [Split Panel](./wa-split-panel.md) (prefer-over)
 
 ## Imports
@@ -101,6 +101,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [Split Panel](./wa-split-panel.md).
+- Components: [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [Split Panel](./wa-split-panel.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#resizableregion`](../../docs/accessibility.md#resizableregion).
 - UX catalog route: `?component=resize`.

package/ai/components/split-view.md

@@ -20,7 +20,7 @@ Present a selectable list and its detail together when space permits, with a one
 
 **Alternatives:**
 
-- [Navigation stack](./recipe-navigation-stack.md) (responsive-alternative) — SplitView renders the one-pane navigation-stack form on compact device classes.
+- [Navigation Stack](./recipe-navigation-stack.md) (responsive-alternative) — SplitView renders the one-pane navigation-stack form on compact device classes.
 - [Workbench](./workbench.md) (nearest) — Use Workbench when a desktop-class tool needs more than the list and detail regions.
 
 ## Imports
@@ -72,6 +72,8 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 - `data-nav-chrome-copy` on `kui-nav-stack__chrome-copy` (`wireNavStack`): Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade.
 - `data-nav-revealed` on `kui-nav-stack__view` (`wireNavStack`): "true" on the preserved, aria-hidden previous view while an incoming view slides over it.
 - `data-nav-exiting` on `kui-nav-stack__view` (`wireNavStack`): "true" on a popped view the helper briefly re-inserts to slide it out.
+- `data-chrome-overlay` on `kui-nav-stack` (`wireNavStack`): measured once the helper has measured the compact stack's overlay chrome (compactStack.chromePresentation: overlay) and published its border-box height on the stack root. Re-applied if a re-render drops it.
+- `data-bottom-toolbar-overlay` on `kui-nav-stack` (`wireNavStack`): measured once the helper has measured the compact stack's overlay bottom toolbar (compactStack.bottomToolbarPresentation: overlay) and published its border-box height on the stack root. Re-applied if a re-render drops it.
 
 ## Geometry
 
@@ -98,6 +100,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [NavStack](./nav-stack.md), [ResizableRegion](./resize.md), [Navigation stack](./recipe-navigation-stack.md), [Workbench](./workbench.md).
+- Components: [NavStack](./nav-stack.md), [ResizableRegion](./resize.md), [Navigation Stack](./recipe-navigation-stack.md), [Workbench](./workbench.md).
 - Docs: [`docs/split-view.md`](../../docs/split-view.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
 - UX catalog route: `?component=split-view`.

package/ai/components/sunken-panel.md

@@ -19,7 +19,7 @@ Group a vertical list of application content on a visually lowered surface with
 
 **Alternatives:**
 
-- [Application layout](./layout.md) (composes-with) — Use layout roles for pane, toolbar, scroll, and ordinary content-stack ownership.
+- [Application Layout](./layout.md) (composes-with) — Use layout roles for pane, toolbar, scroll, and ordinary content-stack ownership.
 
 ## Imports
 
@@ -74,6 +74,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Application layout](./layout.md).
+- Components: [Application Layout](./layout.md).
 - Docs: [`docs/sunken-panel.md`](../../docs/sunken-panel.md), [`docs/sunken-panel.md#ownership`](../../docs/sunken-panel.md#ownership).
 - UX catalog route: `?component=sunken-panel`.

package/ai/components/surface-scaffold.md

@@ -1,4 +1,4 @@
-# Surface scaffolds
+# Surface Scaffolds
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 
@@ -14,11 +14,14 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 - A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText.
 - A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions.
 - A dialog that must leave the page interactive and close on Escape or an outside press uses PopoverDialogSurface; one that fills its body with a SplitView or Pane uses height and bodyLayout="fill".
+- A chat-style dialog floats its composer over the transcript with footerPresentation="floating" and keeps a heading or notice above one scrolling transcript with bodyLayout="fill-last".
+- A dialog's title bar should float over the body on the translucent chrome material so a transcript scrolls visibly beneath both the title bar and a floating composer (headerPresentation="floating" with bodyLayout="fill" and a List or Pane that opts into scrollClearance="both").
 
 **Not when:**
 
 - 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.
+- Do not put quiet secondary text of your own in a floating dialog header; it can fall below AA over the content passing beneath. A ToolbarText slotted as the dialog's label (or into header-actions) is fine: its title takes the normal text color and its description lifts halfway toward it, keeping AA.
 
 ## Imports
 
@@ -38,7 +41,13 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 - modal, side-sheet, or fullscreen dialog
 - typed modal preferred width, viewport gutter, and maximum height, including viewport cap
 - definite viewport-bounded modal height and a fill body layout for one child
-- non-modal light-dismiss PopoverDialogSurface, overlay or embedded in flow
+- fill-last body layout: fixed rows above one filling, scrolling last child
+- docked or floating footer with a typed footerOffset; the body reserves the measured footer height
+- floating footer over a filling child that opts into block-end scrollClearance: content scrolls beneath the footer through the published --kui-scroll-clearance-block-end
+- docked or floating header (headerPresentation) on the translucent chrome material; the body reserves the measured header height
+- floating header over a filling only child that opts into block-start scrollClearance: content scrolls beneath the title bar through the published --kui-scroll-clearance-block-start
+- floating header divider as scroll state: a hairline under the title bar only while the body or a filling child beneath it is scrolled away from its top
+- non-modal light-dismiss PopoverDialogSurface, overlay or embedded in flow, named by label or labelledBy and described by describedBy
 - none, compact, or comfortable body and footer inset
 - standard, compact, or zero-inset popup menu
 
@@ -46,6 +55,7 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 
 - `preferredWidth`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `preferredWidth={remify(832)}`
 - `viewportGutter`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `viewportGutter={remify(8)}`
+- `footerOffset`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `footerOffset={remify(8)}`
 - `maxHeight`: length grammar; raw values: forbid; shorthands `viewport`; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `maxHeight="viewport"`
 
 ## Composition
@@ -68,6 +78,8 @@ Margin: parent · border: child · padding: self (layout role: structure). `self
 ## Accessibility
 
 - Supply the wrapped wa-dialog label and retain Web Awesome's native modal and focus behavior.
+- Name a PopoverDialogSurface with label or labelledBy, and describe it with describedBy (rendered as aria-describedby), usually a title ToolbarText descriptionId.
+- A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
 - Use popup surfaces only for real dropdown menus with named triggers.
 
 ## Styling boundary
@@ -82,7 +94,7 @@ Never put `kui-popover-dialog-surface` on an element you write; render `PopoverD
 
 Never put `kui-popup-surface` on an element you write; render `PopupSurface` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-radius-l`, `--kui-wa-container-inset`, `--kui-wa-surface-inset`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-radius-l`, `--kui-wa-container-inset`, `--kui-wa-surface-inset`, `--kui-chrome-material-raised`, `--kui-chrome-material-filter`, `--kui-scroll-clearance-block-start`, `--kui-scroll-clearance-block-end`. Set a token only where its public contract allows; prefer a prop.
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 

package/ai/components/tab-bar.md

@@ -78,6 +78,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 - `data-tab-autoscroll` on `kui-tab-bar__tabs` (`wireTabBars`): "start" or "end" while a drag near that edge auto-scrolls the strip.
 - `data-scroll-overflow` on `kui-tab-bar__tabs` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
 - `data-scroll-divider` on `chrome named in wireScrollDividers targets (a TabBar strip has none)` (`wireScrollDividers`): The sides, in t/r/b/l order, on which that chrome currently draws its scroll divider. Re-applied if a re-render drops it.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it.
 
 ## Geometry
 

package/ai/components/tab-navigator.md

@@ -44,6 +44,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 - bar divider only while the active scene continues below it (wired by wireScrollDividers)
 - permanent or no bar divider (chromeDividers always or none)
 - sunken active-scene separator (separator auto or hidden)
+- translucent tab bar laid over the active scene (barPresentation overlay, measured by wireTabNavigator)
 
 ## Composition
 
@@ -64,6 +65,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 
 - `data-scroll-overflow` on `the active kui-tab-scaffold__scene, or what scrolls inside it (a sole NavStack's active view or a sole Pane's content)` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
 - `data-scroll-divider` on `kui-tab-scaffold__bar` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it.
 
 ## Geometry
 
@@ -71,6 +73,7 @@ Margin: none · border: conditional · padding: self (layout role: structure). `
 
 - The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.
 - The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it.
+- barPresentation=overlay: once wireTabNavigator has measured the live bar (data-bar-overlay=measured), the bar is absolutely positioned over the scenes on --kui-chrome-material and the scenes route its border-box height (bottom safe area included) as the block-end --kui-edge-inset-\* context, so a plain scene pads and scroll-pads by it and a sole Pane or NavStack clears it; unwired it stays docked.
 
 ## Accessibility
 
@@ -78,6 +81,7 @@ Margin: none · border: conditional · padding: self (layout role: structure). `
 - Wire selection through the controlled active id while leaving inactive scenes mounted and hidden.
 - A focusable scene is a tabpanel named by its tab label; optional scene tabIndex applies only while active.
 - A tab badge is aria-hidden; supply badgeLabel so the tab's accessible name becomes "\<label>, \<badgeLabel>" (it defaults to the badge text). The dot form, badge: true, has no text, so its badgeLabel is required.
+- Over the overlay bar's translucent material, unselected labels lift halfway toward --kui-color-text and the selected label mixes 40% of it into the brand color, so both keep 4.5:1 over worst-case content; the material turns opaque under reduced transparency or increased contrast and paints Canvas with a CanvasText edge in forced colors.
 
 ## Styling boundary
 

package/ai/components/toolbar-control-group.md

@@ -101,6 +101,8 @@ Margin: none · border: self · padding: self (layout role: structure). `self` m
 - Name the group when its relationship is not evident from context.
 - A disabled native button (disabled, or aria-disabled="true" when it must stay focusable) dims to half opacity with the not-allowed cursor and no hover surface; a disabled raw wa-button paints no hover surface either. Do not add disabled styling yourself.
 - Name an icon-only button or link with aria-label, not title. Once any help-tag installer is imported (select/register, popup-menu/register, or help-tags/register), it shows an aria-hidden Web Awesome help tag repeating that name after a 500ms hover and at once on keyboard focus, hidden on a press and on Escape, and never joins aria-labelledby. A native title keeps the browser tooltip and gets no second tag.
+- In an overlay Pane header (headerPresentation="overlay"), overlay NavStack chrome (chromePresentation="overlay") or bottom toolbar (bottomToolbarPresentation="overlay"), or a DialogSurface floating header's header-actions (headerPresentation="floating"), a default-tone group (not dark-toned, not an avatar scrim) takes --kui-color-text for its controls, so they keep WCAG AA over content passing beneath the translucent chrome material.
+- A dark-toned group's hover paints a 14% surface wash over its loud fill, on one control of a group or across a lone control's whole group, so the on-loud icon keeps at least 3:1 over a light page and well above it in dark.
 
 ## Styling boundary
 

package/ai/components/toolbar-text.md

@@ -79,6 +79,7 @@ Margin: none · border: none · padding: none (layout role: structure). `self` m
 
 - Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title.
 - Actionable text is a native button with its full text as its accessible name; action cannot be combined with headingLevel, placeholder, or wrap.
+- In a Pane header with headerPresentation="overlay" or NavStack chrome with chromePresentation="overlay" (or its bottom toolbar with bottomToolbarPresentation="overlay"), or slotted as the label (or into header-actions) of a DialogSurface header with headerPresentation="floating", untoned text keeps WCAG AA over the translucent chrome material: the title takes --kui-color-text at every size and the description mixes --kui-color-text-quiet halfway toward it.
 
 ## Styling boundary
 

package/ai/components/toolbar.md

@@ -67,6 +67,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 - `data-scroll-overflow` on `the targets scroller` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
 - `data-scroll-divider` on `a Toolbar named as targets chrome` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it.
 - `data-toolbar-width-hidden` on `ToolbarText, ToolbarControlGroup and its paired busy status` (`wireToolbarVisibility`): True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers.
 - `data-toolbar-visibility-probe` on `private aria-hidden measurement boxes under Toolbar` (`wireToolbarVisibility`): Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility.
 - `data-morph-preserve` on `private aria-hidden measurement boxes and visibility state children` (`wireToolbarVisibility`): Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them.

package/ai/components/workbench.md

@@ -84,6 +84,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 - `data-resizing` on `kui-workbench__rail` (`wireWorkbench`): Present on a resizable rail or the drawer while a pointer drag resizes it.
 - `data-scroll-overflow` on `kui-pane__content of each panel and work-area Pane` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
 - `data-scroll-divider` on `kui-pane__header and kui-pane__footer of each panel and work-area Pane` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it.
 
 ## Geometry