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

package/docs/accessibility.md

@@ -18,7 +18,7 @@ These are normative contracts for package components and consuming applications.
 - Interactive `ContentItem` cards are keyboard reachable. Set `selectionMode="toggle"` for a pressed button, `selectionMode="single"` for an option inside a listbox, or `selectionMode="multiple"` for a selectable row with a gridcell that can contain native controls. Place multiple-mode rows inside a labeled `List` or `Grid` with `selectionMode="multiple"`; the app owns the selection set and range gestures. Wire `wireContentItems` once so Enter and Space on the card activate its delegated action without activating it from a nested control. Disabled cards expose `aria-disabled` and leave the Tab order.
 - An unlabeled `Skeleton` (including the value slots a component's `placeholder` prop renders) is decorative loading chrome: it is `aria-hidden`, conveys no information a user needs to act on, and is deliberately exempt from the WCAG 3:1 non-text-contrast target. Inside a solid `Badge` it stays subtle (about 2.1–4.4:1 in light, 2.4–2.8:1 in dark, depending on tone); `tests/browser/tone-contrast.spec.ts` holds those values as a regression floor rather than an accessibility threshold. Announce loading through a labeled `Skeleton`, `LoadingSpinner`, or `aria-busy` on the owning region, never through the skeleton's visibility.
 - `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure. Its optional `badge` is persistent inline status/count content beside the title and is announced as part of the banner; keep it terse and do not rely on color alone for its meaning.
-- A removable `Chip` has a native button with a specific `removeLabel`, such as "Remove Urgent tag". The button is absent for a plain chip and disabled for a disabled chip. Its leading `icon` is decorative; the visible label names the tag. `truncate` retains the full plain-text label as a native tooltip. Tag text remains visible because tone does not convey meaning alone.
+- A removable `Chip` has a native button with a specific `removeLabel`, such as "Remove Urgent tag". The button is absent for a plain chip and disabled for a disabled chip. Its leading `icon` is decorative; the visible label names the tag. `truncate` retains the full plain-text label as a native tooltip. Tag text remains visible because tone does not convey meaning alone. A link `Chip` (`href`) is a native anchor named by its visible label, with no remove button; `external` adds `target="_blank"`, `rel="noopener noreferrer"`, and an "(opens in new tab)" name suffix for a text label, and a disabled link chip drops `href`, sets `aria-disabled`, and leaves the tab order. `tone="inherit"` paints no fill, so its label keeps the surrounding text's contrast (a brand-loud bubble's white text included), and its focus ring is drawn in the surrounding foreground so it stays visible on a brand-colored surface.
 - `EmptyState` reports busy state through `aria-busy` and never relies on an illustration as its label.
 - `Select` follows the Web Awesome host's standard `input`/`change` events. Application tests verify the live `value`, focus, and events—not attributes alone. Its decorative option icons and value-dependent selected content remain present after controlled rerenders, so the visible choice does not silently lose its non-text cue.
 - `DisclosureArrow` is an 18px root-scaled decorative visual by default, not an interaction target. Its owning native control supplies a stable accessible name, pointer and keyboard interaction, and `aria-expanded`; multiple arrows keep independently controlled state. Consumers may resize it with the typed `size` prop without changing that ownership. Configured directions animate over the shortest path; a 180-degree closed-to-open tie uses counterclockwise rotation.
@@ -220,7 +220,18 @@ name from its content and ignores an `aria-label` on the host, so an icon-only
 trigger requires `label`, which renders as visually hidden text inside the
 button; a trigger with visible `text` is named by that text. An icon-only
 trigger also shows its `label` as an `aria-hidden` help tag on hover and
-keyboard focus (see [Help tags on icon-only triggers](#help-tags-on-icon-only-triggers)). Group headings
+keyboard focus (see [Help tags on icon-only triggers](#help-tags-on-icon-only-triggers)).
+The open menu carries that same name. Web Awesome renders the `role="menu"`
+panel inside the dropdown's shadow root, where no ID reference can reach the
+trigger (the context anchor is `aria-hidden` light DOM, and a button trigger's
+real `<button>` sits in `wa-button`'s own shadow root). So `PopupMenu` renders
+the name it already knows (a context or icon-only `label`, or the visible
+`text`) as `data-menu-label` on the dropdown, and the register copies it to the
+panel as `aria-label` on first render and on every open. A submenu panel shares
+a shadow root with its parent item's label and is `aria-labelledby` it, so it
+is announced as, for example, "More Actions, menu".
+`tests/browser/popup-menu-accessible-name.spec.ts` finds each panel with
+`getByRole('menu', { name })` in Chromium, Firefox, and WebKit. Group headings
 render as the same uppercase group titles a grouped `Select` shows, and dividers
 are presentational. A keyboard-focused item is the menu's current row, painted
 with the Select's current-option fill rather than a second focus ring inside the
@@ -466,6 +477,41 @@ focused radio, and the checked pill adds a second pixel of border so the
 selection does not rely on hue alone; forced-colors mode paints it with
 `Highlight`.
 
+With `multiple`, the group renders `role="group"` with the same naming, and
+each choice is a native `<input type="checkbox">` inside its pill. Every pill
+is its own Tab stop, Space toggles it, assistive technology reads its native
+checked state, and every checked box submits its value under `name`
+(`FormData.getAll(name)`). Native `required` on a checkbox demands that one
+box, so a multiple group takes no `required`; validate an "at least one" rule
+in the application. Every chip color is a theme token resolved through
+`light-dark()`, so inside a dark appearance scope (`.wa-dark`, `.wa-invert`,
+or any `color-scheme: dark` ancestor) the pills, labels, checked tint, and
+focus ring read on inverse chrome without overrides.
+
+## Composer
+
+`Composer`'s message field is a native `<textarea>` named by `label`
+(`aria-label`, title style). With an `id`, the `hint` renders with the id
+`<id>-hint` and becomes the field's `aria-describedby`; without an `id`, the
+hint is visible only. The field draws no border or outline of its own: the
+frame is its boundary, and while focus is anywhere within the composer the
+frame's border turns brand (`Highlight` in forced-colors mode, with a 2px
+outline). Each trailing action keeps its own name and focus ring. `disabled`
+disables the field only; the app disables its actions. Sending and
+announcing a sent message stay with the app.
+
+With `submitOnEnter` and `wireComposers`, the field carries
+`aria-keyshortcuts="Enter"`, so assistive technology announces the shortcut.
+Enter and Cmd/Ctrl+Enter activate the first trailing action, the same control
+a pointer or Tab-and-Space user reaches; Shift+Enter inserts a newline. An
+Enter that commits an IME composition (`isComposing`, keyCode 229, or between
+`compositionstart` and `compositionend`) is left to the input method, so
+people composing Japanese, Chinese, or Korean text never send a half-written
+message. An empty or whitespace-only message, an auto-repeating key, a
+disabled field, or a disabled, loading, or `aria-disabled` action sends
+nothing. A visible hint may also state the shortcut when the audience may not
+expect it.
+
 ## TokenSearchField
 
 Use `presentation="form-field"` when a structured search query sits beside
@@ -481,7 +527,10 @@ form-control tokens, so the two controls read as one form.
 
 `TokenSearchField` exposes the editable surface as a named `searchbox`. Each
 chip is atomic (`contenteditable="false"`) and contains separately named edit
-and remove buttons; the clear action is also named. Disabled fields publish
+and remove buttons; the clear action is also named. A `trailingAction` is a
+named button whose `label` is also its tooltip; a help toggle sets `expanded`
+(`aria-expanded`, with `haspopup` and `controls` for the surface it opens) and
+an on/off toggle sets `pressed` (`aria-pressed`). Disabled fields publish
 `aria-disabled` and stop editing without hiding the current expression. The
 application owns query parsing and must announce result-count or loading
 changes separately when that feedback is useful. Use `readTokenSearchField()`
@@ -612,6 +661,86 @@ opened it, else the restore control, else a control whose `aria-controls` names
 panel; an open overlay panel takes focus and keeps Tab inside it (the ARIA dialog
 pattern). See [`workbench.md`](workbench.md).
 
+## Chrome material
+
+Translucent chrome, such as a `Pane` header with
+`headerPresentation="overlay"`, a `NavStack` top bar with
+`chromePresentation="overlay"`, or a `NavStack` bottom toolbar with
+`bottomToolbarPresentation="overlay"`, or a `TabNavigator` tab bar with
+`barPresentation="overlay"`, paints `--kui-chrome-material`: the surface at
+80% opacity behind a blur-and-saturate backdrop filter
+(`--kui-chrome-material-filter`). Content scrolls visibly beneath it, so the
+backdrop under its text is not a fixed color. The contrast rule measures the
+worst case: the material composited over a solid black backdrop in the light
+theme and a solid white backdrop in the dark theme. The blur only averages the
+content, so it can never be darker or lighter than that.
+
+Chrome on a raised surface, such as a `DialogSurface` title bar with
+`headerPresentation="floating"`, paints `--kui-chrome-material-raised`
+instead: the raised surface at the same 80%, so the bar matches the dialog
+panel behind it. The same rule and fallbacks apply.
+
+- **Normal text and icons pass AA over any content.** `--kui-color-text`
+  measures about 10.5:1 (light) and 8.3:1 (dark) on that worst case, and
+  about 10.5:1 (light) and 6.7:1 (dark) over the raised material. 80% is
+  above the minimum opacity that keeps 4.5:1 there (about 55% light and 60%
+  dark). A theme that overrides `--kui-chrome-material` or
+  `--kui-chrome-material-raised` must keep its text at 4.5:1 or better
+  against the same backdrops.
+- **Quiet text does not, so `ToolbarText` lifts it.** `--kui-color-text-quiet`
+  falls to about 3.2:1 (light) and 4.1:1 (dark) over the worst case, and the
+  default-size title color to about 3.8:1 (light). Inside an overlay `Pane`
+  header or overlay `NavStack` chrome or bottom toolbar, or slotted as the `label` (or into
+  `header-actions`) of a `DialogSurface` floating header, an untoned
+  `ToolbarText` therefore takes
+  `--kui-color-text` for its title at every size, and its `description` mixes
+  the quiet color halfway toward the normal one, about 5.9:1 in both themes
+  (about 4.9:1 dark over the raised material). That keeps AA while the
+  description still reads as secondary. Controls lift the same way in an
+  overlay `Pane` header, overlay `NavStack` chrome or bottom toolbar, and a
+  `DialogSurface` floating header's `header-actions`: a default-tone
+  `ToolbarControlGroup`'s quiet control color over its own translucent fill
+  measures about 3.0:1 (light) and 3.5:1 (dark) over the worst case, so its
+  controls take `--kui-color-text` there. An overlay `TabNavigator` bar's
+  unselected labels lift halfway toward `--kui-color-text`, and its selected
+  label mixes 40% of it into the brand color: the plain brand color measured
+  about 3.2:1 (light) over the worst case. `wa-dialog`'s own close button is an
+  icon, held to the 3:1 non-text bar, and measures about 3.8:1 (light) and
+  4.1:1 (dark) over the raised material. Any other quiet copy you place in
+  overlay chrome yourself has no such lift; keep it in the content.
+- **The material turns opaque when transparency would hurt.** Under
+  `prefers-reduced-transparency: reduce` or `prefers-contrast: more`, and where
+  `backdrop-filter` is unsupported, it resolves to the opaque surface. In forced
+  colors, the header (or NavStack chrome) paints `Canvas` with a `CanvasText`
+  bottom edge, and an overlay NavStack bottom toolbar paints `Canvas` with a
+  `CanvasText` top edge, so content passing beneath it never shows through.
+
+`tests/browser/overlay-header.spec.ts` (Pane),
+`tests/browser/overlay-nav-stack.spec.ts` (NavStack top chrome),
+`tests/browser/overlay-nav-stack-bottom.spec.ts` (NavStack bottom toolbar,
+which also measures its description, a control, the top chrome's back
+control, and increased contrast), and
+`tests/browser/dialog-floating-header.spec.ts` (DialogSurface) measure the
+title over the material on both worst-case backdrops in Chromium, Firefox, and
+WebKit, and the Pane and DialogSurface specs also measure the description and
+a header control group (DialogSurface also its close button). In
+Chromium they also check the opaque fallbacks for reduced transparency and
+forced colors, and the Pane and DialogSurface specs check increased contrast.
+
+**Firefox and WebKit screenshots omit the blur.** In Playwright's Firefox and
+WebKit, `page.screenshot()` (headless or headed) shows the content beneath the
+material crisp, as if `backdrop-filter` did nothing. Stock Firefox's own
+`--headless --screenshot` does the same. The filter is still applied: a
+`recordVideo` frame of the same page in the same session, which records the
+compositor's output, shows the content blurred. Firefox and WebKit draw
+`backdrop-filter` only when compositing (WebRender in Firefox, Core Animation
+in WebKit), and their snapshot paths repaint the page without it. Chromium's
+screenshot shows the blur. Plain test pages with no kerf CSS behave the same
+way, so no ancestor style in these components is blocking the filter. When
+you review the blur in Firefox or WebKit, use a `recordVideo` frame, not a
+screenshot. A crisp screenshot is not a defect, and contrast is unaffected
+because the rule above already assumes no blur.
+
 ## Verification matrix
 
 For each changed component, inspect default, hover, focus, disabled, selected/pressed, busy/error, long-content, wide, narrow, light, dark, increased-contrast, reduced-motion, keyboard-only, and 200%-zoom states where applicable. DOM order must match reading and focus order, with no clipping or unreachable action.

package/docs/anchored-surface.md

@@ -23,10 +23,15 @@ focusable anchor on close (or the previously focused element for a nonfocusable
 anchor). Pass `initialFocus: false` for read-only
 help that leaves focus on its trigger. Escape and an outside press dismiss it;
 `dismiss`, `onDismiss`, and `outsideIgnore` can customize that behavior.
-`placement` (`bottom` or `top`), `align` (`start` or `end`), and `gap` feed the
-shared `kerfjs/overlay` positioning core: it flips vertically when the other
-side fits, clamps horizontally, and follows scroll and resize. Content taller
-than the viewport scrolls inside the surface.
+`placement` (`bottom` or `top`), `align` (`start` or `end`), `gap`, and
+`viewportMargin` feed the shared `kerfjs/overlay` positioning core: it flips
+vertically when the other side fits, keeps the surface `viewportMargin` (default
+8px) inside the viewport edges, and follows scroll and resize. The surface fits
+its height to the room beside the anchor: when neither side holds it, it opens
+on the roomier side, caps its height to that room, and scrolls its content.
+The room is exposed to the content as `--kui-anchored-surface-available-height`
+and refreshed on every reposition, so a tall help surface fits beside a field on
+a phone without application media queries or `max-height` overrides.
 
 ```tsx
 openAnchoredSurfaceAt(
@@ -52,6 +57,43 @@ Closing the anchor's modal dialog also closes the surface. Escape closes only
 the surface; the dialog beneath stays open. The temporary pointer anchor is
 removed when the surface closes.
 
+## Dark tone for media chrome
+
+A popup anchored to dark media chrome (a volume control in a
+`ToolbarControlGroup tone="dark"` over a video or image preview) passes
+`tone: 'dark'`:
+
+```tsx
+openAnchoredSurface(volumeButton, () => <VolumeControls />, {
+  label: 'Volume',
+  tone: 'dark',
+  placement: 'top',
+});
+```
+
+The tone is the same loud, inverse tone as a dark `ToolbarControlGroup` or
+`ToolbarText`: dark beside a light page and light beside a dark one, so the
+popup matches the group that opened it. When the surface opens it takes the
+opposite of the anchor's color scheme (an explicit `color-scheme` on the anchor
+or an ancestor wins; `light dark` follows the user's preference), and the
+surface is marked `data-tone="dark"`. Nothing else changes. Every semantic
+color token is a `light-dark()` pair, so the surface fill, border, and shadow,
+and the text, borders, and focus rings of the Kerf UI and Web Awesome
+components inside it (a `ListItem` mute row, a `wa-slider`), resolve to the
+other side by inheritance. The content needs no tone props and no overrides.
+Text and focus rings keep WCAG AA in both page schemes. A theme that replaces a
+semantic token with a single color instead of a `light-dark()` pair opts that
+token out of the flip. While the surface is open it follows a live switch: an
+OS preference change, or a theme class, attribute, or inline `color-scheme`
+changed on the anchor or one of its ancestors, flips it to the new opposite
+(the content's own color transitions run, as the page's do). A scheme changed
+only by swapping a stylesheet is not observed. `openAnchoredSurfaceAt` reads the
+scheme from its `context` (the element under the pointer), so a region with its
+own `color-scheme` is honored; without a connected `context` it reads the modal
+scope's (or the page's).
+
+## Theming
+
 Override `--kui-anchored-surface-inset` and
 `--kui-anchored-surface-radius` for a theme; content can compose any Kerf UI
 components without the surface applying action policy. Prefer `PopupMenu` for

package/docs/app-layouts.md

@@ -41,8 +41,19 @@ the layouts handle the insets for you. There is nothing to configure:
   status bar or home indicator but its first and last items can always be
   scrolled clear.
 - **Interior edges get nothing.** A `Workbench` center next to an expanded rail,
-  a `SplitView` detail beside its list, or a `NavStack` view under its chrome is
-  not inset on that edge. Collapse the rail and the center picks up the edge.
+  a `SplitView` detail beside its list, or a `NavStack` view under its docked
+  chrome is not inset on that edge. Collapse the rail and the center picks up
+  the edge. A `NavStack` with `chromePresentation="overlay"` is the exception
+  by design: its views reach under the translucent chrome, and the measured
+  chrome height (top safe area included) becomes their block-start inset, so
+  content scrolls beneath the bar yet rests clear of it (see
+  [Navigation stack › Overlay chrome](nav-stack.md#overlay-chrome)). Its
+  `bottomToolbarPresentation="overlay"` does the same at the bottom: the
+  measured toolbar height (bottom safe area included) becomes the views'
+  block-end inset, so the last item rests just above the toolbar. A
+  `TabNavigator` with `barPresentation="overlay"` does the same for its tab
+  bar: the measured bar height (bottom safe area included) becomes the
+  scenes' block-end inset.
 - **No double inset.** Whichever region applies an inset clears it for its
   descendants. A layout region whose only child is a `Pane` or another layout
   lets that child own the insets. That child fills the region — a `Workbench`
@@ -130,6 +141,16 @@ single scrolling slot; the negative margins change only its inline reach. The
 [`Pane` UX catalog example](../ux-demo/demos/pane.tsx) shows both `deepInset`
 states with the same table component.
 
+### Scrolling beneath overlaying chrome
+
+`Pane.scrollClearance` (`"block-start"`, `"block-end"`, or `"both"`) lets the
+scrolling slot pass beneath chrome laid over the pane's edge, such as a
+`DialogSurface` floating footer over a filling Pane. The slot adds the
+inherited `--kui-scroll-clearance-block-*` context that the chrome publishes to
+its block padding and `scroll-padding`, alongside the safe-area and
+`deepInset` insets, so its first and last items still rest clear of the
+chrome. See `docs/layout.md` "Scroll clearance".
+
 ## Decision matrix
 
 | Situation                                                                    | Layout                                                                                           | Device threshold                                                                                                                   |

package/docs/apple-hig.md

@@ -12,6 +12,7 @@ Native Apple applications should use native platform controls and follow the Hum
 - Use one icon family and one metaphor per action. Directional icons may mirror in RTL; checkmarks, logos, and real-world objects do not.
 - Motion is brief, causal, and optional. Honor reduced-motion and reduced-transparency preferences; repeating indicators stop moving under reduced motion.
 - Writing is concise, specific, and action-led. Labels describe the result, not implementation details.
+- Capitalize by element type, consistently: names of commands, controls, views, and fields use title style; descriptions, messages, tooltips, and option text use sentence style. See [Writing interface copy](./writing.md#capitalization).
 
 ## Interaction
 

package/docs/catalog.md

@@ -85,7 +85,7 @@ action. Filtering does not change the selected
 entry or its preview.
 
 Per-entry `resources` render as "open in new tab" links in the footer, and
-`related` renders a "Related entries" `PopupMenu` in a `single`
+`related` renders a "Related Entries" `PopupMenu` in a `single`
 `ToolbarControlGroup` (grouped by each entry's `group`), so register its elements
 with `@kerfjs/ui/popup-menu/register` when you use it.
 
@@ -142,18 +142,64 @@ entry's `tags` array.
   classes. A supplied `label` also names the row's `section`, so each specimen
   is a named region that assistive technology and
   `getByRole("region", { name })` can address.
+- Example and stack labels are headings, so they use title style ("Heading
+  Identity Stays Whole", "Icon Trigger in a Toolbar Group"); the `note` that
+  explains a specimen stays sentence style. Write a label as a name, not a
+  sentence. See [Writing interface copy](./writing.md#capitalization);
+  `kerf-ui-doctor` reports a sentence-case label as `KUI-D040`.
 - Focused demos do not import local stylesheets, use inline `style`, or invent
   styling-only `demo-*` classes. Prefer a public Kerf component, then a Web
   Awesome surface when Kerf has no equivalent, then ordinary semantic HTML.
   Use `CatalogExample.viewport` for bounded specimen width, height, frame,
   surface, overflow, responsive visibility, and public custom-property values;
   keep those constraints catalog-owned instead of recreating a demo stylesheet.
+  Widths run `sidebar` (272px, a production rail, for sidebar-pane content),
+  `compact` (440px), `medium` (640px), and `wide` (864px), each capped at the
+  stage, plus `full`; `text` and `control` size a single label or control.
   Component heights run `short` (220px) through `tall` (360px); frame an app
   shell, whole-screen layout, or other application-sized recipe with
   `height: "app"` (592px), and give its root `fill` rather than a frame `Pane`.
   An app frame stands in for the screen: it is the containing block for
   screen-fixed chrome, so a compact `CollapsiblePanel` overlay, its backdrop,
   and restore controls dock to the frame's edges rather than the page's.
+  `minHeight` (`short`, `medium`, or `app` at 592px) is a floor the frame
+  may grow past rather than a definite height.
+- A top-layer specimen (a `popover`, a modal) that production anchors to a
+  named region with CSS anchor positioning anchors to the frame instead when
+  the frame takes that name: `viewport.anchorName` is a CSS dashed-ident
+  (`"--app-shell-main"`, validated; anything else throws) that becomes the
+  frame's `anchor-name`, so the specimen's own `position-anchor` rule resolves
+  to the frame. Do not wrap the specimen in a stage element to name it. Anchor
+  names are document-wide, so give each frame on a page its own. The frame
+  only names the anchor: the specimen keeps owning its placement, and as a
+  top-layer element it is not clipped by the frame or the stage. Chromium,
+  Firefox, and WebKit with CSS anchor positioning place it against the frame;
+  an engine without anchor positioning ignores the name, and the specimen
+  falls back to whatever placement its own CSS gives it there.
+- For a centered reading column inside a wider frame, set
+  `viewport.contentWidth` (`compact` 440px, `medium` 640px, or `wide` 864px,
+  each capped at the frame) and `contentAlign: "center"` (the default is
+  `start`). Each in-flow child fills that column; `[popover]` children keep
+  their own geometry. The column applies to block, `grid`, and `flex-column`
+  frames, and `contentAlign` does nothing without `contentWidth`.
+
+```tsx
+<CatalogExample
+  label="Request Docked to the Main Column"
+  viewport={{
+    layout: "flex-column",
+    width: "full",
+    minHeight: "app",
+    anchorName: "--app-shell-main",
+    contentWidth: "medium",
+    contentAlign: "center",
+  }}
+>
+  <Transcript />
+  <PermissionRequestPopup /> {/* its CSS: position-anchor: --app-shell-main */}
+</CatalogExample>
+```
+
 - The specimen is an immediate child of `CatalogExample`. A focused component
   row should place the component root there, without a decorative card or
   spacing wrapper. A composition row may place the composition root there.
@@ -171,7 +217,7 @@ import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";
 
 const buttonPreview = (
   <CatalogExampleStack
-    label="Button variants"
+    label="Button Variants"
     rootAttributes={{ "data-demo": "button" }}
   >
     <CatalogExample label="Icon" note="A bare glyph." align="glyph">
@@ -180,7 +226,7 @@ const buttonPreview = (
     <CatalogExample label="Control" align="inline-control">
       <SegmentedControl id="view" label="View" value="list" choices={choices} />
     </CatalogExample>
-    <CatalogExample label="Authoring note" note="Explain the specimen below.">
+    <CatalogExample label="Authoring Note" note="Explain the specimen below.">
       <p>Use the public helper contract.</p>
     </CatalogExample>
   </CatalogExampleStack>
@@ -367,23 +413,23 @@ const sections: CatalogSection[] = [
 const renderers: Record<string, () => SafeHtml> = {
   button: () => (
     <CatalogExampleStack
-      label="Button states"
+      label="Button States"
       rootAttributes={{ "data-demo": "button" }}
     >
       <CatalogExample label="Default" align="inline-control">
         <Button label="Save" />
       </CatalogExample>
-      <CatalogExample label="Authoring note" note="Explain the specimen below.">
+      <CatalogExample label="Authoring Note" note="Explain the specimen below.">
         <p>The application owns product copy and actions.</p>
       </CatalogExample>
     </CatalogExampleStack>
   ),
   "profile-form": () => (
     <CatalogExampleStack
-      label="Profile form composition"
+      label="Profile Form Composition"
       rootAttributes={{ "data-demo": "profile-form" }}
     >
-      <CatalogExample label="Complete composition">
+      <CatalogExample label="Complete Composition">
         <ProfileForm />
       </CatalogExample>
     </CatalogExampleStack>
@@ -499,7 +545,7 @@ revealCatalogEntry(app, initial, { block: "center" });
 
 ## UX Review capture
 
-On a local Vite dev or preview server the catalog can offer a **Capture region**
+On a local Vite dev or preview server the catalog can offer a **Capture Region**
 header link that starts a UX Review region screenshot, preset with the project
 and the active entry. Static hosting has no local project, so the link never
 appears there. Three pieces wire it:

package/docs/collapsible-panel.md

@@ -147,7 +147,9 @@ top toolbar over a `Pane`:
   place groups wherever the open panel needs them;
 - a `ToolbarControlGroup` marked `relocateOnCollapse` stays available in the
   work area when the panel closes; the standard `toggle: { action, name,
-showLabel?, hideLabel? }` is always the final group.
+showLabel?, hideLabel? }` is always the final group. Give `name` as the
+  panel's title-style name ("Navigator"), which labels the toggle group and
+  completes "Show Navigator" / "Hide Navigator".
 
 Busy groups keep their inert control, spinner, and adjacent live status together
 when relocated. Clearing `busy` restores the same action in its current toolbar;
@@ -166,7 +168,8 @@ divider of its own unless `dividerSides` says so. The `Pane` under it draws
 the line under the toolbar only while its content is scrolled (see
 [Scroll dividers](./layout.md#scroll-dividers)), and takes the panel's `pane`
 (`PaneConfig`: `contentElement`, `contentLabel`, `separators`,
-`safeAreaEdges`, `chromeDividers`) — for example `{ contentElement: "nav",
+`safeAreaEdges`, `chromeDividers`, `appearance`, `deepInset`,
+`scrollClearance`, `headerPresentation`, `tabIndex`, `outlined`) — for example `{ contentElement: "nav",
 contentLabel: "Sections" }` for a navigation rail. An omitted or `undefined`
 field keeps the `Pane` default; without a `toolbar` there is no `Pane`, so
 `pane` is ignored.
@@ -187,8 +190,8 @@ inert; avoid duplicate `id` attributes on marked groups.
 const toolbar: CollapsiblePanelToolbar = {
   label: "Navigator",
   leading: <NewFileGroup />,
-  trailing: <ToolbarControlGroup relocateOnCollapse label="Search files"><SearchButton /></ToolbarControlGroup>,
-  toggle: { action: "toggle-nav", name: "navigator" },
+  trailing: <ToolbarControlGroup relocateOnCollapse label="Search Files"><SearchButton /></ToolbarControlGroup>,
+  toggle: { action: "toggle-nav", name: "Navigator" },
 };
 
 <Row fill gap="none">
@@ -307,7 +310,7 @@ mount(app, () => (
           side="left"
           collapsed
           action="toggle-nav"
-          label="Show navigator"
+          label="Show Navigator"
         />
       )}
       {/* content */}
@@ -362,7 +365,7 @@ sizes, content, and any per-project persistence — exactly as with the other la
 
 ## Recipe and coverage
 
-The catalog ships a runnable **Collapsible sidebar** recipe — a left rail and a
+The catalog ships a runnable **Collapsible Sidebar** recipe — a left rail and a
 bottom drawer with the standard toggles, the compact overlay, and per-panel
 persistence: [open it](../ux-demo/?component=recipe-collapsible-sidebar) or read
 [`recipes.md`](recipes.md#collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx).

package/docs/component-contract.md

@@ -89,8 +89,12 @@ only cataloged `descendantElements` and composed JSX evidence.
 An entry's optional `cssValueProps` makes CSS-adjacent prop grammar equally
 machine-evaluable. Each path records the property grammar, finite shorthands,
 canonical versus exceptional spacing choices, standalone and expression-only
-helpers, raw/unsafe policy, and serialization examples. Nested paths use the
-bounded `items[].property` form. Consumer catalogs can publish the same facts;
+helpers, raw/unsafe policy, and serialization examples. Nested paths are
+dot-separated object members, each optionally suffixed with `[]` to visit
+every array element: `items[].property` for a value inside each array item,
+`iconTile.color` for a member of an object-valued prop. A member that is not a
+literal object or array (a tone string such as `iconTile="brand"`, a variable)
+is skipped rather than guessed. Consumer catalogs can publish the same facts;
 ESLint, `kerf-ui-analyze`, and `kerf-ui-doctor` then issue the same stable
 `KUI-L013`–`KUI-L017` feedback for application and third-party components.
 
@@ -246,10 +250,10 @@ product that genuinely needs one of these elements records a narrow `KUI-L301`
 profile exception for the file that renders it.
 
 Catalog detail footers use one standard resource vocabulary and order. Build
-them with `catalogResources()` from `@kerfjs/ui/catalog-resources`: `Demo source`
-first, optional `Component source` and `Design template`, then `Guidance`.
+them with `catalogResources()` from `@kerfjs/ui/catalog-resources`: `Demo Source`
+first, optional `Component Source` and `Design Template`, then `Guidance`.
 Third-party entries use the typed `integrationGuidance` kind, which renders
-`Integration guidance`, and omit `Component source` when the implementation is
+`Integration Guidance`, and omit `Component Source` when the implementation is
 not owned by the catalog's project. Prefer these semantic kinds over local labels
 such as “View source” or “Read UI guidance”; the helper makes that convention a
 compile-time choice while still returning ordinary `CatalogResource[]` values.
@@ -333,6 +337,8 @@ visual anchor.
 
 `ToolbarControlGroup.tileTone` selects `neutral`, `brand`, `success`, `warning`, or `danger` quiet fill, matching quiet border, and on-quiet foreground for a non-interactive icon tile. Compose a contained `single` group whose only child is a direct decorative LucideIcon (`aria-hidden="true"`). Omission preserves the normal group palette. The prop does not recolor interactive, mixed, multi-control, or borderless groups; keep real actions in controls with their existing focus/hover/pressed treatments.
 
+`ListItem`, `ListItemLink`, and `ListActionRow` take `iconTile` to present their leading `icon` in a filled 32px rounded tile holding an 18px glyph, for settings or command rows that identify each entry by color. Pass a tone (`neutral`, `brand`, `success`, `warning`, or `danger`) for the same quiet fill, matching quiet border, and on-quiet foreground as `ToolbarControlGroup.tileTone`, or `{ color, foreground? }` for an application color: `color` is a `CssColor` (`uiColor()`, `colorVar()`, or `fillColor('#e5484d')`) and `foreground` a `CssForegroundColor`; without one, the glyph is black or white, whichever contrasts with the fill. The tile sits 6px clear of a standard 44px row (a compact row is at least 42px tall), moves the label to the tile's edge, and keeps its colors when the row is hovered or selected. Never wrap the icon in your own tile or resize the row's icon slot.
+
 ### Public CSS anatomy
 
 The `publicClasses` array on each entry in
@@ -396,7 +402,12 @@ The documented exceptions live with their reasons in
 check, so the list only shrinks. The layout regions' inherited edge-inset
 context (`--kui-edge-inset-*` handed to a sole Pane or layout child and cleared
 for any other content, and a Toolbar clearing it for its zones) is the one
-design exception; the others name the open fix ticket.
+design exception; the others name the open fix ticket. The scroll-clearance
+context (`--kui-scroll-clearance-block-*`) needs no exception: overlaying
+chrome publishes it on its own element (a `DialogSurface` on its dialog body,
+a `Pane` overlay header, through `wireScrollDividers`, on its own Pane root).
+A scroll owner reads it only through its own `scrollClearance` prop, or, for an
+overlay-header Pane's content, through its own `headerPresentation`.
 
 Applications and component packages built on the package follow the same
 rules, and the downstream tools enforce them against the composition catalog
@@ -628,10 +639,14 @@ contract in `foundation.css`. A capped popup that scrolls (a long listbox, a
 menu, or a phone submenu) shows a soft shadow along each edge with more
 choices beyond it, so overlay scrollbars never leave it looking complete; the
 cue is CSS-only, appears only toward hidden rows, and a popup whose choices
-all fit draws none. Checkbox items reserve a check column; plain commands start
-at the checkmark's leading edge, beside the group title rather than the
-farther-in Select option label. Checked submenu items keep their checkmark and
-label inside the submenu surface. Compact mixed controls retain the standard
+all fit draws none. Checkbox items reserve a check column, and so does every
+plain command in a level (the top menu or one submenu) that holds a checkbox
+item, through an `aria-hidden` icon-slot spacer, so check, icon, and label
+columns align across the level. A level without a checkbox item keeps the
+compact start: plain commands begin at the checkmark's leading edge, beside the
+group title rather than the farther-in Select option label. Checked submenu
+items keep their checkmark inside the submenu surface with the same check-column
+advance as the top level. Compact mixed controls retain the standard
 item padding, omit an internal separator, and let the raised selected item paint
 over the outer border instead of shrinking to an inset highlight. The Web
 Awesome trigger's shadow base owns max-content sizing, so icons, localized text,
@@ -743,7 +758,12 @@ propagating before the window, or a press without a click, collapses in the
 next task instead.
 `TokenSearchField.trailingAction` supplies an icon, accessible `label`, delegated
 `action`, and optional `id`; the field renders a 24px wide button that fills its
-34px line slot, including the hit target, disabled state, hover, and focus ring.
+34px line slot (32px in `toolbar-group`), including the hit target, disabled
+state, hover, focus ring, and the clear button's radius in each presentation.
+`expanded` renders `aria-expanded` and `pressed` renders `aria-pressed` (one or
+the other, never both); either `true` state keeps the hover fill at full text
+strength. `controls` and `haspopup` render `aria-controls` and `aria-haspopup`,
+and `attributes` carries domain `data-*` metadata but never `data-action`.
 Use `trailing` for passive content. The two props are mutually exclusive.
 For a collapsible search in a stretched Toolbar center, `fill` lets the expanded
 field and its enclosing search `ToolbarControlGroup` consume the available width;
@@ -786,7 +806,16 @@ When a leading AppTab is pinned, the leading scroll divider appears at that
 tab's trailing edge while peer tabs scroll beneath it, including in RTL.
 With `snapTabs`, `wireTabBars` measures the pinned tab and settles peers at
 whole-tab starts after scroll and selection changes, reserving end room so the
-last peer can align there. The application still owns selection and tab order.
+last peer can align there. That room is scrollable content after the last tab,
+inside the strip, so it lengthens the scroll range without widening the strip:
+the strip still shrinks to its allocation, and `trailing` and `end` stay inside
+the bar. The room is still in-flow content, so it counts toward the strip's
+content-based flex basis: when another zone also shrinks (a trailing zone
+given `--kui-tab-bar-trailing-flex: 0 1 auto` with shrinkable content), the
+strip keeps a proportionally larger share. The share converges within a few
+frames and never pushes `trailing` or `end` out of the bar; keep the trailing
+zone non-shrinking with `snapTabs` to avoid it. The application still owns
+selection and tab order.
 ResizeObserver notifications coalesce snap measurements into the next animation
 frame, so inset writes cannot resize the observed strip during observer delivery.
 `wireTabBars` watches the whole root it is given, but a mutation re-measures only