@kerfjs/ui 5.0.0-beta.55 → 5.0.0-beta.56

package/docs/layout.md

@@ -2,8 +2,8 @@
 
 Import `Pane` from `@kerfjs/ui/pane`. Browser-aware bundlers receive its CSS
 automatically; other consumers can import `@kerfjs/ui/pane.css`. Import
-`@kerfjs/ui/layout.css` as well when using the related content-item and control
-layout classes. The vocabulary deliberately describes structure rather than
+`@kerfjs/ui/layout.css` as well when using the `.kui-content` stack and control
+layout classes; place `ContentItem` children from `@kerfjs/ui/content-item`. The vocabulary deliberately describes structure rather than
 location: the same pane can be placed anywhere.
 
 ## Anatomy
@@ -29,10 +29,17 @@ top toolbar followed by secondary toolbar or status rows. A main area or dialog
 often omits the footer; a navigation pane commonly uses all three. Fixed chrome
 stays outside `.kui-pane__content`, which is the pane's only scroll owner.
 
+Tall fixed chrome can leave a short pane no room for its content (a small
+window, or text at 200%). `chromePlacement="auto"` keeps the header and footer
+pinned while the pane is at least 480px (30rem, so it scales with the text
+size) tall, and below that lets the whole pane scroll as one column, header,
+content, and footer together, so the content keeps its natural height. The
+default `fixed` always pins them.
+
 Pass any combination of logical sides to `separators`: `block-start`,
 `block-end`, `inline-start`, and `inline-end`. Every line is off by default and
 each enabled side uses `--kui-pane-separator-width` (1px) and
-`--kui-pane-separator-color` (`--kui-color-border`). Logical sides keep pane
+`--kui-pane-separator-color` (`--kui-color-neutral-border-normal`). Logical sides keep pane
 boundaries correct in both left-to-right and right-to-left layouts.
 
 A pane is safe-area aware. Its background and separators paint through a
@@ -45,18 +52,8 @@ same logical sides as `separators`; all four by default, `[]` to opt out). See
 
 `.kui-content` is a vertical stack with a 24px gap between major children.
 Sections may contain adjacent `ListItem` rows without adding another major gap.
-Ordinary surface-like children use `.kui-content-item` and own their complete
-geometry:
-
-- 8px inline margin from the pane edge
-- 1px border, transparent by default
-- 8px internal padding and 8px internal gap
-- `calc(1px + remify(11px))`, or 12px, rounded corners
-
-Use `.kui-content-item--pill` for the 22px pill radius expressed as
-`calc(1px + remify(21px))`. Consumers can make a content item visible without
-changing its geometry by setting `--kui-content-item-border` and
-`--kui-content-item-background`.
+Ordinary surface-like children are `ContentItem`s and own their complete
+geometry (see [Content items](#content-items)).
 
 Nested selection and hover highlights stay concentric and match their owning
 control's shape. Their inner radius is the outer radius minus the full inset,
@@ -72,20 +69,63 @@ inline gutter instead of nesting them inside another padded content item. A
 conditional `StateBanner` remains visibly distinct because it communicates
 semantic status.
 
+## Content items
+
+Render an ordinary surface-like `.kui-content` child with `ContentItem` from
+`@kerfjs/ui/content-item` (browser-aware bundlers receive its CSS automatically;
+`@kerfjs/ui/layout.css` and `@kerfjs/ui/content-item.css` both deliver it). It
+owns its complete geometry:
+
+- 8px inline margin from the pane edge
+- 1px border, transparent by default
+- 8px internal padding
+- `calc(1px + remify(11px))`, or 12px, rounded corners
+
+```tsx
+import { ContentItem } from "@kerfjs/ui/content-item";
+
+<Pane label="Inspector">
+  <ContentItem>{details}</ContentItem>
+  <ContentItem frame="framed">{pendingChanges}</ContentItem>
+  <ContentItem shape="pill">{summary}</ContentItem>
+</Pane>;
+```
+
+`frame="framed"` paints the standard neutral border in the 1px the item always
+reserves, so framed and unframed items share the same geometry. Frame an item
+only when it marks a real distinction and must read as visibly bounded; do not
+frame it to make it "look contained". `shape="pill"` selects the 22px pill
+radius expressed as `calc(1px + remify(21px))`. There is deliberately no filled
+variant: a lowered, filled surface is `SunkenPanel`, and bare text that only
+needs to align with neighboring items is `ListInsetText`. Safe `data-*`
+metadata goes in `rootAttributes`. Pass `ariaLabel` only for a distinct named
+region (`role="region"`), and `focusTarget` to make the item a programmatic
+focus target (`tabindex="-1"`), for example a NavStack view's `data-nav-focus`
+target.
+
+The rendered classes — `.kui-content-item`, `.kui-content-item--framed`, and
+`.kui-content-item--pill` — stay public for the rare element that must carry the
+geometry itself (for example a `<ul>` list or a `Text` paragraph in an
+application-owned adapter). Prefer `ContentItem` everywhere else so the framing
+choice is typed. `npm run check:guidance` rejects a plain
+`<div class="kui-content-item">` in the package's examples, browser fixtures,
+and UX catalog, since that div is exactly what `ContentItem` renders.
+
 ## Public roles and tokens
 
-| Need                                     | Class                     | Token / default                                                             |
-| ---------------------------------------- | ------------------------- | --------------------------------------------------------------------------- |
-| Unpadded header/content/footer structure | `Pane`, `.kui-pane`       | —                                                                           |
-| Scrolling pane content                   | `.kui-pane__content`      | —                                                                           |
-| Optional logical-edge separators         | `Pane.separators`         | `--kui-pane-separator-width: 1px`                                           |
-| Safe-area sides a pane may pad           | `Pane.safeAreaEdges`      | `--kui-safe-area-*: env(safe-area-inset-*)`, routed as `--kui-edge-inset-*` |
-| Major vertical rhythm                    | `.kui-content`            | `--kui-layout-content-gap: 24px`                                            |
-| Self-contained child geometry            | `.kui-content-item`       | 8px margin + 1px border + 8px padding                                       |
-| Pill child                               | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px`                                            |
-| Related controls                         | `.kui-control-cluster`    | `--kui-layout-control-gap: 8px`                                             |
-| Inline metadata                          | `.kui-inline-metadata`    | `--kui-layout-metadata-gap: 4px`                                            |
-| Explicit scroll owner outside a pane     | `.kui-scroll-owner`       | `overflow: auto`                                                            |
+| Need                                     | Class                        | Token / default                                                    |
+| ---------------------------------------- | ---------------------------- | ------------------------------------------------------------------ |
+| Unpadded header/content/footer structure | `Pane`, `.kui-pane`          | —                                                                  |
+| Scrolling pane content                   | `.kui-pane__content`         | —                                                                  |
+| Optional logical-edge separators         | `Pane.separators`            | `--kui-pane-separator-width: 1px`                                  |
+| Safe-area sides a pane may pad           | `Pane.safeAreaEdges`         | `--kui-safe-area-*: env(safe-area-inset-*)`, routed by each layout |
+| Major vertical rhythm                    | `.kui-content`               | `--kui-layout-content-gap: 24px`                                   |
+| Self-contained child geometry            | `ContentItem`                | 8px margin + 1px border + 8px padding                              |
+| Pill child                               | `ContentItem shape="pill"`   | `--kui-layout-pill-radius: 22px`                                   |
+| Visibly framed child                     | `ContentItem frame="framed"` | neutral 1px border, same geometry                                  |
+| Related controls                         | `.kui-control-cluster`       | `--kui-layout-control-gap: 8px`                                    |
+| Inline metadata                          | `.kui-inline-metadata`       | `--kui-layout-metadata-gap: 4px`                                   |
+| Explicit scroll owner outside a pane     | `.kui-scroll-owner`          | `overflow: auto`                                                   |
 
 The component layer applies the same contract to `Toolbar`, `ListHeader`,
 `ListItem`, `Toolbar`, `StateBanner`, `ValueTable`,
@@ -307,8 +347,8 @@ selected sides; the control wrapper applies its 8px outer margin only on
 selected sides. Every direct child of `ListInsetControl` grows to fill the row
 (a `Select`, a `wa-input`, or a `wa-button` spans the full inset width), and
 several children share the row with an 8px gap; stack controls vertically with
-a `List` using `controlInsets` instead. `ListInsetText.horizontalOnly` remains a deprecated alias for
-`sides="rl"`; an explicit `sides` value takes precedence.
+a `List` using `controlInsets` instead. Pass `sides="rl"` for tight text that
+keeps the horizontal inset without adding vertical box space.
 
 `--kui-space-s` (12px) and `--kui-space-xl` (32px) exist but are **off the
 canonical rhythm** — reach for them only as a deliberate exception, never as a

package/docs/nav-stack.md

@@ -49,11 +49,55 @@ views.value = [
 `NavStack` renders every entry stacked, the last one active and the rest kept
 mounted (so their DOM state survives) but hidden. Each entry carries a
 `key` (stable identity), `content`, an optional `title`, optional per-view
-`toolbar` actions, and an optional per-view `bottomToolbar`. The component-level
+`leading`, `center`, and trailing `toolbar` groups for the top toolbar, and an
+optional per-view `bottomToolbar`. The component-level
 `bottomToolbar` remains a persistent fallback for views that do not provide one.
 The back control appears automatically once the stack has more than one entry;
 `wireNavStack`'s `onBack` is where the app pops its own signal.
 
+## The top toolbar
+
+The top chrome is a real `Toolbar`, so it follows the same zone,
+group, and responsive rules as every other toolbar. Its leading zone holds the
+back control (a borderless `ToolbarControlGroup`, shown once the stack has
+depth), then the active view's `leading` groups, then the view's `title` as a
+`ToolbarText`. The view's `center` fills the center zone and its `toolbar`
+fills the trailing zone. Give each zone `ToolbarControlGroup`s or `ToolbarText`,
+as in any toolbar.
+
+Configure the toolbar with `toolbarConfig` instead of styling it:
+
+```tsx
+<NavStack
+  id="mail"
+  label="Mail"
+  views={views.value}
+  backText={previousTitle}
+  toolbarConfig={{
+    headingLevel: 1,
+    titleSize: "xlarge",
+    dividerSides: "b",
+    responsive: "wrap",
+  }}
+/>
+```
+
+- `toolbarConfig` forwards the `Toolbar` configuration (`dividerSides`,
+  `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) and adds
+  `label` (the toolbar's accessible name), `titleSize` (the title's
+  `ToolbarText` size, default `large`), and `headingLevel` (expose the title as
+  a heading; default a plain span). The defaults keep the stack's own chrome:
+  no divider, one 44px control band, and the top and side safe-area edges
+  claimed.
+- `backIcon` replaces the default chevron-left icon. `backText` adds visible
+  text beside it (for example, the previous view's title); visible text names
+  the control, so `backLabel` applies only to the icon-only control.
+
+The catalog's **Configured toolbar** example shows these together: a level-2
+heading title over a bottom divider, leading and center groups on the root
+view, a trailing group on the pushed view, and `backText` set to the previous
+view's title.
+
 Focus follows the controlled stack automatically. On push, `wireNavStack`
 remembers the focused descendant of the departing view and moves focus into the
 new top view. On pop it restores that exact descendant when it still exists. A

package/docs/recipes.md

@@ -57,8 +57,8 @@ component variables.
 [Open the recipe](../ux-demo/?component=recipe-navigation-sidebar) · [TSX source](../ux-demo/recipes/navigation-sidebar.tsx)
 
 One unpadded `.kui-pane` owns toolbar/content/footer structure. Its
-`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and other
-`.kui-content-item` children own their 8px margin, 1px border, and 8px padding.
+`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and
+`ContentItem` children own their 8px margin, 1px border, and 8px padding.
 Rows and footer toolbar groups remain 44px tall. The app owns routes,
 permissions, labels, selection, valid section counts and their localized
 `countLabel` phrases, non-count badge content, disclosure state, and revealed
@@ -205,7 +205,8 @@ Chromium, Firefox, and WebKit by `tests/browser/collapsible-sidebar-recipe.spec.
   `@kerfjs/ui/webawesome.css`.
 - Compose, don't style. A recipe ships no stylesheet, sets no inline style, and
   names no class outside the published layout vocabulary (`.kui-content`,
-  `.kui-content-item`, …) and themed Web Awesome classes; it configures
+  `.kui-control-cluster`, …) and themed Web Awesome classes — a content item is
+  a `ContentItem`, not a hand-written `.kui-content-item`; it configures
   components through props, `rootAttributes`, and tokens. When a recipe needs a
   capability no component offers, record it as a component gap rather than
   papering over it with CSS. `npm run check:recipes` enforces these rules on

package/docs/split-view.md

@@ -53,11 +53,55 @@ const selected = signal<string | null>(null);
   app's selection). This is the portrait-tablet / handset presentation; as a
   dialog the compact form is a full-screen or large partial-cover modal.
 
+## Configuring the list region and the compact stack
+
+`resizable` forwards the list's `ResizableRegion` configuration alongside
+`size`, `min`, and `max`: `separator` (`"hidden"` keeps the resize hit target
+but paints no line), `handleIcon`, `contentOverflow`, and collapse —
+`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`, and
+`restorePosition`. A collapsed list snaps to zero width, renders `inert` and
+`aria-hidden`, and the detail fills the split; the app owns the `collapsed`
+flag and renders the restore control (usually a `FloatingToolbar`). Omitted
+options keep the region's defaults.
+
+```tsx
+resizable={{
+  size: listWidth.value,
+  min: 220,
+  max: 480,
+  collapsed: listCollapsed.value,
+  restoreControl: <ShowThreadsToolbar />,
+}}
+```
+
+`compactStack` configures the compact `NavStack`: `toolbarConfig`, `backIcon`,
+`backText`, `hideToolbar`, and the persistent `bottomToolbar` forward to the
+stack, and `list` / `detail` give each view its own top-toolbar groups
+(`leading`, `center`, trailing `toolbar`) and `bottomToolbar`:
+
+```tsx
+compactStack={{
+  backText: "Threads",
+  toolbarConfig: { headingLevel: 1 },
+  list: { toolbar: <ComposeGroup /> },
+  detail: { toolbar: <ReplyGroup />, bottomToolbar: <MessageActions /> },
+}}
+```
+
 The catalog's **Interactive compact drill-down** example exercises this exact
 controlled flow: a list action sets the selected message, `detailActive` pushes
 its detail, and the wired Back action clears the selection to reveal the
-preserved list. Use the same structure in application demos so compact examples
-show the interaction rather than rendering a disconnected detail state.
+preserved list. It also forwards `compactStack`: a level-2 heading title over
+a bottom divider, a Compose group on the list view, and a Reply group plus a
+bottom toolbar on the detail. Use the same structure in application demos so
+compact examples show the interaction rather than rendering a disconnected
+detail state.
+
+The catalog's **Resizable, collapsible list** example forwards `resizable`: a
+hidden separator that still resizes the list (its committed width comes back
+through `wireResizableRegions`' `onCommit` into the app's size signal), a Hide
+control in the list's own toolbar, and a `FloatingToolbar` restore control in
+the split's bottom-start corner.
 
 Compose the interactive wiring from the existing helpers — `SplitView` adds no
 wire of its own.

package/docs/tab-scaffold.md

@@ -44,7 +44,8 @@ const dispose = wireTabScaffold(root, {
 });
 ```
 
-Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, and `content`. The
+Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, optional `badge`
+and `badgeLabel` (see [Tab badges](#tab-badges)), and `content`. The
 bottom bar paints through the home-indicator safe area and pads for it and for
 the side insets, while each scene pads for the top and side insets (a scene
 whose only child is a `NavStack` or `Pane` lets that child own them; see
@@ -52,3 +53,51 @@ whose only child is a `NavStack` or `Pane` lets that child own them; see
 truncate horizontally with an ellipsis when a destination name exceeds its
 share of the bar. On larger device classes, promote the tab set to a
 `Workbench` rail or a persistent sidebar instead of a bottom bar.
+
+## Tab badges
+
+Give a tab a `badge` (a count or short string such as `3`, `"99+"`, or
+`"New"`) to show the iOS tab-bar badge: a compact, solid `danger` `Badge` at the
+top-trailing corner of the tab's icon, growing outward as the text lengthens
+(without an icon it sits above the label). The badge is decorative
+(`aria-hidden`); its meaning reaches assistive technology through `badgeLabel`,
+which the tab folds into its accessible name as `"<label>, <badgeLabel>"`:
+
+```tsx
+{
+  id: "inbox",
+  label: "Inbox",
+  icon: <LucideIcon icon={Inbox} name="inbox" />,
+  badge: unread.value,
+  badgeLabel: `${unread.value} unread`,
+  content: <InboxStack />,
+}
+```
+
+`badgeLabel` defaults to the badge text itself, so supply a localized phrase
+whenever the bare text would be ambiguous. Omitting `badge` (or passing an
+empty string or a non-finite number) renders no badge and leaves the tab's name
+as its label; `0` renders, so pass `undefined` when a count should disappear.
+Keep the text short — clamp large counts (`"99+"`) in the app. The tone follows
+the platform convention and is fixed; do not restyle the badge.
+
+### Dot badges
+
+For new content without a count, pass `badge: true`. The tab shows the iOS
+tab-bar dot — an 8px solid `danger` `Badge` (`size="dot"`) centered on the
+icon's top-trailing corner (above the label without an icon). A dot has no
+text to fall back on, so `badgeLabel` is required by the types:
+
+```tsx
+{
+  id: "feed",
+  label: "Feed",
+  icon: <LucideIcon icon={Rss} name="rss" />,
+  badge: hasNewPosts.value ? true : undefined,
+  badgeLabel: "New activity",
+  content: <FeedStack />,
+}
+```
+
+The tab's accessible name becomes `"Feed, New activity"`. Pass `undefined` to
+clear the dot; `false` is not a badge value.

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 `TabScaffold.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 use `CssForegroundColor` (foreground tokens via `uiColor()` or `foregroundColorVar()`; fill aliases such as `uiColor('success')` 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 `TabScaffold.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 use `CssForegroundColor` (foreground tokens via `uiColor()` or `foregroundColorVar()`; 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.                                                                 |
 
 `KerfUiContent` lets conditionals and mapped component collections be direct
 siblings without an otherwise-unnecessary `Fragment`:
@@ -123,7 +123,7 @@ move errors into casts without making the integration safer.
   keyword; replace raw Skeleton dimensions with `px`/`rem`/`em`/`pct` builders;
   and replace raw choice colors with a foreground token such as
   `uiColor('success-on-quiet')` or an app-owned `foregroundColorVar()`.
-  `SelectChoice.color` rejects fill aliases (`uiColor('success')`) and
+  `SelectChoice.color` rejects fill tokens (`uiColor('success-fill-quiet')`) and
   unqualified `colorVar()` values because a fill paints a nearly invisible
   icon.
 - Remove `style` from `ListItem` and `ListActionRow`; use `className`, public

package/docs/ux-demo.md

@@ -1,6 +1,6 @@
 # UX catalog contract
 
-Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
+Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server reloads component source edits without a restart: component entries still load through their `dist/browser` wrappers, so each component's reachable CSS is exercised as consumers receive it, but the JavaScript those wrappers re-export (and every other `@kerfjs/ui` subpath) resolves to `src/`, and CSS resolves to `src/` as well. A component that gains a new CSS dependency needs a restart, because the wrapper listing its stylesheets is regenerated only by the build. Production demo builds, previews, and the browser tests use `dist/`. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
 
 Every Playwright entry point builds current source before the preview server
 starts. `npm run test:e2e -- tests/browser/row.spec.ts` and a direct focused
@@ -51,6 +51,6 @@ 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, 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 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.
 
 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.

package/docs/webawesome-theme.md

@@ -176,8 +176,7 @@ their open state uses the independent `rotate` property.
 
 That scale applies to each Web Awesome component's intrinsic glyph and is
 independent of Kerf `DisclosureArrow`, whose default box is 18px relative to
-the root font size and whose consumer override is
-`--kui-disclosure-arrow-size`.
+the root font size and whose consumer override is its typed `size` prop.
 
 Tooltip and Popover use arrowless floating surfaces by default, matching Hot
 Sheet 2. The theme sets Web Awesome's public `--wa-tooltip-arrow-size` token to

package/docs/workbench.md

@@ -107,7 +107,13 @@ an optional `label`. Common shell behavior is configured rather than restyled:
   defaults to two less than the overlay z-index (39), so they sit beneath
   every overlay: an open overlay covers another panel's restore control as
   it covers the rest of the work area, and a collapsed overlay, which drops
-  its pointer events, leaves the control beneath it usable;
+  its pointer events, leaves the control beneath it usable. While a rail
+  overlay is open (static, or a responsive one whose breakpoint applies), the
+  work area's floating controls — restore corners and any `FloatingToolbar`
+  in `main` — are also hidden outright (out of the tab order and the
+  accessibility tree), so they can never paint over the rail whatever
+  stacking context the app gives the work area; they return as it closes.
+  The rail's own floating controls stay, and a drawer overlay hides nothing;
 - `restoreControl` places an application-owned restore affordance in a
   corner of the Workbench itself while the panel is collapsed. Prefer a
   `toolbar.toggle`, which the Workbench relocates for you; keep
@@ -130,8 +136,8 @@ an optional `label`. Common shell behavior is configured rather than restyled:
   carrying `collapsiblePanelToggleIcon(side, true)` — rather than a bare
   button. To give it `FloatingToolbar`'s toolbar role and floating look, wrap
   that group in a `FloatingToolbar` whose `position` matches the corner: the
-  corner owns the inset (it sets `--kui-floating-toolbar-inset` to 0), so the
-  toolbar floats from the corner instead of doubling it.
+  corner owns the inset (it zeroes the toolbar's default inset), so omit
+  `inset` there and the toolbar floats from the corner instead of doubling it.
 
 - `resizable: true | { min, max }` opts the panel in to drag and keyboard
   resizing, driven by `wireWorkbench` (off by default).
@@ -154,10 +160,12 @@ and close. A panel's `toolbar` has four parts:
 - `constant` — groups that stay available either way. They trail the panel's
   toolbar while it is open and move to the work area's toolbar while it is
   closed.
-- `toggle: { action, name }` — the standard collapse toggle, which the
-  Workbench renders: the per-side panel glyph, `aria-controls` naming the
-  panel, `aria-expanded`, a "Show …"/"Hide …" label, and the `data-action`
+- `toggle: { action, name, showLabel?, hideLabel? }` — the standard collapse
+  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.
+- `center` — optional panel-only center content.
 
 While a panel is closed, its `constant` groups and then its toggle go to:
 
@@ -198,9 +206,37 @@ The work area's `Pane` can carry more fixed chrome: `mainHeader` renders under
 line or a resource toolbar), each divided from the scrolling `main`.
 `mainHeaderPlacement` and `mainFooterPlacement` (`"fixed"` by default, or
 `"scroll"`) let that header or footer chrome scroll away with `main` instead —
-useful where large text would leave pinned chrome little room. `mainToolbar` also
-takes the `Toolbar`'s `responsive` / `responsiveAt` policy; `responsive: "wrap"`
-keeps a long title whole and wraps its actions below it.
+useful where large text would leave pinned chrome little room. `"auto"` keeps
+it pinned while the work area is tall enough and lets it scroll with `main`
+when the work area is short (the Pane's `chromePlacement="auto"`; it applies to
+the pinned header and footer together).
+
+Every toolbar the Workbench composes — `mainToolbar`, `mainBottomToolbar`, and
+each panel's `toolbar` — takes the `Toolbar`'s configuration (`ToolbarConfig`):
+`dividerSides`, `centerAlign`, `responsive`, `responsiveAt`, and
+`safeAreaEdges`. Configure the toolbar through these props rather than styling
+it. By default a panel toolbar keeps its bottom divider, and the work area draws
+one divider under its header chrome and one over its footer chrome, wherever
+that chrome ends; set `dividerSides: ""` to drop a toolbar's divider, for
+example. `responsive: "wrap"` keeps a long title whole and wraps its actions
+below it. `mainBottomToolbar` also takes a `center`. A panel's
+`restorePosition` also places its floating restore controls.
+
+The `Pane`s and `List`s the Workbench composes around your content are
+configurable the same way:
+
+- `mainPane` (`PaneConfig`: `contentElement`, `contentLabel`, `separators`,
+  `safeAreaEdges`) configures the work area's `Pane`, which exists whenever the
+  work area has a toolbar, `mainHeader`, or `mainFooter`;
+- a panel's `pane` configures the `Pane` a `toolbar` panel's `content` renders
+  in — for example `{ contentElement: "nav", contentLabel: "Files" }` for a
+  navigator rail;
+- `mainHeaderList` / `mainFooterList` (`ListConfig`: `gap`, `hAlign`,
+  `vAlign`, `dividerSides`, `textInsets`, `controlInsets`) configure the
+  `List`s holding `mainHeader` / `mainFooter`.
+
+An omitted or `undefined` field keeps today's default, including the header
+and footer dividers described above.
 
 Size a rail so its title and groups fit at its narrowest (a resizable rail's
 `min`); a toolbar that cannot hold them drops the title rather than

package/llms.txt

@@ -102,11 +102,16 @@ the folder modules, and CSS only imports their owner stylesheets.
   without an application customization layer. Before adding `padding`, `margin`,
   `width`, `height`, `border`, `background`, a wrapper card, or a decoration,
   check whether the component, pane, or content-item already owns it. Prefer a
-  component prop or documented `--kui-*` token. CSS for genuinely new structure
+  component prop — `FloatingToolbar inset`, `DisclosureArrow size`, `ListHeader
+headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
+  visibly bounded content item — over overriding its `--kui-*` token. CSS for genuinely new structure
   belongs to the application-owned component that renders it and must not select
   nested Kerf or Web Awesome components.
 - **Never double-inset.** A `.kui-pane` has no padding; its `.kui-content` children
-  own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
+  own the geometry (8px inline margin + 1px border + 8px padding). Render an
+  ordinary surface-like child as `ContentItem` (`@kerfjs/ui/content-item`) with
+  typed `frame` (`none`/`framed`) and `shape` (`rounded`/`pill`) props instead
+  of hand-writing `<div class="kui-content-item">`. Do not add a
   container padding on top of a content-item's own margin — pick one owner. Use
   `.kui-content` for 24px major vertical rhythm.
 - **Opt into document globals explicitly.** Import `@kerfjs/ui/document.css`
@@ -129,7 +134,7 @@ the folder modules, and CSS only imports their owner stylesheets.
   `@kerfjs/ui/css-values` builders; raw CSS strings are rejected. Use `flex()`
   for List flex, typed lengths for Skeleton geometry, and
   foreground colors for choice icons: `uiColor()` with an `*-on-*`/text token
-  or `foregroundColorVar()`; fill aliases such as `uiColor('success')` do not
+  or `foregroundColorVar()`; fill tokens such as `uiColor('success-fill-quiet')` do not
   type-check. These brands are intentionally
   not interchangeable; rows use classes/tokens/props rather than raw `style`.
 - **Use `Grid` for a fixed positive count of equal-width columns.** It uses
@@ -170,7 +175,21 @@ the folder modules, and CSS only imports their owner stylesheets.
   label uses the same uppercase xs/650 treatment and its label and hint share
   that 9px alignment.
 - `Select` requires a visible `label` or an `ariaLabel` for a visually hidden
-  accessible name. The package names the internal combobox, including custom
+  accessible name. Set `multiple` with an array `value` for any number of
+  choices: the popup stays open while choices toggle and closes on an outside
+  press or Escape, and the closed control summarizes the chosen labels. A
+  toolbar filter menu adds `selectedPresentation="icon-only"` and a fixed
+  `triggerIcon`: the trigger shows that icon plus a count badge while any
+  choice is chosen, and its accessible name ends with the chosen labels.
+  Icon-only Selects (single or multiple) and icon-only `PopupMenu`s show an
+  `aria-hidden` Web Awesome help tag repeating that name (and a Select's
+  choice) on hover and keyboard focus, hidden while the popup is open; the
+  register import installs it, so do not add a `title` or tooltip of your own.
+  The same installer tags an icon-only `<button>` or link inside a
+  `ToolbarControlGroup` named by `aria-label` (no visible text or `title`);
+  import `@kerfjs/ui/help-tags/register` once when a toolbar has such buttons
+  but no registered Select or PopupMenu.
+  The package names the internal combobox, including custom
   selected content; consumers do not need shadow-DOM naming workarounds.
   Import `select/register` once for the canonical animation lifecycle: stale
   close/show completions cannot override a later request. Consumers must not
@@ -227,6 +246,11 @@ the folder modules, and CSS only imports their owner stylesheets.
   scrolling `.kui-pane__content`, optional `.kui-pane__footer`). A visible pane owns
   its collapse control; a hidden pane's restore moves to the adjacent main
   toolbar's matching edge — no icon-only rail. Keep one scroll owner per region.
+  While a side overlay is open (a Workbench rail overlay, a `wireSidebar` compact
+  overlay, an overlay `CollapsiblePanel` or horizontal `ResizableRegion`), the
+  layout hides the covered work area's `FloatingToolbar`s and restore corners
+  itself (unfocusable, out of the accessibility tree) until it closes — do not
+  hide them from overlay state yourself.
 - **State and behavior live in the app.** Components take semantic `data-action`
   strings and controlled values; wire them once with `delegate()`/`delegateActions()`
   or the disposer-returning `wire…` helpers, and own domain copy, transport, and
@@ -290,6 +314,10 @@ the folder modules, and CSS only imports their owner stylesheets.
 - **Use `Badge` for compact non-interactive metadata.** Configure its semantic
   tone, appearance, shape, and size instead of creating badge CSS in an app or
   consuming component. Use a real button or link for interactive content.
+  For new content without a count, use the text-free `size="dot"` form: it
+  takes no children, and needs a `label` (announced as an image) or
+  `ariaHidden` when its owner announces it. A `TabScaffold` tab shows the dot
+  with `badge: true` plus its required `badgeLabel`.
 
 ## Public exports