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

package/ai/component-composition.json

@@ -83,6 +83,11 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "link destination and download file name",
+          "owner": "application",
+          "required": false
+        },
         { "id": "disabled policy", "owner": "application", "required": false }
       ],
       "wiring": {
@@ -99,6 +104,8 @@
       "accessibility": {
         "obligations": [
           "The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.",
+          "A link chip is a native anchor named by its visible label; external adds a safe rel, a new tab, and an \"(opens in new tab)\" name suffix, and a disabled link chip drops its destination and leaves the tab order.",
+          "The inherit tone paints no fill, so its label keeps the surrounding text contrast, and its focus ring follows the surrounding foreground.",
           "Keep meaningful tag text visible because tone is supplementary."
         ]
       },
@@ -241,7 +248,7 @@
       "key": "@kerfjs/ui:foundation",
       "package": "@kerfjs/ui",
       "id": "foundation",
-      "name": "Foundation tokens",
+      "name": "Foundation Tokens",
       "kind": "composition",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
@@ -330,6 +337,9 @@
           "--kui-color-surface-lowered",
           "--kui-sunken-texture",
           "--kui-sunken-surface",
+          "--kui-chrome-material",
+          "--kui-chrome-material-raised",
+          "--kui-chrome-material-filter",
           "--kui-color-text",
           "--kui-color-text-quiet",
           "--kui-color-text-link",
@@ -407,7 +417,7 @@
       "key": "@kerfjs/ui:document-baseline",
       "package": "@kerfjs/ui",
       "id": "document-baseline",
-      "name": "Document baseline",
+      "name": "Document Baseline",
       "kind": "composition",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
@@ -467,7 +477,7 @@
       "key": "@kerfjs/ui:layout",
       "package": "@kerfjs/ui",
       "id": "layout",
-      "name": "Application layout",
+      "name": "Application Layout",
       "kind": "composition",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
@@ -626,6 +636,16 @@
           "id": "optional keyboard or programmatic focus (tabIndex) and persistent focus outline (outlined)",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "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)",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "whether the header is docked in its own row or laid over the scrolling content on the translucent chrome material (headerPresentation, also in PaneConfig)",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -644,6 +664,12 @@
             "on": "kui-pane__header and kui-pane__footer",
             "helper": "wireScrollDividers",
             "meaning": "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."
+          },
+          {
+            "name": "data-header-overlay",
+            "on": "kui-pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -659,14 +685,17 @@
             "Safe areas: the root and separators paint through unsafe areas while header, content, and footer pad the sides the pane still reaches (routed by --kui-edge-inset-*); content block insets are scroll padding.",
             "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."
+            "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": {
         "obligations": [
           "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."
+          "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."
         ]
       },
       "cssValueProps": [],
@@ -690,7 +719,10 @@
           "--kui-pane-content-inset-inline-start",
           "--kui-pane-content-inset-inline-end",
           "--kui-pane-scrollbar-gutter",
-          "--kui-sunken-panel-background"
+          "--kui-sunken-panel-background",
+          "--kui-chrome-material",
+          "--kui-chrome-material-filter",
+          "--kui-scroll-clearance-block-start"
         ]
       },
       "diagnostics": [],
@@ -755,6 +787,16 @@
           "id": "whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers)",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "whether the top chrome docks above the active view or lies over it on the translucent chrome material (chromePresentation)",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "whether the bottom toolbar docks below the active view or lies over it on the translucent chrome material (bottomToolbarPresentation)",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -786,6 +828,18 @@
             "helper": "wireNavStack",
             "meaning": "\"true\" on a popped view the helper briefly re-inserts to slide it out."
           },
+          {
+            "name": "data-chrome-overlay",
+            "on": "kui-nav-stack",
+            "helper": "wireNavStack",
+            "meaning": "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."
+          },
+          {
+            "name": "data-bottom-toolbar-overlay",
+            "on": "kui-nav-stack",
+            "helper": "wireNavStack",
+            "meaning": "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."
+          },
           {
             "name": "data-scroll-overflow",
             "on": "the active kui-nav-stack__view, or the kui-pane__content of a sole Pane in it",
@@ -797,6 +851,12 @@
             "on": "kui-nav-stack__chrome and kui-nav-stack__bottom",
             "helper": "wireScrollDividers",
             "meaning": "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."
+          },
+          {
+            "name": "data-header-overlay",
+            "on": "kui-pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -809,7 +869,9 @@
           "padding": "child",
           "notes": [
             "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."
+            "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."
           ]
         }
       },
@@ -818,7 +880,9 @@
           "Give the stack region an accessible label and every back control a stable action label; visible backText names the control itself.",
           "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."
+          "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."
         ]
       },
       "cssValueProps": [],
@@ -944,6 +1008,18 @@
             "on": "kui-nav-stack__view",
             "helper": "wireNavStack",
             "meaning": "\"true\" on a popped view the helper briefly re-inserts to slide it out."
+          },
+          {
+            "name": "data-chrome-overlay",
+            "on": "kui-nav-stack",
+            "helper": "wireNavStack",
+            "meaning": "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."
+          },
+          {
+            "name": "data-bottom-toolbar-overlay",
+            "on": "kui-nav-stack",
+            "helper": "wireNavStack",
+            "meaning": "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."
           }
         ]
       },
@@ -1051,6 +1127,12 @@
             "on": "kui-tab-scaffold__bar",
             "helper": "wireScrollDividers",
             "meaning": "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."
+          },
+          {
+            "name": "data-header-overlay",
+            "on": "kui-pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -1063,7 +1145,8 @@
           "padding": "self",
           "notes": [
             "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."
+            "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."
           ]
         }
       },
@@ -1072,7 +1155,8 @@
           "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.",
           "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."
+          "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."
         ]
       },
       "cssValueProps": [],
@@ -1207,6 +1291,12 @@
             "on": "kui-pane__header and kui-pane__footer of each panel and work-area Pane",
             "helper": "wireScrollDividers",
             "meaning": "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."
+          },
+          {
+            "name": "data-header-overlay",
+            "on": "kui-pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -1335,6 +1425,12 @@
             "on": "kui-pane__header and kui-pane__footer of each panel and work-area Pane",
             "helper": "wireScrollDividers",
             "meaning": "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."
+          },
+          {
+            "name": "data-header-overlay",
+            "on": "kui-pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -1529,6 +1625,12 @@
             "helper": "wireScrollDividers",
             "meaning": "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."
           },
+          {
+            "name": "data-header-overlay",
+            "on": "kui-pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          },
           {
             "name": "data-toolbar-width-hidden",
             "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
@@ -1683,7 +1785,9 @@
         "obligations": [
           "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."
+          "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."
         ]
       },
       "cssValueProps": [
@@ -1775,7 +1879,7 @@
       "key": "@kerfjs/ui:surface-scaffold",
       "package": "@kerfjs/ui",
       "id": "surface-scaffold",
-      "name": "Surface scaffolds",
+      "name": "Surface Scaffolds",
       "kind": "component",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
@@ -1803,6 +1907,8 @@
       "accessibility": {
         "obligations": [
           "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."
         ]
       },
@@ -1847,6 +1953,26 @@
           "rawPolicy": "forbid",
           "examples": ["viewportGutter={remify(8)}"]
         },
+        {
+          "path": "footerOffset",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["footerOffset={remify(8)}"]
+        },
         {
           "path": "maxHeight",
           "grammar": "length",
@@ -1878,7 +2004,11 @@
         "publicTokens": [
           "--kui-radius-l",
           "--kui-wa-container-inset",
-          "--kui-wa-surface-inset"
+          "--kui-wa-surface-inset",
+          "--kui-chrome-material-raised",
+          "--kui-chrome-material-filter",
+          "--kui-scroll-clearance-block-start",
+          "--kui-scroll-clearance-block-end"
         ]
       },
       "diagnostics": [],
@@ -2014,7 +2144,8 @@
       "accessibility": {
         "obligations": [
           "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."
+          "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."
         ]
       },
       "cssValueProps": [
@@ -2853,11 +2984,21 @@
           "id": "the accessible label and selection state of a multi-select grid",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "which one scroller opts into scroll clearance (the one reaching the covered edge)",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "the result picker bounds (maxHeight/minHeight) and its rows",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
         "required": false,
-        "helpers": ["wireScrollDividers"],
+        "helpers": ["wireScrollDividers", "wireListFocusScroll"],
         "obligations": [],
         "stateAttributes": [
           {
@@ -2871,6 +3012,12 @@
             "on": "a List named as targets chrome",
             "helper": "wireScrollDividers",
             "meaning": "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."
+          },
+          {
+            "name": "data-header-overlay",
+            "on": "kui-pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -2882,7 +3029,11 @@
           "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."
+            "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.",
+            "scrollClearance adds the inherited --kui-scroll-clearance-block-start/end context, published by overlaying chrome, to the List block padding and scroll-padding on the opted-in edges; without it the context is ignored.",
+            "frame draws a 1px --kui-color-neutral-border-normal border with --kui-radius-m and a 4px --kui-space-2xs inset on every side (replacing inset/textInsets/controlInsets), exactly the focus-ring reach, so the first and last rows' rings stay inside the clip at the scroll extremes; maxHeight/minHeight bound the List directly.",
+            "Every scrollable List's block scroll padding is the focus-ring reach plus 2px of slack (6px, no change at rest), so any row focused or scrolled into view stops with its ring inside the clip; an unframed List's first and last rows still meet the clip at the scroll extremes, so use frame when they must show a whole ring.",
+            "As a direct child of a Pane's scrolling content, a List that does not scroll itself never shrinks below its rows (flex-shrink 0), so the content's block-end padding (a bottom safe area, an overlay NavStack bottom toolbar's clearance) follows its last row."
           ]
         }
       },
@@ -2890,7 +3041,8 @@
         "obligations": [
           "List adds layout only and no list role by default; selectionMode=\"multiple\" makes it an aria-multiselectable grid with a required ariaLabel for selectable ContentItem rows.",
           "Give a scrollable List a bounded block size and keep keyboard focus visible as its contents scroll.",
-          "A focused scrollable List (a keyboard-focusable scroller) draws the theme focus ring inset and rounded inside its own box, so a rounded or clipping parent never cuts it off; do not restyle its focus."
+          "A focused scrollable List (a keyboard-focusable scroller) draws the theme focus ring inset and rounded inside its own box, so a rounded or clipping parent never cuts it off; do not restyle its focus.",
+          "With wireListFocusScroll, a keyboard-focused (:focus-visible) element in a scrollable List whose focus ring crosses the clip is scrolled into view (block and inline nearest, honoring the ring-room scroll padding) in every engine; pointer focus never scrolls, so a click cannot move its row from under the pointer."
         ]
       },
       "cssValueProps": [
@@ -2919,6 +3071,28 @@
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
           "examples": ["flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
+        },
+        {
+          "path": "maxHeight",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["maxHeight={rem(14)}"]
+        },
+        {
+          "path": "minHeight",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["minHeight={rem(4.25)}"]
         }
       ],
       "boundaries": {
@@ -3080,6 +3254,34 @@
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
           "examples": ["className=\"app-row\""]
+        },
+        {
+          "path": "iconTile.color",
+          "grammar": "color",
+          "helpers": ["fillColor", "uiColor", "colorVar"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "iconTile={{ color: fillColor(\"#e5484d\") }}",
+            "iconTile={{ color: uiColor(\"brand-fill-loud\") }}",
+            "iconTile={{ color: colorVar(\"--app-category-color\") }}"
+          ]
+        },
+        {
+          "path": "iconTile.foreground",
+          "grammar": "color",
+          "helpers": ["uiColor", "foregroundColorVar", "foregroundColor"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "iconTile={{ color: fillColor(\"#e5484d\"), foreground: foregroundColor(\"white\") }}",
+            "iconTile={{ color: uiColor(\"brand-fill-loud\"), foreground: uiColor(\"brand-on-loud\") }}",
+            "iconTile={{ color: colorVar(\"--app-tile\"), foreground: foregroundColorVar(\"--app-tile-ink\") }}"
+          ]
         }
       ],
       "boundaries": {
@@ -3123,7 +3325,21 @@
           "--kui-list-action-row-selected-color",
           "--kui-list-action-row-trailing-hover-background",
           "--kui-list-group-divider-color",
-          "--kui-font-xs"
+          "--kui-list-row-padding-inline",
+          "--kui-list-row-icon-size",
+          "--kui-font-xs",
+          "--kui-radius-m",
+          "--kui-color-brand-fill-quiet",
+          "--kui-color-brand-on-quiet",
+          "--kui-color-success-fill-quiet",
+          "--kui-color-success-border-quiet",
+          "--kui-color-success-on-quiet",
+          "--kui-color-warning-fill-quiet",
+          "--kui-color-warning-border-quiet",
+          "--kui-color-warning-on-quiet",
+          "--kui-color-danger-fill-quiet",
+          "--kui-color-danger-border-quiet",
+          "--kui-color-danger-on-quiet"
         ]
       },
       "diagnostics": [],
@@ -3206,6 +3422,34 @@
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
           "examples": ["className=\"app-row\""]
+        },
+        {
+          "path": "iconTile.color",
+          "grammar": "color",
+          "helpers": ["fillColor", "uiColor", "colorVar"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "iconTile={{ color: fillColor(\"#e5484d\") }}",
+            "iconTile={{ color: uiColor(\"brand-fill-loud\") }}",
+            "iconTile={{ color: colorVar(\"--app-category-color\") }}"
+          ]
+        },
+        {
+          "path": "iconTile.foreground",
+          "grammar": "color",
+          "helpers": ["uiColor", "foregroundColorVar", "foregroundColor"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "iconTile={{ color: fillColor(\"#e5484d\"), foreground: foregroundColor(\"white\") }}",
+            "iconTile={{ color: uiColor(\"brand-fill-loud\"), foreground: uiColor(\"brand-on-loud\") }}",
+            "iconTile={{ color: colorVar(\"--app-tile\"), foreground: foregroundColorVar(\"--app-tile-ink\") }}"
+          ]
         }
       ],
       "boundaries": {
@@ -3260,11 +3504,24 @@
           "--kui-list-item-selected-color",
           "--kui-list-item-trailing-color",
           "--kui-list-group-divider-color",
+          "--kui-list-row-padding-inline",
+          "--kui-list-row-icon-size",
           "--kui-font-xs",
           "--kui-layout-inline-margin",
           "--kui-layout-item-gap",
           "--kui-layout-item-padding",
-          "--kui-layout-rounded-radius"
+          "--kui-layout-rounded-radius",
+          "--kui-radius-m",
+          "--kui-color-brand-on-quiet",
+          "--kui-color-success-fill-quiet",
+          "--kui-color-success-border-quiet",
+          "--kui-color-success-on-quiet",
+          "--kui-color-warning-fill-quiet",
+          "--kui-color-warning-border-quiet",
+          "--kui-color-warning-on-quiet",
+          "--kui-color-danger-fill-quiet",
+          "--kui-color-danger-border-quiet",
+          "--kui-color-danger-on-quiet"
         ]
       },
       "diagnostics": [],
@@ -3460,7 +3717,7 @@
       "key": "@kerfjs/ui:application-tabs",
       "package": "@kerfjs/ui",
       "id": "application-tabs",
-      "name": "Application tabs",
+      "name": "Application Tabs",
       "kind": "composition",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
@@ -3706,6 +3963,12 @@
             "on": "chrome named in wireScrollDividers targets (a TabBar strip has none)",
             "helper": "wireScrollDividers",
             "meaning": "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."
+          },
+          {
+            "name": "data-header-overlay",
+            "on": "kui-pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -3845,7 +4108,7 @@
       "kind": "component",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
-      "contexts": ["wrapping-exclusive-choice"],
+      "contexts": ["wrapping-exclusive-choice", "wrapping-multiple-choice"],
       "zones": [],
       "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
       "state": [{ "id": "value", "owner": "controlled", "required": false }],
@@ -3862,11 +4125,26 @@
       },
       "accessibility": {
         "obligations": [
-          "Name the radio group with label or with labelledBy pointing at a visible heading.",
+          "Name the radio group (or, with multiple, the checkbox group) with label or with labelledBy pointing at a visible heading.",
           "Every choice keeps a visible text label; a swatch or icon is decorative."
         ]
       },
-      "cssValueProps": [],
+      "cssValueProps": [
+        {
+          "path": "choices[].swatch",
+          "grammar": "color",
+          "helpers": ["fillColor", "uiColor", "colorVar"],
+          "shorthands": ["transparent"],
+          "canonicalShorthands": ["transparent"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "swatch: fillColor(\"#3b82f6\")",
+            "swatch: uiColor(\"brand-fill-loud\")",
+            "swatch: colorVar(\"--app-label-color\")"
+          ]
+        }
+      ],
       "boundaries": {
         "rootClass": "kui-choice-chips",
         "publicClasses": ["kui-choice-chips"],
@@ -3878,6 +4156,55 @@
         "composition": "docs/accessibility.md#choicechips"
       }
     },
+    {
+      "key": "@kerfjs/ui:composer",
+      "package": "@kerfjs/ui",
+      "id": "composer",
+      "name": "Composer",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["chat-composer", "dialog-floating-footer"],
+      "zones": [
+        {
+          "id": "actions",
+          "jsx": { "prop": "actions" },
+          "accepts": ["KerfUiContent"],
+          "cardinality": { "min": 1, "max": "unbounded" },
+          "exclusiveWith": []
+        }
+      ],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [{ "id": "value", "owner": "controlled", "required": false }],
+      "wiring": {
+        "required": false,
+        "helpers": ["wireComposers"],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["controls"],
+        "geometry": { "margin": "none", "border": "self", "padding": "self" }
+      },
+      "accessibility": {
+        "obligations": [
+          "Name the message field with label in title style; give it an id so a hint becomes its accessible description.",
+          "Give every trailing action a visible or accessible name, such as a Send button."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-composer",
+        "publicClasses": ["kui-composer"],
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "docs/accessibility.md#composer"
+      }
+    },
     {
       "key": "@kerfjs/ui:token-search-field",
       "package": "@kerfjs/ui",
@@ -4396,7 +4723,7 @@
       },
       "accessibility": {
         "obligations": [
-          "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."
         ]
       },
@@ -7864,7 +8191,7 @@
       "key": "@kerfjs/ui:recipe-app-shell",
       "package": "@kerfjs/ui",
       "id": "recipe-app-shell",
-      "name": "Desktop application shell",
+      "name": "Desktop Application Shell",
       "kind": "recipe",
       "source": "kerf",
       "parents": { "mode": "root", "entries": [] },
@@ -7917,7 +8244,7 @@
       "key": "@kerfjs/ui:recipe-navigation-sidebar",
       "package": "@kerfjs/ui",
       "id": "recipe-navigation-sidebar",
-      "name": "Navigation sidebar",
+      "name": "Navigation Sidebar",
       "kind": "recipe",
       "source": "kerf",
       "parents": { "mode": "root", "entries": [] },
@@ -7970,7 +8297,7 @@
       "key": "@kerfjs/ui:recipe-workspace-header",
       "package": "@kerfjs/ui",
       "id": "recipe-workspace-header",
-      "name": "Workspace header",
+      "name": "Workspace Header",
       "kind": "recipe",
       "source": "kerf",
       "parents": { "mode": "root", "entries": [] },
@@ -8073,7 +8400,7 @@
       "key": "@kerfjs/ui:recipe-composer-form",
       "package": "@kerfjs/ui",
       "id": "recipe-composer-form",
-      "name": "Composer form",
+      "name": "Composer Form",
       "kind": "recipe",
       "source": "kerf",
       "parents": { "mode": "root", "entries": [] },
@@ -8126,7 +8453,7 @@
       "key": "@kerfjs/ui:recipe-list-workspace-states",
       "package": "@kerfjs/ui",
       "id": "recipe-list-workspace-states",
-      "name": "List workspace states",
+      "name": "List Workspace States",
       "kind": "recipe",
       "source": "kerf",
       "parents": { "mode": "root", "entries": [] },
@@ -8175,7 +8502,7 @@
       "key": "@kerfjs/ui:recipe-compact-toolbar",
       "package": "@kerfjs/ui",
       "id": "recipe-compact-toolbar",
-      "name": "Compact toolbar choices and actions",
+      "name": "Compact Toolbar Choices and Actions",
       "kind": "recipe",
       "source": "kerf",
       "parents": { "mode": "root", "entries": [] },
@@ -8232,7 +8559,7 @@
       "key": "@kerfjs/ui:recipe-navigation-stack",
       "package": "@kerfjs/ui",
       "id": "recipe-navigation-stack",
-      "name": "Navigation stack",
+      "name": "Navigation Stack",
       "kind": "recipe",
       "source": "kerf",
       "parents": { "mode": "root", "entries": [] },
@@ -8285,7 +8612,7 @@
       "key": "@kerfjs/ui:recipe-loading-inspector",
       "package": "@kerfjs/ui",
       "id": "recipe-loading-inspector",
-      "name": "Loading inspector",
+      "name": "Loading Inspector",
       "kind": "recipe",
       "source": "kerf",
       "parents": { "mode": "root", "entries": [] },
@@ -8345,7 +8672,7 @@
       "key": "@kerfjs/ui:recipe-collapsible-sidebar",
       "package": "@kerfjs/ui",
       "id": "recipe-collapsible-sidebar",
-      "name": "Collapsible sidebar",
+      "name": "Collapsible Sidebar",
       "kind": "recipe",
       "source": "kerf",
       "parents": { "mode": "root", "entries": [] },