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

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/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>

package/docs/writing.md

@@ -0,0 +1,152 @@
+# Writing interface copy
+
+Kerf UI follows Apple's capitalization conventions for interface text.
+Apple's _Writing_ guidance asks for one style per UI element type, applied
+consistently, and its element guidance assigns those styles. This page is the
+package default, so every Kerf application, demo, and recipe uses the same
+rule. An application may replace it only through a written, product-wide
+style. It should never vary from one screen to the next.
+
+## Capitalization
+
+**Names are title style. Descriptions are sentence style.** Text that names a
+command, control, view, or field uses title style ("Save Draft", "Workspace
+Settings", "Release Date"). Text that describes, explains, reports, or asks
+uses sentence style ("Changes sync when you reconnect").
+
+| Element                                                                                             | Style                        | Examples                                               |
+| --------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------ |
+| Buttons, split-button and toolbar actions, link-style commands                                      | Title                        | Save Draft, Add to Favorites, Don’t Save, Log In       |
+| Menu items, menu group headings, popup-menu triggers                                                | Title                        | Copy Reference, Sort By, Recently Updated, New Folder… |
+| Segmented-control segments, `Select` and pop-up choices, tabs                                       | Title                        | List View, Last 30 Days, In Review                     |
+| Page, view, pane, dialog, and toolbar titles (`ToolbarText` titles), back labels                    | Title                        | Workspace Settings, Back to Inbox                      |
+| Group and list headers (`ListHeader`), table column headings                                        | Title                        | Saved Projects, Needs Attention, Last Modified         |
+| Catalog example and stack labels (`CatalogExample`, `CatalogExampleStack`)                          | Title                        | Heading Identity Stays Whole, Icon Trigger in a Group  |
+| Content item titles: the name an item or card shows                                                 | Title                        | Build Output, Work Area, Unsaved Changes               |
+| Field labels (`FieldLabel`, a field's `label`)                                                      | Title                        | Project Name, Release Date                             |
+| Region and landmark names (accessible names of panes, toolbars, groups, lists, tab bars)            | Title                        | Ticket Workbench, View Actions, Open Documents         |
+| Accessible names of icon-only controls                                                              | Title                        | More Actions, Clear Search                             |
+| `EmptyState`, `StateBanner`, alert, and notification titles that are fragments                      | Title, no ending punctuation | No Release Tasks, Migration Needs Review               |
+| The same titles written as complete sentences                                                       | Sentence, with punctuation   | Release tasks could not be refreshed.                  |
+| Checkbox, switch, and radio option text                                                             | Sentence                     | Show hidden files, Notify me about replies             |
+| Body copy, `description`, `detail`, hints, empty-state and banner detail, dialog and alert messages | Sentence, with punctuation   | Changes sync when you reconnect.                       |
+| Tooltips and help text                                                                              | Sentence                     | Copy the link to this ticket                           |
+| Placeholders                                                                                        | Sentence                     | Search tickets                                         |
+| Status lines, counts, and timestamps (`ToolbarText` status, `Badge`, `CornerStatus`)                | Sentence                     | Saved just now, 3 of 12 updated                        |
+| Progress labels (`LoadingSpinner` and `Skeleton` `label`): the operation under way                  | Sentence, trailing ellipsis  | Loading preview…, Refreshing release tasks…            |
+
+A name that a component composes into a longer label is a name too, so pass
+it in title style. A panel toolbar's `toggle: { action, name }` labels the
+toggle group with `name` and completes "Show …" / "Hide …" with it:
+`name: "Navigator"` gives "Show Navigator". Kerf UI never recapitalizes it.
+
+Data is never recapitalized. Names that a person or a system supplies keep
+their own spelling: file names, ticket titles, user names, and tags. So do
+code identifiers shown as text, such as a prop value a specimen is labeled
+with (`danger`, `transparent`). A content
+item that shows such data (a ticket subject, a message) keeps it as written;
+only a title the interface itself names is title style. `ContentItem`'s own
+`title` prop is a native tooltip, so it is sentence style. Keep a content
+item's `ariaLabel` equal to its visible title.
+
+### Title-style rules
+
+From the [Apple Style Guide](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web)
+(_capitalization_):
+
+- **Capitalize** the first and last word, whatever their part of speech.
+- **Capitalize** nouns, pronouns, verbs, adjectives, and adverbs, however
+  short: It, This, Your, Is, Are, Be.
+- **Capitalize** subordinating conjunctions such as If, and prepositions of
+  five letters or more: About, Between, Through.
+- **Capitalize** a preposition of any length that belongs to a phrasal verb
+  or acts as another part of speech: Start Up the Computer, Turn On, Log In to
+  the Server.
+- **Capitalize** the second word of a hyphenated compound: High-Level Events,
+  Pop-Up Menu. Built-in and Plug-in are the exceptions.
+- **Keep lowercase**:
+  - articles (a, an, the), unless one is the first word or follows a colon;
+  - coordinating conjunctions (and, but, or, nor, for, yet, so);
+  - _to_ in an infinitive (How to Start Your Computer);
+  - _as_ (Export a Document as a PDF);
+  - prepositions of four letters or fewer (at, by, for, from, in, into, of,
+    off, on, onto, out, over, to, up, with).
+- **Keep the brand's own spelling** for words that always start lowercase,
+  such as iPad, iOS, and macOS.
+
+### Sentence-style rules
+
+Capitalize the first word and proper nouns or adjectives only. End a complete
+sentence with punctuation. Leave a fragment without ending punctuation.
+Tooltips may omit the final period.
+
+### Related conventions
+
+- An ellipsis (…) ends a command or menu item that needs more input before it
+  acts: New Ticket…, Save As…. The dialog it opens repeats the command as its
+  title, without the ellipsis.
+- Label an action with its result. Prefer a verb: Publish Update, not OK.
+- Keep a control's accessible name equal to its visible label, or starting
+  with it.
+
+## Diagnostics
+
+`kerf-ui-doctor` reports `KUI-D040` (warning) when a string or template
+literal passed to a known title-style prop leaves a word lowercase that title
+style capitalizes. In a template literal it judges only the static words:
+`` `Edit ${name} shortcut` `` should be `` `Edit ${name} Shortcut` ``, and the
+interpolated value keeps its own spelling. The covered props are:
+
+- `ToolbarText` `text` when the text is a title: it has `headingLevel`, a
+  large size, or sits in a toolbar or panel `title`, `header`, or (unless small) `leading` slot;
+- `ListHeader`, `ListActionRow`, `SplitButton`, and `Combobox` `label`;
+- `CatalogExample` and `CatalogExampleStack` `label`;
+- `EmptyState` and `StateBanner` `title`;
+- `PopupMenu` `text` and item and heading labels, including submenus;
+- `SegmentedControl`, `Select`, and `TabNavigator` choice and tab labels;
+- `NavStack` view titles and `backText`, and `SplitView` `backLabel`;
+- `FieldLabel` text and the text of a `button` or `wa-button`;
+- the `name` of a panel toolbar's `toggle: { action, name }`;
+- 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
+  inside `Workbench`, `CollapsiblePanel`, and `NavStack` configuration, and
+  the `aria-label` of a landmark element (`section`, `nav`, `aside`, `main`,
+  `header`, `footer`, `form`, `search`) or landmark role;
+- the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or
+  `wa-radio-group`;
+- the accessible names of icon-only controls: `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.
+
+The check never judges sentence-style surfaces (including `wa-checkbox`,
+`wa-switch`, and `wa-radio` option text and the `LoadingSpinner` and
+`Skeleton` status labels), interpolated or other dynamic values, or text
+ending with `.`, `!`, or `?`. It skips a word joined to an interpolation, tokens containing digits, code, or paths, and
+lowercase-led brands such as iOS. It does not report capitalized short words,
+because Apple capitalizes a phrasal verb's particle. Suppress `KUI-D040` for a
+lowercase brand or product name. See [the doctor](./ui-doctor.md).
+
+## Sources
+
+- Apple Human Interface Guidelines,
+  [Writing](https://developer.apple.com/design/human-interface-guidelines/writing):
+  choose a capitalization style for each element type and use it consistently.
+- [Menus](https://developer.apple.com/design/human-interface-guidelines/menus)
+  and [The menu bar](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar):
+  menu items and multi-word menu titles use title-style capitalization.
+- [Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
+  and [Notifications](https://developer.apple.com/design/human-interface-guidelines/notifications):
+  a fragment title uses title style. A complete-sentence title and the
+  message use sentence style with punctuation.
+- [Offering help](https://developer.apple.com/design/human-interface-guidelines/offering-help):
+  tooltips use sentence case.
+- The archived OS X Human Interface Guidelines, _Use the Right Capitalization
+  Style in Labels and Text_. Title style covers menu titles and items, push
+  buttons, toolbar item labels, and labels that are not sentences, such as
+  group box and list headings. Sentence style covers checkbox and radio option
+  text and dialog messages.
+- [Apple Style Guide](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web),
+  _capitalization_: the title-style word rules above.