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

package/docs/surface-scaffold.md

@@ -54,7 +54,7 @@ import { remify } from '@kerfjs/ui/css-values';
 import { DialogSurface } from '@kerfjs/ui/surface-scaffold';
 
 <DialogSurface preferredWidth={remify(832)} viewportGutter={remify(8)} maxHeight="viewport" bodyInset="none">
-  <wa-dialog label="Close workspace">{/* Application-owned content and footer */}</wa-dialog>
+  <wa-dialog label="Close Workspace">{/* Application-owned content and footer */}</wa-dialog>
 </DialogSurface>;
 ```
 
@@ -86,12 +86,129 @@ itself stops scrolling. Combine it with `bodyInset="none"`.
 
 ```tsx
 <DialogSurface size="large" height={remify(640)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill">
-  <wa-dialog label="Repository status">
+  <wa-dialog label="Repository Status">
     <SplitView id="repo-split" label="Changes" listWidth={{ size: 432, maxFraction: 0.5 }} list={list} detail={detail} />
   </wa-dialog>
 </DialogSurface>;
 ```
 
+### Chat dialogs: a floating footer over a filling transcript
+
+A chat-style dialog keeps a heading or notices above one scrolling transcript
+and floats its composer over the body's block end. Two props compose it:
+
+- `bodyLayout="fill-last"` stacks the body's children: the leading children
+  keep their natural height, and the last one takes the remaining height and
+  owns its scrolling (a `scrollable` `List` transcript). The body itself stops
+  scrolling. `PopoverDialogSurface` accepts the same layout.
+- `footerPresentation="floating"` lays the footer over the body's block end,
+  `footerOffset` (a branded `CssLength`, default the 16px container inset)
+  from the panel's inline and block-end edges, on a transparent background.
+  The modal panel is its positioning context. The default `docked` footer
+  sits below the body as before.
+
+The register measures the footer (it follows a composer that grows, wraps, or
+hides) and the body reserves that height plus the offset after its own inset,
+with a matching `scroll-padding`. Flowing body content scrolls beneath the
+floating footer and its end stays reachable above it; with `fill` or
+`fill-last` the filling child's scrollport ends at the footer's top. Content
+is never hidden beneath the footer.
+
+To let a filling transcript scroll visibly beneath the floating footer, opt
+its scroller in with `scrollClearance="block-end"` (a `scrollable` `List`, or a
+`Pane`, as the `fill` or last `fill-last` child). The body then stops
+reserving the footer below that child, so the child reaches the panel's block
+end, and publishes the footer's clearance (measured height plus offset) as the
+inherited `--kui-scroll-clearance-block-end` context. The child adds it to its
+own block-end padding and `scroll-padding`: messages pass beneath the
+transparent footer mid-scroll, the last message rests above the composer at
+the end, and focus or `scrollIntoView` never leaves an item hidden beneath it.
+The context is general: chrome that overlays a region's block-start or
+block-end edge publishes `--kui-scroll-clearance-block-start` / `-end`, and a
+scroll owner opts in per edge (see `docs/layout.md` "Scroll clearance"). A
+dialog body clears any clearance inherited from the page.
+
+Choose the offset like any other responsive value: the scaffold adds no
+breakpoint. An 8px offset lines a composer up with the transcript's
+content-item edges when the body has `bodyInset="none"` and list geometry;
+`viewportGutter` and `footerOffset` can follow `deviceClass()` when a phone
+needs tighter edges. Put a [`Composer`](./composer.md) in the floating footer
+with `footerInset="none"`: its raised frame and shadow lift it over the
+transcript, and its field grows the measured footer. With `submitOnEnter` and
+`wireComposers(root)`, Enter sends through the same action as the Send button.
+
+```tsx
+<DialogSurface height={remify(560)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill-last" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
+  <wa-dialog label="Assistant">
+    <StateBanner title="Answers use the latest nightly build." tone="neutral" />
+    <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">
+      {messages.map((message) => (
+        <ContentItem bubble={message.mine ? 'end' : 'start'} appearance={message.mine ? 'brand-loud' : 'neutral'}>
+          <Text variant="span">{message.text}</Text>
+        </ContentItem>
+      ))}
+    </List>
+    <Composer submitOnEnter slot="footer" id="assistant-message" name="message" label="Message" placeholder="Ask about this build" actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>} />
+  </wa-dialog>
+</DialogSurface>;
+```
+
+### A floating title bar
+
+`headerPresentation="floating"` lays the dialog's header (its title and close
+control) over the body's block-start edge on the translucent chrome material,
+`--kui-chrome-material-raised` (the raised panel surface at 80% opacity)
+behind `--kui-chrome-material-filter` (a blur and saturation backdrop filter).
+Content passing beneath the title bar reads as softened color, not as
+competing text. The default `docked` header sits above the body as before.
+
+The register measures the header the same way it measures the footer (it
+follows a title that wraps, text that grows, or a `without-header` toggle).
+The body reserves the measured height before its own inset, with a matching
+`scroll-padding`, so flowing content starts below the title bar and scrolls
+beneath it. A dialog without the register has no measurement, so its header
+stays docked rather than covering content.
+
+To let a filling transcript scroll visibly beneath the title bar, make it the
+body's only child (`bodyLayout="fill"`, or `fill-last` with no leading rows)
+and opt its scroller in with block-start `scrollClearance`. The body then
+stops reserving the header, so the child reaches the panel's block-start
+edge, and publishes the header's height as `--kui-scroll-clearance-block-start`.
+Leading `fill-last` rows (a notice above the transcript) keep the body's
+reservation: they never sit beneath the title bar. Combined with a floating
+composer and `scrollClearance="both"`, the transcript scrolls beneath both:
+
+```tsx
+<DialogSurface height={remify(560)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill" headerPresentation="floating" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
+  <wa-dialog label="Release Thread">
+    <ToolbarText slot="label" text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />
+    <List gap="xs" controlInsets="tb" scrollable scrollClearance="both">
+      {bubbles}
+    </List>
+    <Composer submitOnEnter slot="footer" id="thread-message" name="message" label="Message" placeholder="Reply to the thread" actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>} />
+  </wa-dialog>
+</DialogSurface>;
+```
+
+Like a `Pane`'s overlay header, the title bar draws its divider as scroll
+state: a 1px line along its bottom edge only while the body, or a filling
+child that reaches beneath it, is scrolled away from its top, and none at
+rest. The register follows those scrollers (a nested scroller that starts
+below the title bar never counts), and the line is an inset shadow, so it
+never moves the header or the content.
+
+The material turns opaque under `prefers-reduced-transparency: reduce` or
+`prefers-contrast: more`, and where the browser lacks `backdrop-filter`; in
+forced colors the header paints `Canvas` with a `CanvasText` bottom edge.
+
+For a title with a short supporting line, slot a `ToolbarText` as the label
+(`<ToolbarText slot="label" text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />`).
+On the floating title bar an untoned `ToolbarText` keeps AA by itself: its
+title takes the normal text color and its description lifts halfway toward
+it. Any other quiet copy you place there can fall below AA over the content
+passing beneath it, so keep it in the body (see
+[Accessibility › Chrome material](accessibility.md#chrome-material)).
+
 Treat a dialog body as a `List` by default. When its rows or sections own their
 standard list geometry, set `bodyInset="none"` so the dialog does not add a
 second inset. Bare prose is still a list child: wrap it in `ListInsetText` so its
@@ -109,8 +226,22 @@ hand-built popover with application chrome CSS. It is a native
 `popover="auto"` section with `role="dialog"` that owns Kerf's dialog chrome
 (raised surface, border, large radius and shadow, and a backdrop) and the
 same geometry props as a modal `DialogSurface`: `size`, `preferredWidth`,
-`viewportGutter` (16px by default), `height` / `maxHeight`, and `bodyLayout`.
-Name it with `label` or `labelledBy`.
+`viewportGutter` (16px by default), `height` / `maxHeight`, and `bodyLayout`
+(`flow`, `fill`, or `fill-last`).
+Name it with `label` or `labelledBy`. To give it an accessible description,
+pass `describedBy`, the id of the element that holds the summary. It renders as
+`aria-describedby` on the `role="dialog"` root and usually names a title
+`ToolbarText`'s `descriptionId`:
+
+```tsx
+<PopoverDialogSurface id="connection-details" labelledBy="connection-title" describedBy="connection-summary" bodyLayout="fill-last">
+  <Toolbar label="Connection Details Heading" leading={<ToolbarText text="Connection Details" size="xlarge" id="connection-title" description="Connected to the build server." descriptionId="connection-summary" />} />
+  {details}
+</PopoverDialogSurface>;
+```
+
+`DialogSurface` has no `describedBy`. It wraps a `wa-dialog` that the app
+authors, so the app names and describes that dialog on its own markup.
 
 Open it with a control's `popoverTarget` (or `showPopover()`); the browser
 places it centered in the top layer, light-dismisses it, and restores nothing
@@ -121,8 +252,8 @@ layer and never wider than its container, for a catalog specimen or an inline
 preview.
 
 ```tsx
-<button type="button" popoverTarget="repository-status">Repository status</button>
-<PopoverDialogSurface id="repository-status" label="Repository status" preferredWidth={remify(1024)} height={remify(640)} viewportGutter={remify(8)} bodyLayout="fill">
+<button type="button" popoverTarget="repository-status">Repository Status</button>
+<PopoverDialogSurface id="repository-status" label="Repository Status" preferredWidth={remify(1024)} height={remify(640)} viewportGutter={remify(8)} bodyLayout="fill">
   <SplitView id="repo-split" label="Changes" list={list} detail={detail} />
 </PopoverDialogSurface>;
 ```
@@ -136,4 +267,4 @@ preserve `data-morph-skip-children` when its upgraded light-DOM items must retai
 identity across Kerf rerenders. Import `@kerfjs/ui/popup-menu/register` once for
 the focus handoff fix when wrapping a raw `wa-dropdown`.
 
-Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog` and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
+Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog`, measures each surface's footer for a floating footer's body clearance, draws a floating header's divider while content is scrolled beneath it, and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.

package/docs/tab-navigator.md

@@ -136,7 +136,7 @@ The app owns each stack's view array and the navigator's active tab. Call
 `wireTabNavigator` for tab selection and `wireNavStack` for back navigation
 and transitions, each on its own component root. Push a detail by appending
 a view with its own `toolbar` and `pane`; switching tabs keeps that view
-mounted. The catalog's **NavStack inside a tab** example demonstrates the
+mounted. The catalog's **NavStack Inside a Tab** example demonstrates the
 push, tab switch, and return flow.
 
 Set a tab's `appearance: "sunken"` when its scene owns scrolling and should
@@ -169,6 +169,43 @@ so it never moves the bar or a tab.
 the wiring reports content below. It does not suppress the sunken-surface
 separator; use `separator="hidden"` for that.
 
+## Translucent bar
+
+`barPresentation="overlay"` lays the tab bar over the active scene's bottom
+edge on the translucent chrome material (`--kui-chrome-material` behind
+`--kui-chrome-material-filter`), so the scene's content scrolls visibly beneath
+it, as under an iOS tab bar. The default, `docked`, gives the bar its own band.
+
+```tsx
+<TabNavigator
+  id="mail"
+  label="Mail Sections"
+  barPresentation="overlay"
+  active={active.value}
+  tabs={tabs}
+/>;
+```
+
+`wireTabNavigator` measures the live bar's border box (bottom safe area and its
+1px top edge included), publishes it on the root, and marks the root
+`data-bar-overlay="measured"`. The scenes then hand that height to their
+content as the block-end `--kui-edge-inset-*` context: a plain scene pads and
+scroll-pads by it, and a sole `Pane` or `NavStack` clears it itself, so the
+last item, and anything focused or scrolled into view, rests just above the
+bar. A `NavStack` with its own bottom toolbar pads that toolbar for the bar as
+it would for a bottom safe area: the toolbar's controls sit just above the tab
+bar while its material runs on beneath it. Until the wiring runs, the bar stays
+docked.
+
+Over the material, unselected labels lift halfway toward the normal text color
+and the selected label mixes 40% of it into the brand color, so both keep AA
+over any content beneath. The material turns opaque under reduced
+transparency, increased contrast, or without `backdrop-filter`, and paints
+`Canvas` with a `CanvasText` top edge in forced colors. The scroll divider still
+shows only while more content lies below. Like the NavStack overlay bars, the
+tab bar ends where a classic (space-taking) scrollbar's track begins, so the
+active scene's thumb and buttons stay visible and usable.
+
 ## Tab badges
 
 Give a tab a `badge` (a count or short string such as `3`, `"99+"`, or

package/docs/type-contracts.md

@@ -11,22 +11,22 @@ public-signature artifact.
 
 ## Strengthened contracts
 
-| ID         | Compile-time guarantee                                                                                                                                                                                                                                                                                                                                                                                 |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `KUI-T001` | `ListHeader` is a passive heading, a fully named/icon-bearing trailing action, or a controlled disclosure with `action` + `expanded`. Props ignored by the selected mode are rejected.                                                                                                                                                                                                                 |
-| `KUI-T002` | `Select` has a visible `label` or an `ariaLabel`.                                                                                                                                                                                                                                                                                                                                                      |
-| `KUI-T003` | A literal `Select.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                                                                                             |
-| `KUI-T004` | A literal `SegmentedControl.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                                                                                   |
-| `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `TokenSearchField({ collapsible: true })`.                                                                                                                                                                                                                                                                                                 |
-| `KUI-T006` | `TokenSearchEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                                                                                                                                                                                                                                    |
-| `KUI-T007` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                                                                                                                                                                                                                                              |
-| `KUI-T008` | A literal `TabNavigator.active` id belongs to its literal `tabs`.                                                                                                                                                                                                                                                                                                                                      |
-| `KUI-T009` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                                                                                                                                                                                                                                      |
-| `KUI-T010` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all AppTab, TabBar, ToolbarControlGroup, and Select presentation axes; the convenience root barrel re-exports them.                                                                                                                                                               |
-| `KUI-T011` | Semantic component zones use the recursive `KerfUiContent` type: `SafeHtml`, runtime-empty booleans/nullish values, and readonly nested arrays are valid; arbitrary strings, numbers, and signals are rejected. Explicit text positions such as `ListInsetText` retain their text exception.                                                                                                           |
-| `KUI-T012` | `List.gap` accepts finite `UiSpaceName` shorthands or a complete branded `CssLength`; raw strings and non-standalone `CssLengthExpression` arithmetic are rejected. `calc(plus(...))` promotes a typed expression to a complete value.                                                                                                                                                                 |
-| `KUI-T013` | CSS-valued props preserve property grammar: `List.flex` uses `CssFlex`, `Skeleton` dimensions use `CssSize`/`CssLength`, and choice icons and `LucideIcon.color` use `CssForegroundColor` (foreground tokens via `uiColor()`, `foregroundColorVar()`, or custom values via `foregroundColor()`; fill tokens such as `uiColor('success-fill-quiet')` are rejected); row declaration strings are absent. |
-| `KUI-T014` | Stable single-root visual components accept the explicit native `slot` attribute. Multi-root `ResizableRegion` and `CollapsiblePanel` remain excluded because no single returned element can own the assignment, and other arbitrary native attributes remain rejected.                                                                                                                                |
+| ID         | Compile-time guarantee                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KUI-T001` | `ListHeader` is a passive heading, a fully named/icon-bearing trailing action, or a controlled disclosure with `action` + `expanded`. Props ignored by the selected mode are rejected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `KUI-T002` | `Select` has a visible `label` or an `ariaLabel`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `KUI-T003` | A literal `Select.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `KUI-T004` | A literal `SegmentedControl.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `TokenSearchField({ collapsible: true })`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `KUI-T006` | `TokenSearchEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `KUI-T007` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `KUI-T008` | A literal `TabNavigator.active` id belongs to its literal `tabs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `KUI-T009` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `KUI-T010` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all AppTab, TabBar, ToolbarControlGroup, and Select presentation axes; the convenience root barrel re-exports them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `KUI-T011` | Semantic component zones use the recursive `KerfUiContent` type: `SafeHtml`, runtime-empty booleans/nullish values, and readonly nested arrays are valid; arbitrary strings, numbers, and signals are rejected. Explicit text positions such as `ListInsetText` retain their text exception.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `KUI-T012` | `List.gap` accepts finite `UiSpaceName` shorthands or a complete branded `CssLength`; raw strings and non-standalone `CssLengthExpression` arithmetic are rejected. `calc(plus(...))` promotes a typed expression to a complete value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `KUI-T013` | CSS-valued props preserve property grammar: `List.flex` uses `CssFlex`, `Skeleton` dimensions use `CssSize`/`CssLength`, and choice icons and `LucideIcon.color` use `CssForegroundColor` (foreground tokens via `uiColor()`, `foregroundColorVar()`, or custom values via `foregroundColor()`; fill tokens such as `uiColor('success-fill-quiet')` are rejected); a row `iconTile` is a finite tone or a `CssColor` fill (custom values via `fillColor()`) with an optional `CssForegroundColor` glyph, and a `ChoiceChips` swatch is a `CssColor` fill (`fillColor()`, `uiColor()`, `colorVar()`) or `'transparent'`; a `fillColor()` value is a plain `CssColor` and is rejected where a `CssForegroundColor` is required; row declaration strings are absent. |
+| `KUI-T014` | Stable single-root visual components accept the explicit native `slot` attribute. Multi-root `ResizableRegion` and `CollapsiblePanel` remain excluded because no single returned element can own the assignment, and other arbitrary native attributes remain rejected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
 `KerfUiContent` lets conditionals and mapped component collections be direct
 siblings without an otherwise-unnecessary `Fragment`:

package/docs/ui-analyzer.md

@@ -110,7 +110,9 @@ Catalog entries may also publish `cssValueProps`. Each path names its grammar,
 finite shorthands, canonical and exceptional scale steps, accepted typed
 helpers, expression-only helpers, raw escape policy, and examples. The analyzer
 uses that same metadata for direct component calls and JSX, including nested
-paths such as `choices[].color`; consumer catalogs receive identical checks.
+paths such as `choices[].color` (each array item's member) and
+`iconTile.color` (an object-valued prop's member, skipped when the prop is a
+tone string); consumer catalogs receive identical checks.
 Dynamic values remain a type-system responsibility rather than being guessed.
 
 ## Component ownership (`KUI-L019`–`KUI-L023`)

package/docs/ui-doctor.md

@@ -139,6 +139,77 @@ The browser evaluator is different: it runs the application and is disabled by d
 
 An unavailable or failed stage does not prevent independent stages from reporting. Its final exit is still a configuration failure, so a partial run cannot appear clean.
 
+## Interface copy capitalization
+
+The analyzer stage also checks visible label copy against the package
+capitalization rule in [Writing interface copy](./writing.md#capitalization).
+Names of commands, controls, views, and fields use title style, following
+Apple's guidance. `KUI-D040` (warning) reports a string or template literal
+passed to a known title-style prop that leaves a word lowercase where title style
+capitalizes it. For example, `<wa-button>Save draft</wa-button>` should be
+"Save Draft", and `<ListHeader label="Needs attention" />` should be "Needs
+Attention". The action names the repaired label.
+
+The check reads `.tsx` and `.jsx` source text only and skips test modules.
+Fixture components that tests render (for example
+`tests/browser/fixtures/*.tsx`) are not test modules and are checked: they
+stand in for application screens, so their copy follows the same rule. It
+covers these string literals:
+
+- `ToolbarText` titles: text with `headingLevel`, a large size, or in a
+  toolbar or panel `title`, `header`, or (unless small) `leading` slot;
+- `ListHeader`, `ListActionRow`, `SplitButton`, and `Combobox` labels;
+- `CatalogExample` and `CatalogExampleStack` labels, which render as a
+  `ListHeader` heading (their `note` stays sentence style and is not read);
+- `EmptyState` and `StateBanner` titles;
+- `PopupMenu` trigger text and item and heading labels, including submenus
+  declared in the same file;
+- `SegmentedControl`, `Select`, and `TabNavigator` choice and tab labels;
+- `NavStack` view titles and `backText`, and `SplitView` `backLabel`;
+- `FieldLabel` text and the static text of a `button` or `wa-button`;
+- the `name` of a panel toolbar's `toggle: { action, name }` object literal
+  (Workbench panels, `CollapsiblePanel`), which names the toggle group and
+  completes its "Show …" / "Hide …" label;
+- region and landmark names: the `label` of `Pane`, `Workbench`, `Toolbar`,
+  `ToolbarControlGroup`, `TabBar`, `NavStack`, `CollapsiblePanel`,
+  `FloatingToolbar`, and `ResizableRegion`; the `ariaLabel` of `SunkenPanel`
+  and `List`; a `Pane`'s `contentLabel`; the panel, toolbar, and pane labels
+  in `Workbench` (`leftRail`, `rightRail`, `bottomDrawer`, `mainToolbar`,
+  `mainBottomToolbar`, `mainPane`), `CollapsiblePanel` (`toolbar`,
+  `bottomToolbar`, `pane`), and `NavStack` (`views`, `bottomToolbar`)
+  configuration declared in the same file; and the `aria-label` of a
+  `section`, `nav`, `aside`, `main`, `header`, `footer`, `form`, or `search`
+  element or an element with a landmark `role`;
+- the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or
+  `wa-radio-group`, which is a field or group label;
+- the accessible names of icon-only controls, which the rule also gives title
+  style: `IconButton` and `IconToggleButton` `label`, `PopupMenu` `label`,
+  `SplitButton` `optionsLabel`, `TokenSearchField` `clearLabel`, and the
+  `aria-label` of a `button` or `wa-button` whose only content is an icon. A
+  button with visible text is judged by that text, never by its `aria-label`.
+
+The check is deliberately one-directional, to keep false positives rare:
+
+- It reports only lowercase words. It never reports a capitalized short word,
+  because Apple capitalizes a phrasal verb's particle ("Log In to the
+  Server").
+- It leaves text ending in `.`, `!`, or `?` to sentence style.
+- It judges only a template literal's static words, so
+  `` `Edit ${name} shortcut` `` is reported and the interpolated value never
+  is. A word joined to an interpolation (`` `${count}s` ``) is skipped.
+- It ignores other dynamic values and every sentence-style surface: descriptions,
+  details, placeholders, tooltips, status text, and option text, including
+  `wa-checkbox`, `wa-switch`, and `wa-radio` labels. It does not read
+  `LoadingSpinner` or `Skeleton` labels, which announce a status.
+- It skips tokens containing digits, code, paths, or URLs, and lowercase-led
+  brands such as iOS and macOS.
+- It keeps a minor word inside a longer hyphenated compound lowercase, as
+  between separate words ("Edge-to-Edge", "Up-to-Date").
+- It does not read `ContentItem` `title`, which is a native tooltip.
+
+Suppress `KUI-D040` for a file whose copy is a lowercase brand or product
+name.
+
 ## Full and changed modes
 
 `--full` is the default and analyzes the selected package. `--changed` reads tracked and untracked paths from Git unless one or more `--path` values are supplied. An empty changed set is a configuration error instead of a false-clean success. With `--package`, workspace-relative Git paths are converted to package-relative paths before TypeScript, ESLint, and analyzer selection; paths outside the selected package are ignored.

package/docs/ux-demo.md

@@ -21,13 +21,13 @@ Each `?component=recipe-*` route uses public package primitives, real wiring,
 deterministic state, and semantic layout owners from the [recipe guide](./recipes.md).
 
 - It imports public component subpaths, exercising their browser-selected reachable CSS rather than a catalog-only style path.
-- The `ListActionRow` route's Run tests row composes a trailing `PopupMenu` (`trailingMenu`) with Edit and Delete commands, revealed on interaction, that also opens at the pointer when the row's primary button is right-clicked.
+- The `ListActionRow` route's Run Tests row composes a trailing `PopupMenu` (`trailingMenu`) with Edit and Delete commands, revealed on interaction, that also opens at the pointer when the row's primary button is right-clicked.
 - The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
-- The `PopupMenu` route's context example opens one app-owned menu either at the row's right-click point or below its adjacent, keyboard-operable Demand actions button. The Nested decisions example shows the automatic phone-width submenu placement above or below its parent list, with native ArrowLeft return, Escape dismissal, and child selection.
+- The `PopupMenu` route's context example opens one app-owned menu either at the row's right-click point or below its adjacent, keyboard-operable Demand Actions button. The Nested Decisions example shows the automatic phone-width submenu placement above or below its parent list, with native ArrowLeft return, Escape dismissal, and child selection.
 - The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, pending, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The pinned leading-tab specimen uses native strip scrolling so momentum and the final tab's end position remain natural; `snapTabs` stays an opt-in for applications that want whole-tab settling. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding (a new tab opens `pending` with a spinner and stays selectable while its panel shows a `Skeleton` heading until a simulated load completes), closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
 - Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, and feedback scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component. The former aggregate Web Awesome theme specimen is intentionally omitted because its component families are covered by those focused routes.
 - `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Functional groups follow their authored importance order; components precede compositions inside each group, equal-importance entries use alphabetical order, and the Recipes group comes last. Composition names stay concise and project a visible `Composition` sidebar tag. Non-supported Web Awesome recommendations project to a visible `Discouraged` tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
-- Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
+- Every detail footer groups compact `Demo Source` and `Guidance` actions; first-party component details also expose `Component Source`. Web Awesome details say `Integration Guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
 - The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 15 discouraged choices. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
 - The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with supporting copy in its own aligned row; the current-view heading is also a toolbar. The shared Catalog sidebar includes a filter for entry and heading names that works across first-party and ecosystem sections, including collapsed sections. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The preview stage sits directly in the sunken main Pane, with its canvas padded by the medium spacing token. The stage fills the preview scroller for short specimens and grows with taller ones; every background choice follows that same shared behavior in this demo and in consumers. The checkerboard belongs to that stage, rather than a viewport-height wrapper or nested card, and one explicitly repeated SVG tile keeps the pattern continuous through below-fold content. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
 - The composer-form recipe demonstrates one coherent visible form surface with toolbar title/supporting-copy hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
@@ -35,7 +35,7 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - Catalog-only brand marks, preview dimensions, checkerboard tiles, and the compound display-settings control retain local geometry because they are specimen chrome or intrinsic control anatomy rather than reusable application spacing roles.
 - The menu composition route demonstrates toolbar/content/footer anatomy, 24px major gaps, 8/1/8 child geometry, the full-width `ListHeader` count-or-badge/action split, logical-end 44px action targets with 18px visuals, and 44px row/header/toolbar targets. Its one chevron is a production 18px `DisclosureArrow` inside a controlled Tools header that actually reveals and hides content; ordinary Projects navigation has no false disclosure affordance. Browser assertions cover stable naming, expanded/content transitions, visual rotation, node identity, reduced motion, RTL alignment and containment, and wide, narrow, dark, and 200% layouts. The focused ListHeader route separately shows the shared neutral count pill for Attachments, Notes (including zero), and Duplicates plus a non-count legacy badge, full-width logical-end actions, and no disclosure without content.
 - The `DisclosureArrow` route renders the production 18px root-scaled default without a catalog-only size override. Its two native buttons independently control the default right-to-down chevron and a recognizable right-facing replacement arrow with left-to-up custom directions; both use shortest-path rotation and their names stay stable while `aria-expanded` communicates state. Browser coverage verifies the custom clockwise path, pointer and native keyboard activation, focus, narrow and 200%-zoom stacking with contained labels, consumer sizing, and the independent `.5` Web Awesome glyph scale retained by Kerf `Select`.
-- A detail with relationships renders one content-fitted `Components` footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Its popup owns the standard surface inset so headings and even long component names stay clear of the menu border. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
+- A detail with relationships renders one content-fitted `Components` footer selector: `Uses` links to direct dependencies and `Used By` links to reverse dependents. Its popup owns the standard surface inset so headings and even long component names stay clear of the menu border. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
 - Focused demos ship no local stylesheets, inline styles, or styling-only class names. They compose Kerf components first, Web Awesome surfaces where Kerf has no equivalent, and ordinary semantic HTML for the remainder. The catalog-owned `CatalogExample.viewport` contract supplies the few specimen constraints needed to demonstrate layout behavior. Recipes follow the same rule: they ship no stylesheets, inline styles, or styling-only classes, and the catalog frames each one in the `CatalogExample` viewport its exported `presentation` declares (full-width application arrangements span the canvas measure; narrower recipes sit in the left-aligned example column). Demo-only CSS is limited to the document-shell `style.css`, which carries no recipe rules. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
 - Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. Individual Web Awesome action, form, layout, navigation, feedback, media, and helper routes provide focused theme specimens without a redundant aggregate route; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges, a scoped override, and a placeholder with and without a badge, the badged placeholder in every tone so captures cover the solid badge skeleton; the Application tabs composition uses a Web Awesome card with semantic header/footer slots and Kerf `Text` while demonstrating overflow, edge autoscroll, and controlled pointer/keyboard reordering.
 - The ToolbarControlGroup route also demonstrates the public compact/tight,
@@ -53,11 +53,11 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - The footer action log is an `aria-live` region, making interactions visible to both people and browser tests.
 - The focused Toast route calls Web Awesome's documented programmatic stack API and notes that Hot Sheet 2 still uses its own app-level toast implementation; the catalog demonstrates ecosystem support without implying current product adoption.
 - Browser coverage walks every Kerf, composition, and Web Awesome route, checks every listed Web Awesome custom element is registered in its focused specimen, exercises the ecosystem disclosure and both relationship directions, validates offline source/guidance hrefs and accessible wide/narrow/200%-zoom wrapping, and covers tab selection/reordering/overflow, semantic palettes and scoped overrides, light/dark rendering, toolbar popup and responsive find behavior, single/multiline search alignment, menu alignment, banner urgency, keyboard resizing, live custom-element values, and representative wide/narrow captures.
-- The production build keeps the catalog shell and Kerf routes in the entry chunk and moves the third-party code loaded at startup (the Web Awesome select and popup-menu registrations with their Lit and Floating UI runtime) into an eagerly preloaded `vendor` chunk, so neither nears the largest-chunk limit in `demo-bundle-budget.json`; only modules statically reachable from the entry qualify, so lazy-only dependencies stay in their lazy chunks. It then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
+- The production build splits the code loaded at startup into three eagerly preloaded chunks behind a tiny entry, so none nears the largest-chunk limit in `demo-bundle-budget.json`: `vendor` (the Web Awesome select and popup-menu registrations with their Lit and Floating UI runtime), `kerf` (the built `@kerfjs/ui` modules and the kerf core, plus every startup stylesheet), and `catalog` (the catalog shell and per-component demo modules). A chunk carries the CSS its modules import, so all startup CSS modules share the `kerf` chunk: the stylesheet stays one file with the cascade order a single-chunk build emits, and the chunk graph stays acyclic (`catalog` imports `kerf`, never the reverse). Only modules statically reachable from the entry qualify, so lazy-only dependencies stay in their lazy chunks. It then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
 
 The focused ListHeader route shows `xs`, `sm`, `m`, `l`, and `xl` labels at one
 semantic heading level. Its default `sm` style still matches `FieldLabel`.
 It also shows simultaneous badge and status indicators, with a conditional
 badge expression that may return `undefined`.
 
-Before handoff, inspect the actual captures for readability, context, alignment, clipping, spacing, responsiveness, focus, and obvious defects. Fix and recapture rather than treating the screenshot as proof by itself.
+Before handoff, inspect the actual captures for readability, context, alignment, clipping, spacing, responsiveness, focus, and obvious defects. Fix and recapture rather than treating the screenshot as proof by itself. Firefox and WebKit screenshots leave out `backdrop-filter`, so translucent chrome looks unblurred in them. Check the blur on a `recordVideo` frame instead (see [Accessibility › Chrome material](accessibility.md#chrome-material)).

package/docs/webawesome-theme.md

@@ -190,6 +190,13 @@ a panel, and a Web Awesome card containing details, using public components and
 no demo stylesheet. Browser tests cover repeated layers, actual compositing,
 text contrast, light/dark switching, narrow/wide layouts, and forced colors.
 
+The built-in close control of a `wa-dialog` or `wa-drawer` matches a borderless
+single `ToolbarControlGroup` button, the close a toolbar-composed dialog uses
+(see the list-detail dialog recipe): a 40px circle with no border and the
+neutral hover fill, in place of Web Awesome's 35px rounded square. The theme
+sizes it through the directly exported `close-button__base` part, so the
+default header and a toolbar-composed header present one close affordance.
+
 Add `class="hide-actions"` to a `wa-dialog` when the dialog supplies its own
 dismissal affordance and should omit Web Awesome's header action region. The
 theme sets `display: none` on the directly exported `header-actions` part; it

package/docs/workbench.md

@@ -198,7 +198,7 @@ and calls `wireNavStack` for animated push/pop and focus movement. See
   rightRail={{
     label: "Tickets",
     collapsed: ticketsCollapsed.value,
-    toolbar: { toggle: { action: "toggle-tickets", name: "tickets" } },
+    toolbar: { toggle: { action: "toggle-tickets", name: "Tickets" } },
     navStack: { id: "ticket-stack", label: "Tickets", views: ticketViews.value },
   }}
 />
@@ -221,7 +221,10 @@ and close. A panel's `toolbar` has these parts:
   toggle, which the Workbench renders: the per-side panel glyph,
   `aria-controls` naming the panel, `aria-expanded`, a "Show …"/"Hide …"
   label (or your localized `showLabel` / `hideLabel`), and the `data-action`
-  the app handles. It is always the last group.
+  the app handles. It is always the last group. `name` is the panel's
+  title-style name ("Navigator", "Build Output"): it becomes the toggle
+  group's accessible name and completes the "Show Navigator" / "Hide
+  Navigator" label, so it follows [the capitalization rule](./writing.md#capitalization).
 
 While a panel is closed, marked groups follow their open-panel zone order
 (`leading`, `center`, `trailing`), followed by its toggle:
@@ -249,8 +252,8 @@ toggle, so it never depends on a control it covers. An app's own
       label: "Navigator",
       title: <ToolbarText text="Navigator" />,
       leading: <NewFileGroup />,
-      trailing: <ToolbarControlGroup relocateOnCollapse label="Search files"><SearchButton /></ToolbarControlGroup>,
-      toggle: { action: "toggle-navigator", name: "navigator" },
+      trailing: <ToolbarControlGroup relocateOnCollapse label="Search Files"><SearchButton /></ToolbarControlGroup>,
+      toggle: { action: "toggle-navigator", name: "Navigator" },
     },
     content: <Files />,
     collapsed: navCollapsed.value,
@@ -297,7 +300,8 @@ The `Pane`s and `List`s the Workbench composes around your content are
 configurable the same way:
 
 - `mainPane` (`PaneConfig`: `contentElement`, `contentLabel`, `separators`,
-  `safeAreaEdges`, `chromeDividers`, `appearance`) configures the work area's
+  `safeAreaEdges`, `chromeDividers`, `appearance`, `deepInset`,
+  `scrollClearance`, `headerPresentation`, `tabIndex`, `outlined`) configures the work area's
   `Pane`, which exists whenever the work area has a toolbar, `mainHeader`, or
   `mainFooter`. Without that chrome, `appearance: "sunken"` paints the main
   region's own scroll surface;
@@ -500,7 +504,7 @@ presents as one, mirroring `wireSidebar`'s compact overlay:
     data-action="toggle-navigator"
     aria-controls="editor-left-rail"
     aria-expanded={String(!navCollapsed.value)}
-    aria-label={navCollapsed.value ? "Show navigator" : "Hide navigator"}
+    aria-label={navCollapsed.value ? "Show Navigator" : "Hide Navigator"}
   >
     <LucideIcon {...collapsiblePanelToggleIcon("left", navCollapsed.value)} />
   </button>