@kerfjs/ui 5.0.0-beta.54 → 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`,
@@ -96,6 +136,11 @@ also keeps 8px of root-scaled block padding independently of its semantic inline
 inset. Most interactive rows and toolbar groups are 44px tall.
 Toolbar groups reserve a real 1px outer border around a 42px inner area, even
 when their border and background are transparent.
+A `Toolbar` lays its zones out against one 44px control band at its top: an
+item no taller than the band is centered in it by its own size, and a taller
+item (a wrapped title, a second trailing row) starts at the band's top and
+grows down, so it never moves the other controls. A wrapped `ToolbarText`
+centers its first line in the band.
 Trailing icon actions share one axis: a toolbar control centers its glyph in
 that 44px slot at the 8px inline margin, and a `ListHeader` action centers its
 fitted 36px square in a slot of the same size (a transparent hit layer extends
@@ -302,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

@@ -9,9 +9,9 @@ ship no stylesheet of their own and are not new monolithic components.
 Copy the recipe source together with the catalog-independent
 [`mount-recipe.ts`](../ux-demo/recipes/mount-recipe.ts) adapter. It mounts the
 controller at one stable application root, uses `delegateActions()` for recipe
-commands, forwards form and dialog lifecycle events, wires resize commits with
-the public `onCommit` callback, retains every disposer, and returns one
-idempotent disposer:
+commands, forwards form and dialog lifecycle events, runs the recipe's own
+`wire()` (for example `wireWorkbench` or `wireSidebar`), retains every
+disposer, and returns one idempotent disposer:
 
 ```ts
 import { createRecipe } from "./navigation-sidebar.js";
@@ -31,32 +31,34 @@ specific dispatch; either way, wire once at a stable root and retain disposal.
 [Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx)
 
 A filling `List` (`fill`, with the recipe's `data-*` markers through
-`rootAttributes`) stacks the app-bar `Toolbar` above a `Row` that places
-controlled `ResizableRegion` navigation and inspector panes around a content
-`Pane` that a one-column `Grid` grows to fill. Each region's lone `Pane` fills
-the region's full height, so it reaches the bottom edge the separator does.
-Only those three real panes own a
-`.kui-pane__content` scroll owner; no frame `Pane` wraps the layout in a scroll
-owner that never scrolls. Each pane lists the screen edges it reaches in
-`safeAreaEdges` (the bottom plus its outer side, or both sides when it is the
-only pane shown), and the app-bar `Toolbar` claims the top edge and both sides
-with its own `safeAreaEdges`, so it clears the status area. Below desktop sizes the app reads `deviceClass()` and shows one
-pane at a time, switched by a pressed-state `ToolbarControlGroup`. The recipe
-owns the shell topology; the app owns routing, responsive pane visibility,
-sizes, persistence, and data.
-Keep each visible pane's collapse action in its own toolbar. Once hidden, put
-its restore action in the adjacent main toolbar on the same logical edge:
-leading for an inline-start sidebar and trailing for an inline-end inspector.
-Collapse the pane completely rather than preserving an empty icon rail.
-Adapt only public `--kui-layout-*` and component variables.
+`rootAttributes`) stacks the app-bar `Toolbar` above a `Workbench`
+(`@kerfjs/ui/workbench`): resizable navigation and inspector rails around the
+task list. Each rail composes its own panel toolbar — a default-size title and
+the standard hide toggle — and the work area's `mainToolbar` carries the xl
+view title. While a rail is hidden, `Workbench` relocates its show toggle into
+the work-area toolbar on the same logical edge (leading for the navigation
+rail, trailing for the inspector), and `wireWorkbench` hands focus between the
+two positions. Collapse a rail completely rather than preserving an empty icon
+rail. Only the three real panes own a `.kui-pane__content` scroll owner; no
+frame `Pane` wraps the layout in a scroll owner that never scrolls, and the
+app-bar `Toolbar` claims the top edge and both sides with its own
+`safeAreaEdges`.
+
+On a narrow container the rails overlay the task list one at a time instead of
+squeezing it, leaving a 44px strip on the far side that dismisses the overlay
+(`responsiveOverlayAt`, on by default; `compactOverlay: 'full'` covers the
+whole width). The app owns each rail's collapsed and size signals — which
+`wireWorkbench` keeps in sync with resizing and overlay dismissal — plus
+routing, persistence, and data. Adapt only public `--kui-layout-*` and
+component variables.
 
 ## Navigation sidebar
 
 [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
@@ -75,19 +77,23 @@ controls relocate without changing focus order.
 
 [Open the recipe](../ux-demo/?component=recipe-list-detail-dialog) · [TSX source](../ux-demo/recipes/list-detail-dialog.tsx)
 
-The production Web Awesome dialog owns modal focus, Escape, its labeled header,
-and its close control; the thin recipe adapter restores the invoking control
-after the hide event. `DialogSurface` chooses the large modal with no body
-inset, because `SplitView` and its rows own list geometry, and a comfortable
-footer inset for the record actions. On roomy devices `SplitView` shows the
-project list beside its detail; each pane opens with a `ListHeader` on one
-shared line, and the dialog title, both headers, and the list text share the
-17px text edge while the `ValueTable` keeps the 8px outer margin. On compact
-devices the dialog becomes a full-screen sheet and `SplitView` becomes a
+A list-detail dialog is laid out like a `Workbench` with a left sidebar: on
+roomy devices the list is a full-height sidebar and the detail is a full-height
+main column, each a `Pane` with its own top `Toolbar`. The sidebar's toolbar
+carries its quiet default-size title (and it may add a bottom toolbar for
+sidebar-only actions); the main column's toolbar carries the dialog's primary
+extra-large title and the close control, and its footer carries the record
+actions. The Web Awesome dialog therefore renders `without-header` there —
+its label still names the modal — and the close button uses
+`data-dialog="close"`. Web Awesome keeps modal focus and Escape, and the thin
+recipe adapter restores the invoking control after the hide event.
+`DialogSurface` chooses the large modal with no body inset, because the panes
+own their geometry. On compact devices the dialog becomes a full-screen sheet
+with its own labeled header and footer actions, and `SplitView` becomes a
 `NavStack` drill-down whose back control the application pops. The
 application owns open state, selection, the pushed detail, dismissal policy,
-and record actions. Do not rebuild the dialog or reach into private shadow
-parts.
+and record actions. Do not put the primary title in a header spanning both
+columns, rebuild the dialog, or reach into private shadow parts.
 
 ## Composer form
 
@@ -162,11 +168,12 @@ which values are still unknown.
 
 A mini app frame whose left navigation rail and bottom activity drawer are
 standalone `CollapsiblePanel`s (`@kerfjs/ui/collapsible-panel`) driven by
-`wireSidebar` (`@kerfjs/ui/wire-sidebar`). `CollapsiblePanelToggle` supplies the
-standard per-side glyph: a collapse toggle lives inside each panel, and the
-panel's expand toggle shows only while it is collapsed, so exactly one control
-owns each action and a collapsed panel is still reachable. The rail's expand
-toggle sits in the always-visible main header; the drawer's is a
+`wireSidebar` (`@kerfjs/ui/wire-sidebar`). Each panel takes a `toolbar` — a
+title plus the standard per-side toggle — so the hide control lives in the
+panel's own header, and `CollapsiblePanelRelocated` renders the matching show
+control only while the panel is collapsed, so exactly one control owns each
+action and a collapsed panel is still reachable. The rail's relocated toggle
+leads the always-visible main header; the drawer's sits in a
 `FloatingToolbar` passed as the drawer's own `restoreControl`, which the panel
 floats in its column's safe-area-aware bottom-end corner, next to where the
 drawer opens — do not hand-roll a conditional floating control beside the
@@ -198,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/surface-scaffold.md

@@ -18,7 +18,7 @@ padding and aligns with bordered siblings. Reserve `compact` or `comfortable`
 body insets for exceptional content that does not already have list/content-item
 geometry.
 
-Wrap one `wa-dropdown` with `PopupSurface`. `inset="list-zero"` removes menu
+Wrap one `PopupMenu` (or another single `wa-dropdown`) with `PopupSurface`. `inset="list-zero"` removes menu
 padding for a child that already owns row insets, `compact` uses 4px, and
 `standard` uses the shared 8px surface inset. Keep the dropdown trigger named and
 preserve `data-morph-skip-children` when its upgraded light-DOM items must retain

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
@@ -10,7 +10,11 @@ launch Chromium, Firefox, and WebKit. The build emits
 `source-freshness.json`; browser coverage compares it with an independent hash
 of the current `src/` and `ux-demo/` inputs, so a stale `dist-demo` cannot pass
 after a route or component edit. `npm run demo:serve` remains a preview-only
-command for an already-built catalog.
+command for an already-built catalog. The demo-conformance preflight also
+rejects a component route that wraps its `CatalogExampleStack` in a card or
+other container (`catalog-demo/wrapped-example-stack`): single-component demos
+sit directly on the catalog grid, and only composition and recipe routes frame
+their content.
 
 Ten lazy production-composition routes live under the `Recipes` category.
 Each `?component=recipe-*` route uses public package primitives, real wiring,
@@ -25,7 +29,7 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - 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. 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 checkerboard belongs to the preview scroll owner rather than a viewport-height stage 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.
-- The list-detail dialog recipe composes `DialogSurface`, the dialog's own labeled header and close control, `SplitView`, and footer actions. Its `SplitView` sits flush in the dialog body, both panes open with a `ListHeader` on one shared line, the dialog title and header text share the 17px text edge, the value table keeps the 8px outer margin, and the trailing actions keep the 16px footer gutter. Compact devices get a full-screen sheet with a list-to-detail drill-down. Browser geometry coverage protects those relationships at wide and narrow widths.
+- The list-detail dialog recipe is laid out like a `Workbench` on roomy devices: a headerless `DialogSurface` modal whose `SplitView` holds a full-height list sidebar `Pane` with its own toolbar beside a full-height detail `Pane` that carries the primary xl title, the `data-dialog="close"` control, and the record actions in its footer. Compact devices get a full-screen sheet with its own labeled header, footer actions, and a list-to-detail drill-down. Browser geometry coverage protects those relationships at wide and narrow widths.
 - 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`.
@@ -47,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