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

package/ai/component-composition.schema.json

@@ -384,7 +384,7 @@
       "properties": {
         "path": {
           "type": "string",
-          "pattern": "^[A-Za-z][A-Za-z0-9]*(?:\\[\\]\\.[A-Za-z][A-Za-z0-9]*)?$"
+          "pattern": "^(?:[A-Za-z][A-Za-z0-9]*(?:\\[\\])?\\.)*[A-Za-z][A-Za-z0-9]*$"
         },
         "grammar": {
           "enum": [

package/ai/components/README.md

@@ -9,12 +9,12 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 ## Kerf UI — Foundation
 
 - [Badge](./badge.md) — Present compact metadata without application-authored badge CSS or consumer styling of component internals.
-- [Chip](./chip.md) — Render removable tags without application rules on Web Awesome internals.
+- [Chip](./chip.md) — Render removable tags and file or link chips without application rules on Web Awesome internals or anchor chrome.
 - [LucideIcon](./lucide-icon.md) — Decorative and meaningfully labeled Lucide-compatible icons.
 - [DisclosureArrow](./disclosure-arrow.md) — Indicate whether a disclosure control is open with an overridable 18px root-scaled visual and shortest-path rotation behavior.
-- [Foundation tokens](./foundation.md) — Provide the shared semantic token foundation for application themes and every styled Kerf UI component.
-- [Document baseline](./document-baseline.md) — Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.
-- [Application layout](./layout.md) — Provide one reusable pane, toolbar, content stack, and content-item geometry across sidebars, main areas, and dialogs.
+- [Foundation Tokens](./foundation.md) — Provide the shared semantic token foundation for application themes and every styled Kerf UI component.
+- [Document Baseline](./document-baseline.md) — Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.
+- [Application Layout](./layout.md) — Provide one reusable pane, toolbar, content stack, and content-item geometry across sidebars, main areas, and dialogs.
 
 ## Kerf UI — Structure
 
@@ -27,7 +27,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [SunkenPanel](./sunken-panel.md) — Group a vertical list of application content on a visually lowered surface with one owned 8px inset and an explicit rounded or square-corner shape.
 - [Toolbar](./toolbar.md) — Leading, centered, and trailing toolbar composition.
 - [ToolbarControlGroup](./toolbar-control-group.md) — Provide complete toolbar action geometry through configuration, including semantic anchors, overflow containment, and dropdown menu insets without application CSS.
-- [Surface scaffolds](./surface-scaffold.md) — Configure recurring dialog and popup geometry without consumer ::part() overrides.
+- [Surface Scaffolds](./surface-scaffold.md) — Configure recurring dialog and popup geometry without consumer ::part() overrides.
 - [FloatingToolbar](./floating-toolbar.md) — A transparent, forced-dark toolbar that floats over its container's content.
 - [ToolbarText](./toolbar-text.md) — Extra-large through extra-small toolbar identity text.
 - [Text](./text.md) — Render paragraph semantics by default, h1 through h6 when selected, or geometry-free inline secondary text as a span while independently configuring quiet or danger tone, compact through extra-large size, or monospace font.
@@ -50,14 +50,15 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [ListHeader](./list-header.md) — Fill the available section width by default, or shrink-wrap without outer geometry when inline, while splitting a dormant title and optional count or combined badge/status indicators from a logical-end action with an 18px visual; disclosure mode renders the title cluster as a button with a default production DisclosureArrow.
 - [ListActionRow](./list-action-row.md) — Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.
 - [ListItem](./list-item.md) — Selectable, disabled, trailing, and multiline action or link rows.
-- [Application tabs](./application-tabs.md) — Show AppTab and TabBar in a complete controlled composition.
+- [Application Tabs](./application-tabs.md) — Show AppTab and TabBar in a complete controlled composition.
 - [AppTab](./tabs.md) — Render a controlled application tab with compact or icon-only presentation, a visible drop target, optional full-name display, and an optional pinned leading position.
 - [TabBar](./tab-bar.md) — Controlled tab strips whose tabs shrink and scroll while fixed leading, trailing, and far-edge end actions remain visible.
 
 ## Kerf UI — Controls
 
 - [SegmentedControl](./segmented-control.md) — Controlled exclusive choices in toolbar, rounded-rectangle, and pill presentations.
-- [ChoiceChips](./choice-chips.md) — Choose one value from a visible set too large for a segmented track, such as a color palette with labeled swatches.
+- [ChoiceChips](./choice-chips.md) — Choose one value, or with multiple any number of values, from a visible set too large for a segmented track, such as a color palette with labeled swatches or a set of annotation intents.
+- [Composer](./composer.md) — Write a chat message or prompt in a raised frame whose border turns brand while focus is within, with a field that grows between row bounds and a trailing send action.
 - [TokenSearchField](./token-search-field.md) — Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
 - [ResizableRegion](./resize.md) — Pointer and keyboard-operable split region with a customizable handle icon.
 - [Select](./select.md) — Choose one or more controlled values, keep unavailable choices visible, and optionally select all enabled choices or clear a multiple selection.
@@ -73,7 +74,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [AnchoredSurface](./anchored-surface.md) — Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
 - [Feedback](./feedback.md) — Banners, empty states, and labeled progress.
 - [StateBanner](./state-banner.md) — Present persistent inline feedback or attractive non-status emphasis with a named semantic tone.
-- [CornerStatus](./corner-status.md) — Show ongoing app-level progress such as "Loading…" or "Updating tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
+- [CornerStatus](./corner-status.md) — Show ongoing app-level progress such as "Loading…" or "Updating Tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
 - [EdgeActivityIndicator](./edge-activity-indicator.md) — Signal ambient background activity (server work, sync) along the top edge of the viewport without allocating layout or taking the pointer, with Kerf-owned motion and reduced-motion handling.
 - [EmptyState](./empty-state.md) — Actionable empty and busy content states.
 - [LoadingSpinner](./loading-spinner.md) — Meaningfully labeled or decorative progress.
@@ -172,13 +173,13 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 
 ## Kerf UI — Recipes
 
-- [Desktop application shell](./recipe-app-shell.md) — App bar above a Workbench with resizable navigation and inspector rails, relocated rail toggles, narrow-container overlays, and explicit pane scroll owners.
-- [Navigation sidebar](./recipe-navigation-sidebar.md) — Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.
-- [Workspace header](./recipe-workspace-header.md) — Page identity with primary, secondary, and overflow actions that relocate at narrow widths.
+- [Desktop Application Shell](./recipe-app-shell.md) — App bar above a Workbench with resizable navigation and inspector rails, relocated rail toggles, narrow-container overlays, and explicit pane scroll owners.
+- [Navigation Sidebar](./recipe-navigation-sidebar.md) — Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.
+- [Workspace Header](./recipe-workspace-header.md) — Page identity with primary, secondary, and overflow actions that relocate at narrow widths.
 - [List-detail dialog](./recipe-list-detail-dialog.md) — Production modal laid out as a workbench: a full-height SplitView list sidebar with its own toolbar beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.
-- [Composer form](./recipe-composer-form.md) — One visible publishing-form surface with Toolbar heading hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.
-- [List workspace states](./recipe-list-workspace-states.md) — Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.
-- [Compact toolbar choices and actions](./recipe-compact-toolbar.md) — A compact toolbar that distinguishes grouped commands, a visible exclusive choice, a longer Select, and one ordinary action.
-- [Navigation stack](./recipe-navigation-stack.md) — A push/pop navigation stack drill-down with animated slides and a live device class.
-- [Loading inspector](./recipe-loading-inspector.md) — A record inspector whose per-record values load asynchronously — every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.
-- [Collapsible sidebar](./recipe-collapsible-sidebar.md) — A mini app frame whose left navigation rail and bottom activity drawer are standalone CollapsiblePanels driven by wireSidebar: per-side collapse/expand toggles, focus move-in and restore, a dismissable compact overlay, and per-panel persistence.
+- [Composer Form](./recipe-composer-form.md) — One visible publishing-form surface with Toolbar heading hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.
+- [List Workspace States](./recipe-list-workspace-states.md) — Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.
+- [Compact Toolbar Choices and Actions](./recipe-compact-toolbar.md) — A compact toolbar that distinguishes grouped commands, a visible exclusive choice, a longer Select, and one ordinary action.
+- [Navigation Stack](./recipe-navigation-stack.md) — A push/pop navigation stack drill-down with animated slides and a live device class.
+- [Loading Inspector](./recipe-loading-inspector.md) — A record inspector whose per-record values load asynchronously — every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.
+- [Collapsible Sidebar](./recipe-collapsible-sidebar.md) — A mini app frame whose left navigation rail and bottom activity drawer are standalone CollapsiblePanels driven by wireSidebar: per-side collapse/expand toggles, focus move-in and restore, a dismissable compact overlay, and per-panel persistence.

package/ai/components/anchored-surface.md

@@ -37,6 +37,7 @@ Exact prop names and types: [`@kerfjs/ui/anchored-surface`](../public-api-signat
 - pointer anchor
 - top or bottom placement
 - modal-dialog host
+- tone: 'dark' (the inverse tone of a dark ToolbarControlGroup, for popups anchored to media chrome)
 
 ## Composition
 
@@ -71,6 +72,18 @@ const handle = openAnchoredSurface(button, () => <HelpPanel />, {
 // Close from the app's action handler: handle.close();
 ```
 
+### Popup anchored to dark media chrome
+
+tone: 'dark' matches a ToolbarControlGroup tone="dark": the surface takes the opposite of the anchor's color scheme (openAnchoredSurfaceAt reads it from point.context) and follows a live OS-preference or ancestor theme switch while open, so its content inherits the inverse text, border, and focus colors without overrides.
+
+```tsx
+openAnchoredSurface(volumeButton, () => <VolumeControls />, {
+  label: 'Volume',
+  tone: 'dark',
+  placement: 'top',
+});
+```
+
 ## Styling boundary
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.

package/ai/components/application-tabs.md

@@ -1,4 +1,4 @@
-# Application tabs
+# Application Tabs
 
 <!-- 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/chip.md

@@ -4,18 +4,20 @@
 
 `@kerfjs/ui:chip` · Kerf UI · component · Foundation
 
-A short tag with semantic tone and an optional accessible remove button, including compact and disabled variants.
+A short tag with semantic or inherited tone, an optional accessible remove button, or a native link and download form, including compact and disabled variants.
 
 ## When to use
 
-Render removable tags without application rules on Web Awesome internals.
+Render removable tags and file or link chips without application rules on Web Awesome internals or anchor chrome.
 
 - Show a short tag that the application can remove through a delegated action, including a compact or disabled tag.
+- Show a downloadable file or a short link with chip geometry, such as the referenced files of a chat message; set tone inherit inside a brand-loud or neutral ContentItem bubble.
 
 **Not when:**
 
 - Use Badge for non-interactive status and count metadata.
 - Do not use the remove button without a specific accessible name.
+- Use ListItemLink for a navigation row and ToolbarActionLink for a toolbar link.
 
 ## Imports
 
@@ -29,11 +31,11 @@ Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#k
 
 **Variants (configure, do not restyle):**
 
-- neutral, info, pop, success, warning, or danger tone
+- neutral, info, pop, success, warning, danger, or inherit tone
 - quiet, solid, or outline appearance
 - pill or rounded shape
 - compact or default size
-- removable or plain, enabled or disabled
+- removable, link, or plain, enabled or disabled
 
 ## Composition
 
@@ -43,7 +45,7 @@ Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#k
 
 ## State and wiring
 
-**The app owns:** tag text and identity; remove action and list update; disabled policy.
+**The app owns:** tag text and identity; remove action and list update; link destination and download file name; disabled policy.
 
 No wiring helper.
 
@@ -54,6 +56,8 @@ Margin: none · border: self · padding: self (layout role: foundation). `self`
 ## Accessibility
 
 - 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.
 
 ## Styling boundary

package/ai/components/choice-chips.md

@@ -4,19 +4,20 @@
 
 `@kerfjs/ui:choice-chips` · Kerf UI · component · Controls
 
-An exclusive, wrapping set of separated pill chips backed by native radios, with optional leading color swatches or icons.
+A wrapping set of separated pill chips backed by native radios (one exclusive value) or, with multiple, native checkboxes (any number of values), with optional leading color swatches or icons.
 
 ## When to use
 
-Choose one value from a visible set too large for a segmented track, such as a color palette with labeled swatches.
+Choose one value, or with multiple any number of values, from a visible set too large for a segmented track, such as a color palette with labeled swatches or a set of annotation intents.
 
 - Expose one exclusive choice among several visible options that must wrap onto more rows, such as a labeled color palette with swatches.
+- Set multiple when the person may turn any number of visible, wrapping options on or off, such as label filters or annotation intents.
 
 **Not when:**
 
 - Use SegmentedControl for a few compact choices on one track.
-- Use Select when the choice list is long or space is tight.
-- Do not use it for removable tags (Chip) or for multiple selection.
+- Use Select when the choice list is long or space is tight; a multiple Select keeps a long multi-value list behind one trigger.
+- Do not use it for removable tags (Chip).
 
 **Alternatives:**
 
@@ -27,24 +28,30 @@ Choose one value from a visible set too large for a segmented track, such as a c
 ## Imports
 
 - JavaScript: `@kerfjs/ui/choice-chips` — exports `ChoiceChips`.
+- JavaScript: `@kerfjs/ui/css-values` — exports `fillColor`.
 - CSS: the browser build of `@kerfjs/ui/choice-chips` pulls its CSS automatically; import `@kerfjs/ui/choice-chips.css` manually only without the `browser` export condition.
 - Declared side effects: browser-condition-css.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/choice-chips`](../public-api-signatures-v1.md#kerfjsuichoice-chips) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/choice-chips`](../public-api-signatures-v1.md#kerfjsuichoice-chips), [`@kerfjs/ui/css-values`](../public-api-signatures-v1.md#kerfjsuicss-values) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
 - color swatch, transparent (struck-through) swatch, icon, or text-only choices
+- single (radios) or multiple (checkboxes) selection
 - default or compact size
 - disabled group or disabled choices
-- required
+- required (single selection only)
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `choices[].swatch`: color grammar; raw values: forbid; shorthands `transparent`; helpers `fillColor`, `uiColor`, `colorVar` — e.g. `swatch: fillColor("#3b82f6")`
 
 ## Composition
 
 - Parents: any.
-- Contexts: `wrapping-exclusive-choice`.
+- Contexts: `wrapping-exclusive-choice`, `wrapping-multiple-choice`.
 - Children: unrestricted.
 - Built from: [LucideIcon](./lucide-icon.md).
 
@@ -60,7 +67,7 @@ Margin: none · border: self · padding: self (layout role: controls). `self` me
 
 ## Accessibility
 
-- 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.
 
 ## Styling boundary

package/ai/components/collapsible-panel.md

@@ -21,7 +21,7 @@ Add one independently collapsible peripheral panel without adopting the complete
 **Alternatives:**
 
 - [Workbench](./workbench.md) (larger-composition) — Use Workbench when the central work area coordinates multiple peripheral panels.
-- [Collapsible sidebar](./recipe-collapsible-sidebar.md) (recipe) — Use the production recipe for collapse, restore, compact overlay, focus, and persistence ownership.
+- [Collapsible Sidebar](./recipe-collapsible-sidebar.md) (recipe) — Use the production recipe for collapse, restore, compact overlay, focus, and persistence ownership.
 
 ## Imports
 
@@ -71,6 +71,7 @@ Exact prop names and types: [`@kerfjs/ui/collapsible-panel`](../public-api-signa
 - `data-morph-preserve` on `kui-collapsible-panel__backdrop` (`wireSidebar`): Keeps the injected compact-overlay backdrop through the application's re-render; the helper creates and removes the backdrop itself.
 - `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
 
@@ -97,6 +98,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [LucideIcon](./lucide-icon.md), [Workbench](./workbench.md), [Collapsible sidebar](./recipe-collapsible-sidebar.md).
+- Components: [LucideIcon](./lucide-icon.md), [Workbench](./workbench.md), [Collapsible Sidebar](./recipe-collapsible-sidebar.md).
 - Docs: [`docs/collapsible-panel.md`](../../docs/collapsible-panel.md), [`docs/collapsible-panel.md#recipe-and-coverage`](../../docs/collapsible-panel.md#recipe-and-coverage).
 - UX catalog route: `?component=collapsible-panel`.

package/ai/components/composer.md

@@ -0,0 +1,83 @@
+# Composer
+
+<!-- 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`. -->
+
+`@kerfjs/ui:composer` · Kerf UI · component · Controls
+
+A raised chat or prompt composer: a framed message field that grows with its content above an action row with a hint and a send button.
+
+## When to use
+
+Write a chat message or prompt in a raised frame whose border turns brand while focus is within, with a field that grows between row bounds and a trailing send action.
+
+- Write a chat message, assistant prompt, or comment reply that is sent with a trailing action, especially in a DialogSurface floating footer over a transcript.
+
+**Not when:**
+
+- Use wa-textarea with a FieldLabel for an ordinary form field that is submitted with the rest of a form.
+- Do not wrap it in another framed ContentItem or card; it owns its frame, padding, and shadow.
+
+**Alternatives:**
+
+- [Textarea](./wa-textarea.md) (prefer-over) — Use Composer instead of a wa-textarea and a button in app-styled chrome for a chat or prompt composer; it owns the raised frame, focus-within border, auto-grow, and action row.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/composer` — exports `Composer`, `wireComposers`.
+- CSS: the browser build of `@kerfjs/ui/composer` pulls its CSS automatically; import `@kerfjs/ui/composer.css` manually only without the `browser` export condition.
+- Wiring: `wireComposers` from `@kerfjs/ui/wire-composers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/composer`](../public-api-signatures-v1.md#kerfjsuicomposer), [`@kerfjs/ui/wire-composers`](../public-api-signatures-v1.md#kerfjsuiwire-composers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- minRows and maxRows bounds for the growing field
+- optional hint, described by the field when an id is given
+- disabled field
+- submitOnEnter: Enter or Cmd/Ctrl+Enter activates the first trailing action, Shift+Enter inserts a newline (with wireComposers)
+- slotted into a DialogSurface floating footer
+
+## Composition
+
+- Parents: any.
+- Contexts: `chat-composer`, `dialog-floating-footer`.
+- Children: unrestricted.
+- Built from: [Text](./text.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `actions` — JSX prop `actions`; accepts `KerfUiContent`; at least 1.
+
+## State and wiring
+
+- value — controlled
+
+**Wiring:** `wireComposers` is optional.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- 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.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-composer`.
+
+Never put `kui-composer` on an element you write; render `Composer` instead (`KUI-L103`).
+
+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: [Text](./text.md), [Textarea](./wa-textarea.md).
+- Docs: [`docs/composer.md`](../../docs/composer.md), [`docs/accessibility.md#composer`](../../docs/accessibility.md#composer).
+- UX catalog route: `?component=composer`.

package/ai/components/content-item.md

@@ -27,7 +27,7 @@ Render one self-contained .kui-content child that owns its 8px inline margin, re
 
 - [ListInsetText](./list-inset-text.md) (nearest) — Use ListInsetText when bare text only needs to align with neighboring content items.
 - [SunkenPanel](./sunken-panel.md) (nearest) — Use SunkenPanel for a lowered, filled surface around a vertical stack.
-- [Application layout](./layout.md) (composes-with) — Place ContentItem children in a Pane or .kui-content stack, which owns the 24px major rhythm.
+- [Application Layout](./layout.md) (composes-with) — Place ContentItem children in a Pane or .kui-content stack, which owns the 24px major rhythm.
 
 ## Imports
 
@@ -93,6 +93,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [ListInsetText](./list-inset-text.md), [SunkenPanel](./sunken-panel.md), [Application layout](./layout.md).
+- Components: [ListInsetText](./list-inset-text.md), [SunkenPanel](./sunken-panel.md), [Application Layout](./layout.md).
 - Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/layout.md#content-items`](../../docs/layout.md#content-items).
 - UX catalog route: `?component=content-item`.

package/ai/components/corner-status.md

@@ -8,7 +8,7 @@ Non-dismissible app-level status pinned to a viewport corner in the top layer, h
 
 ## When to use
 
-Show ongoing app-level progress such as "Loading…" or "Updating tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
+Show ongoing app-level progress such as "Loading…" or "Updating Tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
 
 - Show ongoing app-level progress or status that has no better home beside the affected work and must stay visible until the work ends.
 

package/ai/components/document-baseline.md

@@ -1,4 +1,4 @@
-# Document baseline
+# Document Baseline
 
 <!-- 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`. -->
 
@@ -20,7 +20,7 @@ Let an application opt into Kerf UI-owned document defaults and a definite full-
 
 **Alternatives:**
 
-- [Foundation tokens](./foundation.md) (composes-with) — Import the foundation tokens the baseline reads; the baseline itself adds only global document selectors.
+- [Foundation Tokens](./foundation.md) (composes-with) — Import the foundation tokens the baseline reads; the baseline itself adds only global document selectors.
 
 ## Imports
 
@@ -72,6 +72,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Foundation tokens](./foundation.md).
+- Components: [Foundation Tokens](./foundation.md).
 - Docs: [`docs/document-baseline.md`](../../docs/document-baseline.md).
 - UX catalog route: `?component=document-baseline`.

package/ai/components/foundation.md

@@ -1,4 +1,4 @@
-# Foundation tokens
+# Foundation Tokens
 
 <!-- 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`. -->
 
@@ -55,7 +55,7 @@ Margin: none · border: none · padding: none (layout role: foundation). `self`
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public tokens it reads: `--kui-font-sans`, `--kui-font-mono`, `--kui-font-2xs`, `--kui-font-xs`, `--kui-font-s`, `--kui-font-m`, `--kui-font-l`, `--kui-font-xl`, `--kui-font-2xl`, `--kui-font-weight-semibold`, `--kui-space-none`, `--kui-space-2xs`, `--kui-space-xs`, `--kui-space-s`, `--kui-space-m`, `--kui-space-l`, `--kui-space-xl`, `--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`, `--kui-layout-inline-margin`, `--kui-layout-item-border-width`, `--kui-layout-item-padding`, `--kui-layout-item-gap`, `--kui-layout-content-gap`, `--kui-layout-control-gap`, `--kui-layout-metadata-gap`, `--kui-layout-highlight-inset`, `--kui-layout-rounded-radius`, `--kui-layout-pill-radius`, `--kui-toolbar-group-inner-size`, `--kui-toolbar-group-size`, `--kui-toolbar-gap`, `--kui-safe-area-block-start`, `--kui-safe-area-block-end`, `--kui-safe-area-inline-start`, `--kui-safe-area-inline-end`, `--kui-radius-s`, `--kui-radius-m`, `--kui-radius-l`, `--kui-radius-circle`, `--kui-radius-pill`, `--kui-disclosure-icon-scale`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-surface-lowered`, `--kui-sunken-texture`, `--kui-sunken-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-text-link`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-loud`, `--kui-color-brand-on-quiet`, `--kui-color-brand-on-normal`, `--kui-color-brand-on-loud`, `--kui-color-brand-on-fill`, `--kui-color-pop-fill-loud`, `--kui-color-pop-fill-quiet`, `--kui-color-pop-fill-normal`, `--kui-color-pop-border-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-border-loud`, `--kui-color-pop-on-quiet`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-loud`, `--kui-color-pop-on-fill`, `--kui-color-success-fill-loud`, `--kui-color-success-fill-quiet`, `--kui-color-success-fill-normal`, `--kui-color-success-border-quiet`, `--kui-color-success-border-normal`, `--kui-color-success-border-loud`, `--kui-color-success-on-quiet`, `--kui-color-success-on-normal`, `--kui-color-success-on-loud`, `--kui-color-success-on-fill`, `--kui-color-warning-fill-loud`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-fill-normal`, `--kui-color-warning-border-quiet`, `--kui-color-warning-border-normal`, `--kui-color-warning-border-loud`, `--kui-color-warning-on-quiet`, `--kui-color-warning-on-normal`, `--kui-color-warning-on-loud`, `--kui-color-warning-on-fill`, `--kui-color-danger-fill-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-fill-normal`, `--kui-color-danger-border-quiet`, `--kui-color-danger-border-normal`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-color-danger-on-normal`, `--kui-color-danger-on-loud`, `--kui-color-danger-on-fill`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-shadow-l`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-font-sans`, `--kui-font-mono`, `--kui-font-2xs`, `--kui-font-xs`, `--kui-font-s`, `--kui-font-m`, `--kui-font-l`, `--kui-font-xl`, `--kui-font-2xl`, `--kui-font-weight-semibold`, `--kui-space-none`, `--kui-space-2xs`, `--kui-space-xs`, `--kui-space-s`, `--kui-space-m`, `--kui-space-l`, `--kui-space-xl`, `--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`, `--kui-layout-inline-margin`, `--kui-layout-item-border-width`, `--kui-layout-item-padding`, `--kui-layout-item-gap`, `--kui-layout-content-gap`, `--kui-layout-control-gap`, `--kui-layout-metadata-gap`, `--kui-layout-highlight-inset`, `--kui-layout-rounded-radius`, `--kui-layout-pill-radius`, `--kui-toolbar-group-inner-size`, `--kui-toolbar-group-size`, `--kui-toolbar-gap`, `--kui-safe-area-block-start`, `--kui-safe-area-block-end`, `--kui-safe-area-inline-start`, `--kui-safe-area-inline-end`, `--kui-radius-s`, `--kui-radius-m`, `--kui-radius-l`, `--kui-radius-circle`, `--kui-radius-pill`, `--kui-disclosure-icon-scale`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-surface-lowered`, `--kui-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`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-loud`, `--kui-color-brand-on-quiet`, `--kui-color-brand-on-normal`, `--kui-color-brand-on-loud`, `--kui-color-brand-on-fill`, `--kui-color-pop-fill-loud`, `--kui-color-pop-fill-quiet`, `--kui-color-pop-fill-normal`, `--kui-color-pop-border-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-border-loud`, `--kui-color-pop-on-quiet`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-loud`, `--kui-color-pop-on-fill`, `--kui-color-success-fill-loud`, `--kui-color-success-fill-quiet`, `--kui-color-success-fill-normal`, `--kui-color-success-border-quiet`, `--kui-color-success-border-normal`, `--kui-color-success-border-loud`, `--kui-color-success-on-quiet`, `--kui-color-success-on-normal`, `--kui-color-success-on-loud`, `--kui-color-success-on-fill`, `--kui-color-warning-fill-loud`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-fill-normal`, `--kui-color-warning-border-quiet`, `--kui-color-warning-border-normal`, `--kui-color-warning-border-loud`, `--kui-color-warning-on-quiet`, `--kui-color-warning-on-normal`, `--kui-color-warning-on-loud`, `--kui-color-warning-on-fill`, `--kui-color-danger-fill-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-fill-normal`, `--kui-color-danger-border-quiet`, `--kui-color-danger-border-normal`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-color-danger-on-normal`, `--kui-color-danger-on-loud`, `--kui-color-danger-on-fill`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-shadow-l`. 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/layout.md

@@ -1,4 +1,4 @@
-# Application layout
+# Application Layout
 
 <!-- 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/list-action-row.md

@@ -12,6 +12,7 @@ Keep a selectable primary row action and an independently named trailing action
 
 - A navigation or item row needs both a primary selectable action and an independently focusable trailing action.
 - A command row needs a trailing "…" overflow menu (trailingMenu), optionally also opened at the pointer from the row's contextmenu with openPopupMenuAt.
+- A settings or command row identifies each entry by a colored icon tile (iconTile) instead of a bare glyph.
 
 **Not when:**
 
@@ -51,10 +52,13 @@ Exact prop names and types: [`@kerfjs/ui/list-action-row`](../public-api-signatu
 - before, after, or paired group divider
 - position-aware divided-list corners: flat wherever a divider line (this row's or a neighbor's) meets the edge
 - draggable row with dragging and drop-before / drop-after insertion states
+- filled leading icon tile (iconTile): a quiet tone preset (neutral, brand, success, warning, danger) or an application fill with an optional foreground; a 32px rounded tile holding an 18px glyph
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
 
 - `style`: declarations grammar; raw values: forbid — e.g. `className="app-row"`
+- `iconTile.color`: color grammar; raw values: forbid; helpers `fillColor`, `uiColor`, `colorVar` — e.g. `iconTile={{ color: fillColor("#e5484d") }}`
+- `iconTile.foreground`: color grammar; raw values: forbid; helpers `uiColor`, `foregroundColorVar`, `foregroundColor` — e.g. `iconTile={{ color: fillColor("#e5484d"), foreground: foregroundColor("white") }}`
 
 ## Composition
 
@@ -93,7 +97,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-list-action-row`, `kui-list-action-row__icon`, `kui-list-action-row__label`, `kui-list-action-row__primary-label`, `kui-list-action-row__description`, `kui-list-action-row__status`, `kui-list-action-row__primary`, `kui-list-action-row__trailing-action` on an element you write; render `ListActionRow` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-brand-border-loud`, `--kui-color-brand-border-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-quiet`, `--kui-focus-ring`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`, `--kui-radius-pill`, `--kui-list-action-row-background`, `--kui-list-action-row-border`, `--kui-list-action-row-color`, `--kui-list-action-row-dragging-opacity`, `--kui-list-action-row-drop-indicator`, `--kui-list-action-row-drop-indicator-width`, `--kui-list-action-row-hover-background`, `--kui-list-action-row-hover-border`, `--kui-list-action-row-selected-background`, `--kui-list-action-row-selected-border`, `--kui-list-action-row-selected-color`, `--kui-list-action-row-trailing-hover-background`, `--kui-list-group-divider-color`, `--kui-font-xs`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-brand-border-loud`, `--kui-color-brand-border-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-quiet`, `--kui-focus-ring`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`, `--kui-radius-pill`, `--kui-list-action-row-background`, `--kui-list-action-row-border`, `--kui-list-action-row-color`, `--kui-list-action-row-dragging-opacity`, `--kui-list-action-row-drop-indicator`, `--kui-list-action-row-drop-indicator-width`, `--kui-list-action-row-hover-background`, `--kui-list-action-row-hover-border`, `--kui-list-action-row-selected-background`, `--kui-list-action-row-selected-border`, `--kui-list-action-row-selected-color`, `--kui-list-action-row-trailing-hover-background`, `--kui-list-group-divider-color`, `--kui-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`. 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/list-item.md

@@ -11,6 +11,7 @@ Configurable native-button action rows and native-anchor navigation rows with st
 Selectable, disabled, trailing, and multiline action or link rows.
 
 - Render a selectable, disabled, trailing, or multiline sidebar action row whose descendants must remain clipped to the rounded row boundary; use ListItemLink when the destination has an href and needs native link activation.
+- A settings or command row identifies each entry by a colored icon tile (iconTile) instead of a bare glyph.
 
 **Not when:**
 
@@ -52,10 +53,13 @@ Exact prop names and types: [`@kerfjs/ui/list-item`](../public-api-signatures-v1
 - busy while retaining content
 - before, after, or paired group divider
 - position-aware divided-list corners: flat wherever a divider line (this row's or a neighbor's) meets the edge
+- filled leading icon tile (iconTile): a quiet tone preset (neutral, brand, success, warning, danger) or an application fill with an optional foreground; a 32px rounded tile holding an 18px glyph
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
 
 - `style`: declarations grammar; raw values: forbid — e.g. `className="app-row"`
+- `iconTile.color`: color grammar; raw values: forbid; helpers `fillColor`, `uiColor`, `colorVar` — e.g. `iconTile={{ color: fillColor("#e5484d") }}`
+- `iconTile.foreground`: color grammar; raw values: forbid; helpers `uiColor`, `foregroundColorVar`, `foregroundColor` — e.g. `iconTile={{ color: fillColor("#e5484d"), foreground: foregroundColor("white") }}`
 
 ## Composition
 
@@ -93,7 +97,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-list-item`, `kui-list-item__icon`, `kui-list-item__label`, `kui-list-item__primary-label`, `kui-list-item__description`, `kui-list-item__status`, `kui-list-item__trailing` on an element you write; render `ListItem` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-brand-border-loud`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-radius-pill`, `--kui-focus-ring`, `--kui-list-item-color`, `--kui-list-item-background`, `--kui-list-item-align-items`, `--kui-list-item-border-width`, `--kui-list-item-border`, `--kui-list-item-columns`, `--kui-list-item-drag-target-background`, `--kui-list-item-drag-target-outline`, `--kui-list-item-drag-target-outline-offset`, `--kui-list-item-dragging-opacity`, `--kui-list-item-drop-indicator`, `--kui-list-item-drop-indicator-width`, `--kui-list-item-gap`, `--kui-list-item-hover-background`, `--kui-list-item-hover-border`, `--kui-list-item-icon-color`, `--kui-list-item-icon-size`, `--kui-list-item-label-max-width`, `--kui-list-item-label-weight`, `--kui-list-item-min-height`, `--kui-list-item-padding-block`, `--kui-list-item-padding-inline`, `--kui-list-item-radius`, `--kui-list-item-selected-background`, `--kui-list-item-selected-border`, `--kui-list-item-selected-color`, `--kui-list-item-trailing-color`, `--kui-list-group-divider-color`, `--kui-font-xs`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-brand-border-loud`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-radius-pill`, `--kui-focus-ring`, `--kui-list-item-color`, `--kui-list-item-background`, `--kui-list-item-align-items`, `--kui-list-item-border-width`, `--kui-list-item-border`, `--kui-list-item-columns`, `--kui-list-item-drag-target-background`, `--kui-list-item-drag-target-outline`, `--kui-list-item-drag-target-outline-offset`, `--kui-list-item-dragging-opacity`, `--kui-list-item-drop-indicator`, `--kui-list-item-drop-indicator-width`, `--kui-list-item-gap`, `--kui-list-item-hover-background`, `--kui-list-item-hover-border`, `--kui-list-item-icon-color`, `--kui-list-item-icon-size`, `--kui-list-item-label-max-width`, `--kui-list-item-label-weight`, `--kui-list-item-min-height`, `--kui-list-item-padding-block`, `--kui-list-item-padding-inline`, `--kui-list-item-radius`, `--kui-list-item-selected-background`, `--kui-list-item-selected-border`, `--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-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`. 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/list.md

@@ -17,6 +17,9 @@ Standardize vertical component layout, optional physical-side text/control inset
 - Apply the standard text or control inset to selected physical sides without an application wrapper.
 - Align children horizontally or distribute them vertically with the same physical alignment vocabulary as Row.
 - Use selectionMode="multiple" and ariaLabel to group selectable rich ContentItem rows in a multi-select grid.
+- Use scrollClearance on the scrollable List that reaches an edge overlaid by chrome (a DialogSurface floating footer) so rows scroll visibly beneath it while the first and last rows still rest clear of it.
+- Render a bounded, framed result picker of ListItem rows (search results, duplicate candidates) with scrollable, frame, and typed maxHeight/minHeight instead of an app-owned bordered scroller.
+- Call wireListFocusScroll(root) once when keyboard users move focus through a scrollable List's rows, so Firefox and Safari bring a partly hidden focused row and its ring fully into view as Chromium does.
 
 **Not when:**
 
@@ -28,13 +31,15 @@ Standardize vertical component layout, optional physical-side text/control inset
 
 - JavaScript: `@kerfjs/ui/list` — exports `List`.
 - JavaScript: `@kerfjs/ui/css-values` — exports `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `plus`, `calc`, `flex`.
+- JavaScript: `@kerfjs/ui/wire-list-focus-scroll` — exports `wireListFocusScroll`.
 - CSS: the browser build of `@kerfjs/ui/list` pulls its CSS automatically; import `@kerfjs/ui/list.css` manually only without the `browser` export condition.
 - Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Wiring: `wireListFocusScroll` from `@kerfjs/ui/wire-list-focus-scroll` (optional).
 - Declared side effects: browser-condition-css.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#kerfjsuilist), [`@kerfjs/ui/css-values`](../public-api-signatures-v1.md#kerfjsuicss-values), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#kerfjsuilist), [`@kerfjs/ui/css-values`](../public-api-signatures-v1.md#kerfjsuicss-values), [`@kerfjs/ui/wire-list-focus-scroll`](../public-api-signatures-v1.md#kerfjsuiwire-list-focus-scroll), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
@@ -44,6 +49,9 @@ Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#k
 - typed CssLength gap
 - boolean, finite-keyword, or typed CssFlex flex
 - scrollable
+- scrollClearance block-start, block-end, or both: clears overlaying chrome inside the scroll area
+- frame: 1px neutral border, control radius, and a 4px focus-ring-safe inset
+- typed CssLength maxHeight and minHeight bounds
 - base or raised solid surface
 - document reading inset
 - left/center/right/full horizontal alignment
@@ -59,6 +67,8 @@ Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#k
 
 - `gap`: length grammar; raw values: forbid; shorthands `none`, `2xs`, `xs`, `m`, `l`; exceptional (justify) `s`, `xl`; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `gap="xs"`
 - `flex`: flex grammar; raw values: forbid; shorthands `none`, `auto`, `initial`; helpers `flex` — e.g. `flex="none"`
+- `maxHeight`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `maxHeight={rem(14)}`
+- `minHeight`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `minHeight={rem(4.25)}`
 
 ## Composition
 
@@ -69,26 +79,32 @@ Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#k
 
 ## State and wiring
 
-**The app owns:** child semantics and content; the bounded height needed for scrolling; typed gap, flex, alignment, and divider choices; the accessible label and selection state of a multi-select grid.
+**The app owns:** child semantics and content; the bounded height needed for scrolling; typed gap, flex, alignment, and divider choices; the accessible label and selection state of a multi-select grid; which one scroller opts into scroll clearance (the one reaching the covered edge); the result picker bounds (maxHeight/minHeight) and its rows.
 
-**Wiring:** `wireScrollDividers` is optional.
+**Wiring:** `wireScrollDividers`, `wireListFocusScroll` is optional.
 
 **Wiring-owned state attributes** — never render, remove, or branch on these as app state:
 
 - `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 List 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.
 
 ## Geometry
 
 Margin: none · border: conditional · padding: conditional (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
 - 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.
 
 ## Accessibility
 
 - 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.
+- 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.
 
 ## Styling boundary