@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.111

package/llms.txt

@@ -6,64 +6,605 @@
 > generate correct, good-looking kerf UI — it is not a catalog to browse.
 
 ```bash
-npm install kerfjs @kerfjs/ui   # kerfjs is a peer; Web Awesome is an optional peer
+npm install kerfjs @kerfjs/ui # kerfjs is a peer; Web Awesome is an optional peer
 ```
 
 Import each component from its own subpath (`@kerfjs/ui/list-item`, `@kerfjs/ui/toolbar`,
 …); the browser build pulls that component's reachable CSS automatically, so do not
 maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 
+The sunken/lowered background is semi-transparent: Web Awesome's
+`--wa-color-surface-lowered` is mirrored by `--kui-color-surface-lowered` and
+used by `--kui-color-neutral-fill-quiet`. `SunkenPanel`, sunken
+`Pane`/`Workbench`/`TabNavigator` surfaces, and Web Awesome
+`appearance="sunken"` use that tint by default through their optional
+`--kui-sunken-panel-background` / `--kui-wa-sunken-background` override tokens.
+Each layer composites over its backdrop. Intentional nested layers create
+depth; avoid a wrapper or extra background that paints the same visual surface
+twice. Check contrast in both color schemes over the actual backdrop. See
+[contextual transparency](./docs/webawesome-theme.md#contextual-transparency).
+
+For chrome laid over imagery, use the `clear` presentation (Pane
+`headerPresentation`, NavStack `chromePresentation` /
+`bottomToolbarPresentation`, TabNavigator `barPresentation`) with glass
+control groups, and `scrollEdge="material"` (or `"surface"`) to fade a
+backing in gradually over `scrollEdgeDistance` (default 60px) as content
+scrolls beneath (a first `BackdropImage` with `underChrome` runs its artwork beneath the header); see [Clear header](./docs/layout.md#clear-header).
+
+For a `kerfjs/overlay` dialog with `presentation: 'bottom-sheet'`, import
+`@kerfjs/ui/overlay-sheet.css` once (and pass `exitClass: 'kui-overlay-sheet-exit'`
+for the slide out; add the `kui-overlay-sheet-resizable` class and call
+`wireOverlaySheets()` for a resize grabber); see [Core dialogs as bottom sheets](./docs/surface-scaffold.md#core-dialogs-as-bottom-sheets).
+
+For an app-chosen surface color, set the typed `background` prop (a
+`@kerfjs/ui/css-values` color) on `Pane` (also `PaneConfig`), `NavStack`,
+`TabNavigator`, or a `TabNavigatorTab` instead of styling the component. It
+replaces the default or sunken fill; overlay chrome keeps its material; forced
+colors paint `Canvas`. Keep content at AA over the color. See
+[Background colors](./docs/layout.md#background-colors).
+For a region that takes on a color with text kept at AA automatically, set
+`tint={{ color, scheme }}` (the app declares the scheme; no color detection; an optional `accent` re-derives the brand ramp at AA);
+see [Tinted surfaces](./docs/layout.md#tinted-surfaces).
+
+For arbitrary interactive help or popup content, use `openAnchoredSurface` or
+`openAnchoredSurfaceAt` from `@kerfjs/ui/anchored-surface`; see
+[AnchoredSurface](./docs/anchored-surface.md). The app owns content and actions.
+Inside a native `<dialog>`, `wa-dialog`, or `wa-drawer`, the surface stays
+interactive and closes with the dialog. It keeps an 8px viewport gutter
+(`viewportMargin`) and fits its height to the room beside the anchor, scrolling
+its content, so do not add media queries or `max-height` overrides.
+`tone: 'dark'` gives a popup anchored to dark media chrome the inverse tone of a
+`ToolbarControlGroup tone="dark"`; its content inherits the matching colors.
+For a public subpath containing several visual components, use a folder with one
+component per source file and one owned stylesheet per visual component. Keep its
+compatibility entrypoints implementation-free: JavaScript/TypeScript only re-exports
+the folder modules, and CSS only imports their owner stylesheets.
+
+### Shared semantic tones
+
+Use `ToolbarText tone="dark"` on a loud-filled toolbar surface (the inverse
+`--kui-color-neutral-fill-loud`) to match dark control groups; it inverts with
+the color scheme. Over a dark photo or scrim keep the default tone inside a
+`BackdropImage` overlay, which takes the dark scheme under its `scrim`. It applies to read-only headings and actionable
+titles at every size; default tone retains existing identity and heading colors.
+
+`SemanticTone` is the shared color-role type for `Badge`, `Chip`, `StateBanner`,
+and semantic `ContentItem` appearances: `neutral`, `info`, `pop`, `success`,
+`warning`, and `danger`. Import it as a type from `@kerfjs/ui`,
+`@kerfjs/ui/badge`, `@kerfjs/ui/state-banner`, or `@kerfjs/ui/content-item`.
+Use `info` for the role backed by the existing `--kui-color-brand-*` tokens.
+Migrate Badge/Chip `tone="brand"` to `tone="info"`; `BadgeTone` and
+`StateBannerTone` remain deprecated aliases of `SemanticTone`.
+
+## The rule: components own their styles
+
+Configure components through their typed props (size, density, inset,
+presentation, `ToolbarConfig`, `PaneConfig`, …); never restyle one from outside.
+No application or parent CSS may select a `.kui-*` class, a `[data-component]`
+root, a `wa-*` element a Kerf component renders, or its `::part()`s, and no
+writing another component's `--_kui-*` / `--kui-*` variables where a prop
+exists. When a component adapts inside another, it styles itself in that
+context in its own stylesheet. A missing prop is a component gap to report,
+not a reason to override — and your own components follow the same rule.
+
 ## How to build a screen (retrieval order)
 
+First make the design decision: state what the user must read or do, find the
+Kerf or consuming-app component whose purpose and interaction match, and
+configure it. Compose `Toolbar`, `List`, `Row`, `Grid`, `ContentItem`, and the
+other primitives before creating markup or CSS. A local component should own a
+real domain behavior or new structure; a wrapper made only to re-space or
+re-skin an existing component is the wrong choice. Ask what each `div`, `span`,
+fragment, class, and CSS rule contributes. Remove it if a component already
+owns the semantics, surface, inset, scrollport, or gap. Use the spacing scale
+to show relationships, keep useful negative space, and align neighboring text
+and control edges. Check the result against adjacent screens at wide and narrow
+widths. The concrete [decision pass](./docs/component-selection.md#decision-pass-before-jsx-or-css)
+explains when to reuse, compose, extend, or use native HTML.
+
 1. **Pick the component from the interface need**, not by appearance — read
    [component-selection.md](./docs/component-selection.md) (the problem→component
    matrix, with imports, wiring, ownership, and alternatives).
 2. **Get exact signatures before emitting code** — read
    [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) (real prop names,
    callback shapes, disposer return types).
-3. **For exhaustive, structured facts** (ids, exports, variants, `publicClasses`,
-   relationships, side effects) load the
-   [Machine-readable component catalog](./ai/component-catalog.json) — the
-   canonical checked-in source; its schema is alongside it.
-4. **Apply the rules below and in** [skill.md](./ai/skill.md).
+3. **Look up each component you use** in the
+   [component reference index](./ai/components/README.md) — one line per
+   entry — then read only those `ai/components/<id>.md` pages (1–7 KB each):
+   use/avoid, imports and side effects, a link to exact props, legal parents,
+   zones with their JSX prop and child count, app- and wiring-owned state,
+   geometry, accessibility, the styling boundary (configure through props;
+   never override internals), and `KUI-C###` diagnostics. Do not load the
+   large JSON catalogs just to choose or compose components; the pages are
+   generated from them.
+   **Tools and mechanical checks** use the JSON sources instead: the
+   [Machine-readable component catalog](./ai/component-catalog.json) (ids,
+   exports, variants, `publicClasses`, relationships, side effects, and
+   geometry ownership) — the canonical checked-in source; its schema is
+   alongside it. Also load the
+   consuming application's catalog extension when present; generate one from the
+   [Consumer catalog extension schema](./ai/component-catalog-extension.schema.json)
+   when app-owned components must participate in selection or alignment.
+   A tool loads the [Composition catalog](./ai/component-composition.json) — a
+   generated composition layer beside the component catalog, not a replacement
+   for it — to mechanically evaluate parents, contexts, zones/cardinality,
+   children, state, wiring (including the wiring-owned `stateAttributes` an app
+   must never render or remove), responsive/layout/accessibility rules, and
+   public boundaries. The component catalog stays the selection and delivery
+   surface; the composition layer joins catalogs by `package:id`. Consumer
+   composition catalogs use
+   [the composition extension schema](./ai/component-composition-extension.schema.json).
+   Load [compile-time contracts](./ai/compile-time-contracts-v1.json) for stable
+   `KUI-T###` ids, exact declaration symbols, and the boundary between rejected
+   source states and relationships that still require runtime/catalog checks.
+   Before generating application UI, discover `.kerf-ui-profile.json` with the
+   shipped [application profile API](./ai/application-ui-profile.mjs). Merge
+   package defaults, workspace policy, then parent-to-child directory policy;
+   honor its package-qualified preferences, approved theme/density, semantic
+   tokens, layout conventions, and narrow source-located exceptions. Validation
+   is catalog-aware per layer, including parent values later overridden by a
+   child; synchronous hosts use [application-ui-profile-sync.cjs](./ai/application-ui-profile-sync.cjs).
+   See the
+   [workspace profile example](./docs/examples/application-ui-profile.json).
+   A zone's optional `jsx.prop` is its only authoritative JSX binding; never
+   infer one from the zone id. Use `children` for one homogeneous primary
+   region and explicit named content prop slots for semantic positions or
+   replacement content. These slots use the recursive `KerfUiContent` type:
+   `SafeHtml`, runtime-empty boolean/nullish values, and readonly nested arrays.
+   Put conditionals and mapped component arrays directly in them; do not add a
+   `Fragment` only to satisfy types. Arbitrary strings, numbers, and signals are
+   rejected unless a component explicitly exposes a text position such as
+   `ListInsetText`. These are typed props, not native `<slot>` elements,
+   wrapper slot components, or a generic `slots` object. Leave unresolved
+   dynamic expressions unknown.
+   Stable single-root Kerf UI components separately accept the explicit native
+   `slot="name"` prop for light-DOM composition inside a custom element and
+   preserve it across rerenders. Do not infer arbitrary native-attribute
+   spreading from this narrow interop contract. `ResizableRegion` and
+   `CollapsiblePanel` remain excluded because their optional restore controls
+   make their output multi-root; `CollapsiblePanelToggle` remains slot-capable.
+4. **When authoring a component gallery**, load
+   [catalog-authoring.json](./ai/catalog-authoring.json), then follow its
+   authoritative [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract).
+   Use its component/composition/recipe taxonomy and functional-group,
+   importance, alphabetical-tie, and recipes-last ordering policy. Focused
+   demos and recipes use public components plus `CatalogExample.viewport`,
+   never local stylesheets, inline styles, or styling-only classes. A frame
+   that a top-layer specimen anchors to takes `viewport.anchorName`, and a
+   centered column takes `viewport.contentWidth` + `contentAlign`.
+5. **Apply the rules below and in** [skill.md](./ai/skill.md).
+6. **Before calling an integration complete**, run
+   [`kerf-ui-doctor`](./docs/ui-doctor.md). Its portable JSON report merges
+   profile/catalog, TypeScript, Kerf ESLint, and static analyzer diagnostics;
+   CSS-adjacent component props are checked from catalog `cssValueProps`, so
+   prefer its canonical shorthand or typed helper over raw CSS strings; a
+   `--wa-color-{tone}-fill-loud` override without a governing `on-loud` (same
+   or ancestor scope, possibly in a co-loaded stylesheet), or whose literal
+   pair measures below 4.5:1, is review finding `KUI-L018` (set both); CSS that restyles a component
+   (`KUI-L019`), touches its private `--_*` variables (`KUI-L020`), overrides a token a typed prop sets
+   (`KUI-L021`), or styles it through a hook class on its root (`KUI-L022`) is an error: configure the
+   component instead, and report a component gap when no prop exists; application-component imports may use TypeScript `paths` aliases; use `"ownership": "component"` with catalog `styleSources` to apply this boundary between an app's own components; repair source-located errors until exit 0. Use full mode for release gates;
+   generated `dist`/`coverage`, dependency, cache, evidence, and nested-worktree
+   directories are excluded consistently from every static stage.
+   [`kerf-ui-analyze`](./docs/ui-analyzer.md) remains available when only static
+   layout diagnostics are wanted; its review findings are a bounded human/AI
+   review queue rather than an objective aesthetic score.
+7. **Evaluate the running application** by explicitly enabling the doctor's
+   browser stage or directly invoking
+   [`kerf-ui-evaluate`](./docs/ui-evaluator.md). Preserve its `KUI-B###`
+   browser evidence and screenshots; record hierarchy/rhythm/density/aesthetic
+   ratings separately with a named reviewer rather than presenting them as
+   objective assertions.
+
+## Application interaction choices
+
+For ordinary server-backed freshness, prefer event-driven updates, subscriptions,
+or explicit user refresh when they meet the product need. Use fixed-interval
+polling when periodic sampling is genuinely required or no suitable update
+channel exists; choose the interval deliberately and cancel the timer when its
+owning view is disposed.
+
+Make cursor cues match enabled behavior: use a pointer for actionable targets,
+grab/grabbing or resize cues for actual drag and resize affordances, and a
+default or disabled cue when an action is unavailable. Keep the semantic
+control, keyboard behavior, focus treatment, and disabled state aligned with
+the cursor; the cursor alone cannot explain an interaction. See
+[accessibility contracts](./docs/accessibility.md) and
+[interaction principles](./docs/apple-hig.md#interaction).
+
+## Interface copy capitalization
+
+Follow Apple's split, the package default: **names are title style;
+descriptions are sentence style.** Title style: buttons, menu items and menu
+headings, popup-menu triggers, segments, `Select` choices, tabs,
+page/view/pane/dialog/toolbar titles, back labels, `ListHeader` and column
+headings, field labels, icon-only control names, and fragment
+`EmptyState`/`StateBanner` titles ("Save Draft", "Back to Inbox"). Sentence
+style: body copy, descriptions, details, messages, tooltips, placeholders,
+checkbox/switch/radio option text, and status lines ("Saved just now"). Title
+style capitalizes the first and last word and phrasal-verb particles ("Log
+In"); it lowercases articles, coordinating conjunctions, `to` in infinitives,
+`as`, and prepositions of four letters or fewer elsewhere. Keep brand spellings
+and user data as written. `kerf-ui-doctor` reports violations in known
+title-style labels as `KUI-D040`. See
+[Writing interface copy](./docs/writing.md#capitalization).
 
 ## Core rules (do the right thing)
 
+- **Prefer a Kerf UI component, then a native HTML element**, using each for
+  what it is good at. Kerf UI needs no Web Awesome; it is an optional
+  integration. Never render a `Discouraged` Web Awesome element (`wa-button`,
+  `wa-input`, `wa-checkbox`, `wa-select`, `wa-dropdown`, `wa-dialog`,
+  `wa-tab-group`, `wa-icon`, …); use the Kerf component that replaces it
+  (`Button`, `TextField`, `Checkbox`, `Select`, `PopupMenu`, `DialogSurface`,
+  `TabBar`, `LucideIcon`; see
+  [webawesome-migration.md](./docs/webawesome-migration.md)), and file a
+  component gap rather than dropping to the raw tag.
 - **Reach for the primitive, not for CSS.** The package is built to look right
-  *unstyled*. Before adding `padding`, `margin`, `width`, `height`, `border`,
-  `background`, a wrapper card, or a decoration, check whether the component, the
-  pane, or the content-item already owns it — it almost always does. Prefer a
-  component prop or a `--kui-*` token; write CSS only for genuinely new structure,
-  and then only join a component's documented `publicClasses` (never reach in by
-  tag/id/attribute or an unlisted class).
+  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 — `FloatingToolbar inset`, `DisclosureArrow size`, `ListHeader
+headingLevel`, `SearchField 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">`. For a chat transcript, set
+  `bubble="start"` (other participants) or `bubble="end"` with
+  `appearance="brand-loud"` (the person's own messages): the item fits its
+  message up to 80% of the row. 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`
+  once for border-box sizing, token-backed body/link presentation, inherited
+  native table-cell and form-control font metrics, zero body margin, and
+  zero-specificity semantic cursors for native controls (pointer, not-allowed
+  when disabled, text on text inputs). Put `.kui-app-root` on the one direct mount container only when a
+  percentage-height shell needs the provided `html` → `body` → app-root height
+  chain. Add `data-viewport="locked"` to that body-child root for a
+  full-viewport shell whose document never scrolls (`100dvh` and
+  `overflow: clip` on `html`, `body`, and the root). The baseline is not part of `styles.css` or component browser imports.
+- **Use compact layout options where needed.** `Text flush lineHeight="tight"`
+  fits short dialog copy, and `Text align="center"` centers wrapping status
+  copy; `ValueTable density="compact"` reduces row spacing,
+  with public row column, padding, and gap tokens for specific metadata layouts.
+  `ToolbarText size="xsmall"` suits a dense rail heading. The
+  `SearchField` editor shrinks in narrow groups; its minimum width can be
+  set with `--kui-search-field-editor-min-width`.
+- **Label read-only field previews.** Use `FieldLabel` from `@kerfjs/ui/text`
+  in `ListInsetControl sides="trl"` above a `ContentItem` value. Connect its
+  id to the preview group's `aria-labelledby`; use the live control's own
+  `label` while editing.
+- **Use Toolbar zone options.** `responsive="trailing-priority"` moves an
+  expanded trailing control to a full second row at `responsiveAt`; the leading
+  title remains above it. Public leading-min-width, trailing-gap/justify, and
+  per-zone inline-padding tokens cover app-specific toolbar geometry.
+  In a stacked Toolbar, `ToolbarControlGroup placement="end"` places a collapsed
+  search at its row's trailing edge; `sizing="fill"` gives its expanded state a
+  full row and a reduced-motion-aware downward entrance.
+  `--kui-toolbar-inset: 0px` removes an embedded Toolbar's outer padding and
+  corresponding minimum-height allowance while preserving its zone gap and
+  safe-area compensation. For a shorter header embedded in a panel or card,
+  pass `density="compact"` (40px: a 34px control band and 3px block insets)
+  and give its groups `size="compact"`; never shrink a Toolbar with CSS.
+  Composites forward `density` from their `ToolbarConfig` (Workbench panel,
+  main, and bottom toolbars, CollapsiblePanel, NavStack, SplitView) and size
+  the groups they compose (panel toggles, the back button) to match; pass
+  `density` to `CollapsiblePanelRelocated` when its toolbar is compact.
+- **Name panel toggles in title style.** A panel toolbar's
+  `toggle: { action, name }` uses `name` as the toggle group's accessible name
+  and in the default "Show …" / "Hide …" label, so pass a title-style panel
+  name (`name: "Navigator"` gives "Show Navigator"); it is never recapitalized.
+- **Position region restore controls declaratively.** A ResizableRegion has a
+  background token, `contentOverflow="visible"` for an anchored popup,
+  top/bottom `restorePosition`, typed `restoreInset`, and
+  `restorePlacement="inline"` for normal flow. FloatingToolbar also has
+  `placement="inline"`, per-edge inset tokens, and `safeAreaInsets`.
+- **Configure list rows through their APIs.** `ListItem density="spacious"`
+  gives option rows more room. `multiline` wraps labels, with
+  `multilineIconAlign="center"` when the icon should center on the whole copy.
+  `divider` owns row separators and `state="drag-target"` paints the drop
+  target. For lines only between rows, give every row but the last
+  `divider="after"` (the last `"none"`); a row's corners are flat wherever a
+  divider line meets them, so the group rounds only its outer corners on
+  hover and selection. For a reorderable list, set `draggable` + `itemId` on `ListItem`,
+  `ListItemLink`, or `ListActionRow` rows and call `wireListReorder` (from
+  `@kerfjs/ui/wire-list-reorder`) once; it paints the dimmed dragging rows and
+  the before/after insertion line, supports Alt+Shift+ArrowUp/ArrowDown, and
+  reports `{ listId, sourceIds, target: { id, position }, source }` for
+  `reorderListItems`. The `dragging` / `dropPosition` props render the same
+  states from app-owned drag state. For keyboard row navigation in a
+  `scrollable` List, call `wireListFocusScroll` (from
+  `@kerfjs/ui/wire-list-focus-scroll`) once: it scrolls a keyboard-focused row
+  whose focus ring crosses the clip into view in Firefox and Safari too.
+  Public ListItem tokens set row, icon, label, and trailing geometry;
+  ListHeader `size="xs|sm|m|l|xl"` sets label scale independently of
+  `headingLevel` (`sm` keeps the current FieldLabel-sized uppercase style;
+  `m`/`l`/`xl` match themed h5/h4/h3). The label is one ellipsized line;
+  set `wrap` where the whole label must stay readable in a narrow column
+  (it wraps instead of truncating). Its height, title padding, and border
+  tokens tune section density. A semantic `count` requires `countLabel` and
+  excludes other indicators; `badge` and `status` may render together, and
+  either may be explicitly `undefined` in conditional app state.
+  For a filled command list, scope `--kui-list-item-background`,
+  `--kui-list-item-color`, `--kui-list-item-border`,
+  `--kui-list-item-hover-background`, `--kui-list-item-hover-border`,
+  `--kui-list-item-selected-background`, `--kui-list-item-selected-color`,
+  and `--kui-list-item-selected-border` at the list or row boundary.
+  To align `ListItem` and `ListActionRow` rows in one list on a custom
+  leading inset, set `--kui-list-row-padding-inline` on the `List` (never
+  `--kui-list-item-padding-inline`, which moves only `ListItem` rows). Both
+  row kinds draw an 18px untiled leading icon by default, so their labels
+  align; resize both with `--kui-list-row-icon-size` on the `List` (never
+  `--kui-list-item-icon-size`, which resizes only `ListItem` icons).
+- **Use `Row` for horizontal and `List` for vertical layout.** Both expose
+  physical `hAlign`/`vAlign` props and typed gaps. Row defaults to left/full,
+  an `xs` gap, and no wrapping; List retains full/top and zero-gap defaults.
+  Use canonical physical `textInsets` or `controlInsets` sides in
+  `t`/`r`/`b`/`l` order; text geometry wins on overlapping sides.
+  `ListInsetText` and `ListInsetControl` inset every side by default and accept
+  the same `sides` grammar for selective edges.
+  List additionally supplies
+  optional typed `gap`, `flex`, vertical scrolling, and canonical
+  `dividerSides` (`t`/`r`/`b`/`l` order). It adds no list semantics; children own
+  those, and only one bounded region should own scrolling. Pass a finite spacing
+  shorthand (`gap="xs"`, `gap="m"`) or a complete `CssLength` from the CSS-free
+  `@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 and `LucideIcon.color`: `uiColor()` with an `*-on-*`/text token,
+  `foregroundColorVar()`, or `foregroundColor()` for a custom CSS color; fill tokens such as `uiColor('success-fill-quiet')` do not
+  type-check. Fills (a `ChoiceChips` swatch, a row `iconTile` color) take a
+  plain `CssColor`: `fillColor('#3b82f6')` for a custom CSS color, `uiColor()`,
+  or `colorVar()`; never `foregroundColor()` for a fill. These brands are intentionally
+  not interchangeable; rows use classes/tokens/props rather than raw `style`.
+  Set `LucideIcon.inline` for an icon in `Text` or prose; it changes the SVG
+  from block to inline-block without changing its inherited 1em size.
+- **Use `Grid` for equal-width columns.** Set a fixed positive `columns` count
+  or typed `minColumnWidth` for automatic container-width collapse, never both.
+  The app owns the outer width and child semantics; use custom CSS grid for
+  asymmetric/intrinsic tracks and `ResizableRegion` for adjustable boundaries.
+  `Grid.gap` and `Grid.flex` use the same typed grammars as Row.
+  `Grid.textInsets` and `Grid.controlInsets` select physical sides for the
+  standard 17px text and 8px control inset; text wins on overlap.
+  For selectable document tiles, use `selectionMode="multiple"` and a required
+  `ariaLabel`, with `ContentItem selectionMode="multiple"` children. Wire
+  `wireContentItems` for spatial arrow navigation, Enter/Space activation, and
+  one roving Tab stop per grid; a non-selectable row between them is a
+  `ContentItem gridRow` (row + gridcell, no selection).
+  Resolve each activation with `applySelection` and `selectionGesture` from
+  `@kerfjs/ui/selection` (plain replaces, Cmd/Ctrl toggles, Shift extends).
+- **Give a layout root `fill`, not a frame `Pane`.** A Row, List, or Grid that
+  is the sole layout root of a definite-height parent takes its full height
+  with `fill` and carries safe `data-*` markers through `rootAttributes`.
+  Inside a flex layout use `flex` instead.
+- **Keep Web Awesome on the shared inset tiers.** `webawesome.css` uses
+  `--kui-wa-control-inset` (8px controls/items) and
+  `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside
+  Accordion, Card, Details, Callout, and Include), while
+  plain Details keep their body flush while plain Accordion items inset both
+  trigger and body, framed Details use the 16px container inset only on the
+  trigger, and framed Accordion items use it on both regions;
+  `--kui-wa-container-inset` keeps Tab Panel at 16px. Dialog body and footer use
+  the surface (8px) and container (16px) tiers respectively, independent of the
+  dialog's shared `--spacing`. Override the tier at the narrowest useful scope
+  instead of restyling individual shadow parts.
+  Filled badges use each semantic variant's quiet fill with normal text for
+  WCAG-AA compact-copy contrast. Override
+  `--kui-wa-badge-filled-background` and
+  `--kui-wa-badge-filled-foreground` as a contrast-safe pair instead of adding
+  host selectors.
+  When a dialog provides another dismissal affordance, add `hide-actions` to
+  the `wa-dialog` host; the theme hides its directly exported `header-actions`
+  part without an unsupported chained `::part()` selector.
+  Checkbox and Radio Group option regions and the Color Picker trigger stay
+  flush, so each box, circle, or swatch sits on the host's inline-start edge
+  like Kerf's `Checkbox`, `RadioGroup`, and `ColorField`, with the label and
+  hint on the 9px text column. Bordered fields and Switch draw their border or
+  track on that same edge like `TextField`, `Select`, and `Switch`, so place a
+  Web Awesome field exactly where the Kerf field would go.
+  Stacked radios sit 8px apart (`0.25em` block margins) for the same 28px
+  pitch as `RadioGroup`.
+  Slider's complete interactive region uses the shared 8px logical inline outer
+  inset without shifting its already-aligned label.
+  Known Date's Month/Day/Year captions and bordered text-like field hints align
+  with field values at the shared 9px border-plus-padding inset. OTP Input's
+  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. 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.
+  Set `caret={false}` on an icon-only toolbar Select to make a round trigger;
+  a custom `renderSelected` icon stays centered, and the default keeps the
+  visible caret.
+  `SelectChoice.disabled` keeps an unavailable option visible but unselectable;
+  `disabledReason` adds its tooltip. For multiple selects, opt in to
+  `selectAllLabel` and `clearLabel` footer buttons to select enabled choices
+  or clear the value through ordinary change events. The app owns the updated
+  controlled value and localized action labels.
+  Icon-only Selects (single or multiple) and icon-only `PopupMenu`s show an
+  `aria-hidden` 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
+  repair popup timing or anchor placement; raw Web Awesome selects stay native.
+  Use `hint` for supporting text below the control and `placeholderText` only
+  for the empty value inside it; loading placeholders retain the visible hint.
 - **Trust the defaults.** Render a control at its natural size and color (a
   `LucideIcon` is 24px); if it looks wrong, fix the surrounding layout, not the
   control. Never force a component's width/height to size it — that leaves a halo
   or a stretched oval.
+- **Make room for an expanded search instead of growing it past what fits.** A
+  collapsible search group grows into the space beside its sibling groups; if
+  that space is too small, the siblings wrap onto a new row while it opens.
+  Size the expanded search to what fits (`--kui-search-field-expanded-width`,
+  or `sizing="grow"` with a `growBasis` that fits), and if a useful search
+  cannot fit beside the other controls, set aside those controls while the
+  search is open: mark them `visibility="yield-to-expanded-sibling"` (they
+  leave a 480px-or-narrower toolbar while a sibling is expanded), or, in a
+  `responsive="trailing-priority"` Toolbar, `visibility="yield-to-priority-row"`
+  (they leave exactly while the expanded control has its own row, from the
+  Toolbar's `responsiveAt`; never restate that breakpoint with `hideBelow`,
+  whose strict "below" is one pixel off the Toolbar's inclusive width), or
+  gather them behind a "…" `PopupMenu` overflow group. The app decides which
+  controls yield.
+- **Change the brand with `--kui-color-brand`.** Set it once on `:root` (any
+  color): Kerf derives the brand fill, brand text and links, text on brand
+  fills, and the focus ring at WCAG AA, and Web Awesome's brand tokens follow.
+  Overriding `--kui-color-brand-fill-loud` alone leaves brand text and the
+  focus ring blue.
 - **Toolbars hold only `ToolbarText` and `ToolbarControlGroup`.** Never put a bare
   button, input, link, or loose markup in a `leading`/`center`/`trailing` zone.
   Wrap every control — `SegmentedControl`, `Select`, a collapsible
-  `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. A
-  toolbar popup menu is a `single` `ToolbarControlGroup` around a `wa-dropdown`
-  (its `slot="trigger"` `wa-button` is the toolbar button, kept under
-  `data-morph-skip-children`).
-- **`PanelHeader` is *the* panel/dialog/page heading.** A plain toolbar with an
-  optional bordered icon group, an extra-large `ToolbarText` title, the trailing
-  controls you pass, and an optional subtitle below — do not hand-build a heading
-  row or restyle a toolbar into one.
+  `SearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. For an
+  ordinary icon/action control inside the group use a **plain `<button>`** (the
+  group styles it fully) — that is the default; a standalone `Button` belongs
+  outside a group. A toolbar popup menu is a `PopupMenu`
+  (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`)
+  in a `single` `ToolbarControlGroup` with `nestedDropdown`; never hand-write
+  `wa-dropdown` markup for a menu. Let the group size the trigger from its icon,
+  localized text, and caret. Set `overflow="wrap"` for independent action links
+  that must remain fully visible at narrow widths; whole links move to a second
+  row, as in the catalog resource footer. `PopupMenu` items also support nested `submenu`
+  actions, headings, dividers, checked or trailing choice marks, danger tone,
+  and disabled reasons; nested headings/dividers stay out of keyboard choices;
+  a choice dispatches its `data-action` plus a bubbling `kui-menu-select` event whose
+  `detail.checked` is the state a checkbox choice asks for (the app owns and
+  renders that state);
+  use `context` with `anchor` + `openPopupMenu` (or `openPopupMenuAt`) and
+  `closePopupMenu` for pointer-anchored row menus, whose `placement` applies
+  at the point (`top-start` opens above it); the menu owns its
+  zero-footprint anchor host, so add no wrapper or CSS. `openPopupMenuAt`
+  also opens a button-triggered menu at the pointer for one opening
+  (`bottom-start`, or `openPopupMenuAt(menu, x, y, { placement: 'top-start' })`
+  to open above the point). A row's
+  trailing "…" overflow menu is `ListActionRow`'s `trailingMenu` (`label`,
+  `icon`, `items`, optional `placement` and `disabled`), which renders a
+  `PopupMenu` as the row's sibling trailing control. Do not force a dropdown or button width. Nothing
+  wraps inside a group: an icon sits beside its label on one row, and a
+  `ToolbarText` is one ellipsized line unless you opt into `wrap`/`maxLines`. A
+  Select or PopupMenu trigger drops its focus ring while its popup is open and
+  the ring follows the control's shape; never add ring CSS. Compact
+  mixed groups keep standard item padding and raised selected chrome without an
+  internal separator; the selected item paints over the outer border. For an
+  avatar control, set `content="avatar"` and `avatarImage` on the group instead of
+  inserting an `img`; a lone control paints the group and a multi-button group
+  paints only its pressed highlight. Dividers earn their place: a `Toolbar`
+  draws none by default and pinned chrome gets its line from scroll state (see
+  the scroll-divider rule below); never fake one with a border or pad below a
+  divider to make it look right.
+- **Use one direct toolbar composition for panel/dialog/page headings.** Put an
+  optional icon in a `ToolbarControlGroup`, an extra-large `ToolbarText` directly
+  in the leading zone, and actions in a trailing group. A short supporting
+  line ("Changes save automatically.") is the `ToolbarText` `description`:
+  quiet, one truncating line under the title, aligned with its text, with
+  `descriptionId` for `aria-describedby`. Longer copy is app-owned content
+  below. Do not create a private heading wrapper or restyle the
+  toolbar. A narrow peripheral rail or drawer, where extra-large would truncate
+  at its minimum size, names itself with the default `ToolbarText` size.
+  `ToolbarText size="xlarge-fixed"` keeps the 20px `--kui-font-l` heading step;
+  `xlarge` retains the responsive page-title clamp.
+- **Use `Text` for ordinary semantic headings, paragraphs, and inline secondary
+  text outside toolbar title zones.** Omit `variant` for the default `p`, pass
+  `h1`–`h6` based on the document outline, or use `variant="span"` inside a row,
+  label, or table cell without adding box geometry. Independently compose `tone="quiet|danger"`,
+  `size="compact|large|xlarge"`, and `font="monospace"` for supporting, error,
+  compact, prominent, display, and code roles instead of global utility classes. It passes native attributes
+  through; block variants own the standard transparent border plus item padding, while `span` owns none. Keep
+  toolbar titles on `ToolbarText` and list-aligned bare prose on `ListInsetText`.
+  Text supports `controlMargins` with canonical physical Sides for an exterior 8px control gutter; it preserves border/padding and avoids an isolated Row wrapper. Avoid stacking it with parent insets. Inline spans retain native inline margin behavior.
+
+  `ToolbarControlGroup.tileTone` selects `neutral`, `brand`, `success`, `warning`, or `danger` quiet fill, matching quiet border, and on-quiet foreground for a non-interactive icon tile. Compose a contained `single` group whose only child is a direct decorative LucideIcon (`aria-hidden="true"`). Omission preserves the normal group palette. The prop does not recolor interactive, mixed, multi-control, or borderless groups; keep real actions in controls with their existing focus/hover/pressed treatments.
+  `ToolbarControlGroup` `material="glass"` paints a group that floats over imagery or a clear (transparent) toolbar on the translucent chrome material (`--kui-chrome-material` with the blur/saturate `--kui-chrome-material-filter`), with a specular edge in place of the gray border and a soft shadow. Its controls take `--kui-color-text`, so they stay at AA over any content; a raised or outline selection paints an opaque surface pill. The fill turns opaque under reduced transparency, increased contrast, static effects (`update: slow` or `:root[data-kui-effects="static"]`), or without backdrop-filter support, and paints Canvas/CanvasText in forced colors. A `tone="dark"` glass group keeps its loud fill and gains the blur and edge; a borderless group has no surface and ignores the material. Keep the solid default on an opaque toolbar, and never add your own `backdrop-filter` or translucent background to a group.
+  `ListItem`, `ListItemLink`, and `ListActionRow` take `iconTile` to present their leading `icon` in a filled 32px rounded tile holding an 18px glyph, for settings or command rows that identify each entry by color. Pass a tone (`neutral`, `brand`, `success`, `warning`, or `danger`) for the same quiet fill, matching quiet border, and on-quiet foreground as `ToolbarControlGroup.tileTone`, or `{ color, foreground? }` for an application color: `color` is a `CssColor` (`uiColor()`, `colorVar()`, or `fillColor('#e5484d')`) and `foreground` a `CssForegroundColor`; without one, the glyph is black or white, whichever contrasts with the fill. The tile sits 6px clear of a standard 44px row (a compact row is at least 42px tall), moves the label to the tile's edge, and keeps its colors when the row is hovered or selected. Never wrap the icon in your own tile or resize the row's icon slot.
+  Toolbar zones accept `KerfUiContent` directly. Use `ToolbarText` for identity and `ToolbarControlGroup` for related controls that need its shared chrome; a bare control keeps its own styling and accessibility responsibilities.
+  Expanded search groups accept `expandedOverflow="visible"` to anchor app-owned suggestion/date/help surfaces below their relative root; collapsed/default groups retain existing clipping. Apps own surface placement/dismissal and use `data-search-field-keep-open` or `collapsible.keepOpenOn` for focus.
+
 - **Space by the five-step scale, by relationship not by eye.** `0`
   `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
   group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing
-  regions). 12px/32px are off-scale exceptions.
+  regions). 12px/32px are off-scale exceptions. Prefer direct `Row.gap`/`List.gap`
+  shorthands for repeated rhythm; use `Spacer` for one typed empty width/height
+  or flexible main-axis gap. Use `space`, `px`, `rem`, `em`, `pct`, `lengthVar`, and
+  `calc(plus(...))` for typed runtime composition. `remify()` is source-CSS only.
+- **Keep nested highlight corners concentric.** Inset hover and selection surfaces
+  follow the owning control's pill or rounded shape; their radius is the outer
+  radius minus `--kui-layout-highlight-inset`. Do not give an inner highlight an
+  unrelated radius.
 - **Panes share one child-owned geometry.** Sidebars, main areas, inspectors, and
-  dialogs all use an unpadded `.kui-pane` (optional `.kui-pane__toolbar`, one
-  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.
+  dialogs all render `Pane`: an unpadded `.kui-pane` (optional header, one
+  scrolling `.kui-pane__content`, optional footer). Use `tabIndex={0}` for a
+  whole-surface Tab stop or `-1` for programmatic
+  focus on Pane, SunkenPanel, static ContentItem, or a plain TabNavigator scene;
+  `outlined` holds its standard focus ring for an app state such as a drop target.
+  Workbench uses `mainTabIndex`/`mainOutlined` for the center and
+  `tabIndex`/`outlined` per rail or drawer. Hidden scenes and collapsed panels
+  suppress those states. Never write a component's anatomy classes onto your
+  own element to recreate it (`KUI-L103`); only the catalog's `placeableClasses`
+  (layout utilities, `.kui-app-root`,
+  `.kui-content-item` on a non-div carrier) belong there. A visible pane owns
+  its collapse control (the last control of its last group); a hidden pane's
+  restore moves to the adjacent main toolbar's matching edge — no icon-only
+  rail — and a collapsed drawer's restore sits in the bottom toolbar or a
+  `FloatingToolbar` beside the drawer, near where its effect appears. Align
+  text to text and icons to icons across a pane; a border is decoration, never
+  the alignment anchor. Keep one scroll owner per region.
+- **Dividers between pinned chrome and scrolling content are scroll state.**
+  Toolbars draw no divider by default. Call `wireScrollDividers(appRoot)`
+  (`@kerfjs/ui/wire-scroll-dividers`) once and keep its disposer: every `Pane`
+  with `chromeDividers="scroll"` then draws the line under its header only while content is scrolled beneath
+  it and the line over its footer only while more content lies below (never
+  when the content fits), every `NavStack`'s top chrome and bottom toolbar and
+  every `TabNavigator` bar do the same around the active view or scene, and
+  every `TabBar` marks each side of its strip with tabs scrolled out of view. Configure a pane with `chromeDividers`
+  (`scroll` for a plain pane by default, `always` for a sunken pane by default,
+  or explicit `scroll`, `always`, `none`), and a `NavStack` or `TabNavigator`
+  with its own `chromeDividers` (same values; a `SplitView` forwards it through
+  `compactStack`); name app-owned chrome in `targets`.
+  A `TabNavigator` also takes `separator="auto" | "hidden"`: auto draws the
+  bar's top edge beside a sunken active scene or nested Pane even when content
+  fits; hidden suppresses that edge, including scroll dividers.
+  Never add a border, or a permanent `dividerSides`, to fake one.
+  For a header that floats over its scrolling content, set
+  `headerPresentation="overlay"` on the `Pane` (or in `PaneConfig`). It paints
+  the translucent chrome material (`--kui-chrome-material`, opaque under
+  reduced transparency, increased contrast, forced colors, a slow-updating
+  display, and the app-set `data-kui-effects="static"` root switch). The same
+  `wireScrollDividers` call measures the header and publishes its height as
+  block-start scroll clearance, which the content clears automatically. Keep
+  overlay-header text in the normal text color.
+  For a translucent stack bar laid over the active view, set
+  `chromePresentation="overlay"` on the `NavStack`. `wireNavStack` measures
+  the top chrome and hands its height (top safe area included) to the views
+  as their block-start inset, so a plain view or a sole `Pane` clears it
+  automatically. Keep its text in the normal text color. For a translucent
+  bottom toolbar, set `bottomToolbarPresentation="overlay"` (separate from
+  `chromePresentation`); `wireNavStack` hands its height (bottom safe area
+  included) to the views as their block-end inset, so the last item rests
+  just above it. Its `ToolbarText` and default-tone `ToolbarControlGroup`
+  controls lift themselves to AA. For a translucent tab bar, set
+  `barPresentation="overlay"` on the `TabNavigator`; `wireTabNavigator`
+  measures the bar and the scenes hand its height to their content as the
+  block-end inset. Its tab labels lift themselves to AA.
+  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
@@ -72,60 +613,408 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 - **App state is domain/persisted; helpers own only ephemeral mechanics.** Keep
   navigation stacks, tab selection and order, pane sizes, and `collapsed`/`expanded`
   disclosure flags in the app — they are data or persisted layout, and the app reads
-  them to render. The `wire…` helpers own the *ephemeral* parts: `wireNavStack` the
-  push/pop animation, `wireTabBars` the overflow autoscroll and drag preview,
-  `wireResizableRegions` the live drag preview; they report committed changes via
-  callbacks. The one richer case is `wireTokenSearchFields`, which manages the
+  them to render. The `wire…` helpers own the _ephemeral_ parts: `wireNavStack` the
+  content-slide, per-view top/bottom chrome cross-fade, and focus move/restore
+  (mark a preferred new-view target with `data-nav-focus`), `wireTabBars` the
+  overflow autoscroll, drag preview, and
+  replacement focus after controlled automatic tab activation,
+  `wireResizableRegions` the live drag preview, `wireScrollDividers` the
+  scroll-state attributes from which a `Pane` draws its chrome dividers and a
+  `TabBar` its overflow dividers; they report committed changes via
+  callbacks. For a tab-local action plus a separate far-edge action, set
+  `TabBar trailingPlacement="adjacent"`, put the local action in `trailing`, and
+  the workspace action in `end`; the component keeps both visible while its tab
+  list shrinks and scrolls, without application descendant CSS. Each action
+  zone accepts one ToolbarControlGroup, standalone Kerf `Button`, or exceptional
+  Web Awesome `wa-button` for its own chrome. Managed
+  SearchField clear also preserves open state and replacement
+  editor focus before the next input task, so shortcut-letter typing stays in search.
+  Select All deletion does the same; deletion
+  restoration finishes before the next keystroke rather than on a delayed frame.
+  Persist both query and remaining tokens read from an edited field; change
+  `revision` to replace unmanaged DOM-owned text programmatically, or call
+  `model.replace({ query, tokens })` for a model-managed field. In grammar-assisted
+  search, a model rule's `suggest(input, state)` receives current committed tokens
+  so suggestions can omit selected values; one-argument callbacks still work.
+  A sibling helper can call `model.commit(value)` for the active `name:` prefix
+  even when that value is not suggested; invalid values and missing prefixes
+  leave state unchanged.
+  A managed field subscribes the host render only to `model.structure`
+  (committed tokens, empty or non-empty text, editor revision), so typing plain
+  text never re-runs it; in the host's own render read `model.state.peek()` and
+  bind `model.result` as a signal hole instead of reading `model.state.value`.
+  The one richer case is `wireSearchFields`, which manages the
   collapsible field's expand/collapse/focus by default (on, per-behavior opt-out) and
   exposes the `expanded` signal on its handle — bind it in render or hand in your own
   via `collapsible.signals`. Do not hand-roll open/collapse/focus that helper
   provides; but do keep a plain disclosure toggle (a one-line boolean the app already
   renders from) in the app. For real-app composition it also offers a focusout
-  keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn`,
+  keep-open exception (`data-search-field-keep-open` regions or `collapsible.keepOpenOn`,
   so a sibling suggestions/date popover does not collapse an empty field), opt-in
   atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via
   `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an
   `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — so the app can drop its own keydown/input
   boilerplate while still owning parsing and controlled token state.
+  When `onEdit` or `onRemoveToken` changes tokens and the controlled render
+  replaces the focused editor, the helper hands focus and caret to the new
+  editor in the same task (end stays at end), so do not add a refocus
+  `MutationObserver` or `requestAnimationFrame`.
 - **Placeholder loading state, don't rebuild it.** For a value or component that is
   still loading, set `placeholder` on the component (`Select`, `ListHeader`,
-  `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`,
-  `AppTab`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
-  slots as subtle **unanimated** skeleton blocks and interactivity disabled, so a
-  parent composes a faithful loading view (e.g. an inspector) without hand-rebuilding
-  markup. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
-  (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
-  `LoadingSpinner` for known busy activity instead.
+  `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`,
+  `TabBarItem`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
+  slots as subtle **unanimated** skeleton blocks and interactivity disabled. Only
+  unknown values change: a placeholder is never dimmed or styled as disabled (a
+  control you disabled keeps its live disabled tone), so a parent composes a
+  faithful loading view (e.g. an inspector) without hand-rebuilding markup.
+  Component-drawn chrome stays live: a `ListItem` or `ListActionRow` keeps its
+  `busy` spinner while its `status` (and a `ListItem`'s `trailing`) content
+  become skeletons. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`,
+  and never animate it — use
+  `LoadingSpinner` for known busy activity instead. Set its `size` prop to a
+  named icon step or positive pixel number when the inherited 1em is unsuitable.
+- **Keep ListItem content inside the row.** The rounded `ListItem` root clips
+  overflowing label, status, and dormant trailing content. Set `multiline` when
+  the primary label should wrap; use `ListActionRow` instead when trailing content
+  must be interactive.
+- **Dialog bodies are lists by default.** Compose rows and sections in `List`,
+  use `DialogSurface bodyInset="none"` when those children own their geometry,
+  and wrap bare prose in `ListInsetText` so it shares the standard list gutter
+  without stacking a second body inset.
+- **Use a StateBanner badge only for compact supporting status.** Pass the
+  optional string `badge` for a terse count or status beside the title. It
+  inherits the banner tone and is announced with the banner, so keep its text
+  meaningful and never rely on color alone.
+- **Configure StateBanner copy and action placement.** `copyLayout="stacked"`
+  puts detail below the title and badge; `actionPlacement="below"` always
+  gives the action a separate trailing row. The default trailing action stays
+  beside the copy while it has room and wraps onto its own trailing row on a
+  narrow banner, so do not switch placement per breakpoint.
+  `presentation="strip"` renders a flush, square, full-width band for a
+  layout edge with tone-colored `dividerSides` (bottom by default) instead of
+  the inset rounded card; never restyle a card into a strip.
+- **Use `SplitButton` for a primary action with options.** One loud semantic
+  fill with a native primary button and an options trigger (`aria-expanded`,
+  `aria-haspopup`); `tone`, `fill`, `shape` (`rounded` or `pill`, as on
+  `Button`), `busy`, and `disabled` are props. Never build one from
+  `wa-button-group` or app CSS on native buttons.
+- **Keep a Button's focus ring inside a clipping ancestor with
+  `focusRingInset`.** `Button` and `SplitButton` draw the ring 1px outside the
+  box; inside a container that clips overflow, set `focusRingInset` and the
+  ring moves inside the box with a surface-colored line inside it, so it keeps
+  3:1 contrast even on a loud fill of its own hue. The line follows the
+  surface context sunken, quiet, raised, and highlighted surfaces, app
+  `background` colors, and glass chrome publish
+  (`--kui-color-surface-current`, `-region`, `-tint`), so it never reads as a
+  halo there. Never re-offset the outline from app CSS.
+- **Span a full-width primary action with `fill`.** `<Button tone="brand" fill action="create">Create Project</Button>`
+  spans the parent's available inline width instead of shrinking to its
+  label, with the label centered and ellipsized once it no longer fits; a
+  link (`href`) fills the same way. It is the same `fill` `SplitButton`
+  takes. Never set `width: 100%` on a Button from app CSS.
+- **Make any `Button` a toggle with `pressed`.** In content or a pane footer,
+  `<Button icon={…} ariaLabel="Show Conversation" emphasis="plain" pressed={open} action="toggle-chat" />`
+  renders a native `aria-pressed` button whose pressed look draws on top of
+  its tone and emphasis; the app flips the state. Never wrap a
+  `ToolbarControlGroup` outside a toolbar or restyle a button to fake it.
+- **Mark a current setup step with `Button.currentStep`.** It emits
+  `aria-current="step"` on a button or link, including a disabled current step.
+  The app owns the step label and which step is current. See `docs/button.md`.
+- **Let an icon-state toggle skip selected chrome.** When a pressed toggle's
+  glyph already shows its state (an empty or filled star), set
+  `data-selected-chrome="none"` on that button, or `selectedChrome="none"` on
+  its `ToolbarControlGroup`; never override the group's pressed-button styles.
+- **Lay out a `ValueTable` through its props.** `labelWidth` sets a minimum
+  label column, `presentation="stacked"` puts values under labels, and
+  `stackBelow="compact" | "narrow"` stacks only while the table is narrower
+  than 512px/576px; do not override `--kui-value-table-row-columns`.
+- **Show selectable item summaries with `SummaryRow`.** One `role="option"`
+  per item as a list `row` or board `card`, with a state `rail`, a clamped
+  `title`, `trailingMeta`, a `metadata` line, `selected`, `dimmed`, and
+  `listEdge` rounding; the app owns the listbox and keyboard movement. Never
+  hand-roll ticket-row chrome.
+- **Group settings rows in `FramedList`.** For rows of arbitrary content in
+  one rounded frame with dividers between them (settings, account cards,
+  shortcut lists), compose `FramedListRow`s; `ValueTable` is the same frame for
+  label/value facts. Never hand-roll a `ul` with borders and row padding.
+- **Bound a result picker with a framed `List`.** For a bordered, scrolling
+  list of `ListItem` rows (search results, duplicate candidates), use
+  `<List scrollable frame maxHeight={rem(14)} minHeight={rem(4.25)}>`:
+  `frame` draws a 1px neutral border, the control radius, and a 4px inset
+  that keeps the first and last rows' focus rings inside the clip, and the
+  typed `CssLength` bounds need no flex-column ancestor. Never wrap a List in
+  an app div with `max-height`, `overflow`, and a border.
+- **Use `Button` for every standalone action, icon-only included.**
+  `Button` (`@kerfjs/ui/button`) is a native button in a `tone` (`neutral`,
+  `brand`, `success`, `danger`) and an `emphasis` (`primary`, `secondary`, `plain`), at
+  the 44px control height or `size="compact"`, with an optional `icon`,
+  `loading`, `href`, form `type`, `shape` (`rounded` or `pill`), and `pressed`
+  for a toggle. With an `icon` and `ariaLabel` but no label it is an icon-only
+  square (a circle as a pill). Brand secondary/plain labels darken the brand
+  token in light mode to stay legible on a quiet hover fill. Inside a `ToolbarControlGroup`
+  keep a native `button`; the group owns its geometry.
+- **Paint a strip's surface with `List surface`.** `surface="base"` or
+  `"raised"` fills a List and its insets with a solid surface (a banner strip
+  above a sunken work area); never wrap it in app CSS that sets a background.
+- **Use `TextField` for free text.** `@kerfjs/ui/text-field` is a native
+  input in one labeled box: `label` (or `ariaLabel`), `hint`, and `error` (its
+  description; an error marks it invalid), an optional `icon` and `clearable`
+  button, `multiline` with `rows` and a growing `maxRows`, and `maxLength` with
+  `showCount`, at the 44px height or `size="compact"`. Call
+  `wireTextFields(root)` (`@kerfjs/ui/wire-text-fields`) once for clearing and
+  counting. For `type="number"`, pass native `min`, `max`, and `step` as numbers
+  or strings (`step="any"` accepts arbitrary decimals). For `type="date"`,
+  pass an ISO date string and use the browser's native picker. `autofocus`
+  forwards to the native input or textarea for insertion and dialog open.
+  Never render `wa-input`
+  or `wa-textarea` for a form field.
+- **Use `Checkbox`, `CheckboxGroup`, `RadioGroup`, and `Switch` for native
+  toggles.** `@kerfjs/ui/checkbox` (with `indeterminate` and
+  `wireCheckboxes(root)` from `@kerfjs/ui/wire-checkboxes`),
+  `@kerfjs/ui/checkbox-group` (`label`, `name`, `choices`, an array `value`;
+  a labeled set laid out like RadioGroup), `@kerfjs/ui/radio-group` (`label`,
+  `name`, `choices`, `value`; one Tab stop, arrow keys), and
+  `@kerfjs/ui/switch` (`role="switch"`, only for a setting that applies
+  immediately) draw Kerf boxes over native inputs with hint and error text.
+  Stack standalone Checkboxes in a `List gap="xs"`: 8px apart, the same 28px
+  pitch as `RadioGroup` and `CheckboxGroup` choices. Never render
+  `wa-checkbox`, `wa-checkbox-group`, `wa-radio-group`, or `wa-switch`.
+- **Use `Combobox` to pick or create a value by typing.** A themed native
+  input on the ARIA combobox pattern with filtered suggestions and an optional
+  create option; `wireComboboxes(root, { onCommit })` reports `{ id, value,
+created, input }`. Never use a hand-styled `<input list>` + `<datalist>`.
+- **Pick or drop files with `FilePickerTrigger` / `FileDropZone`.** Both wrap
+  a real, visually hidden file input; `wireFilePickers(root, { onFiles })`
+  reports browsed and dropped files and highlights the zone while dragging.
+  Never hand-style a file input, its label, or a dashed drop target.
+- **Swap content in place with `ContentSwap`.** Two sides share one cell;
+  `active`, `transition` (`push`, `crossfade`, `none`), and `direction` drive
+  Kerf-owned motion with an inert, hidden inactive side and reduced-motion
+  fallback. Use `NavStack` for full views with toolbars.
+- **Lay out a kanban board with `ColumnTrack`.** Equal columns that never
+  narrow below `minColumnWidth` scroll sideways; `layout="paged"` pages one
+  column at a time with a peek and snapping. Never re-track a `Grid` or
+  hand-roll scroll-snap CSS.
+- **Show ambient activity with `EdgeActivityIndicator`.** A layout-free,
+  pointer-inert top-edge strip whose bars ripple while `busy`, with an optional
+  polite `message` pill; Kerf owns the wave and reduced motion. Never hand-roll
+  fixed bars, keyframes, or a hanging pill in app CSS.
+- **Host app-level progress in `CornerStatus`.** For a non-dismissible
+  "Loading…" or "Updating… N of M" with no home beside the affected work, put
+  a `StateBanner` (`urgency="status"`) inside `CornerStatus` and call
+  `wireCornerStatus` once: a top-layer manual popover at a safe-area-aware
+  corner, with no close button, light dismiss, Escape, or focus change. Never
+  position a banner with fixed-position CSS or hide a toast's close part.
+- **Style transient toasts with `@kerfjs/ui/overlay-toast.css`.** Import it
+  once and call `toast()` from `kerfjs/overlay` with `exitClass:
+'kui-toast-exit'` and `exitDuration: 200`: a bottom-edge, safe-area-aware
+  stack on the raised surface, `variant` tones, a `StateBanner` as the only
+  content, and reduced-motion-aware motion. Never use `wa-toast`.
+- **Style hover tooltips with `@kerfjs/ui/overlay-tooltip.css`.** Import it
+  once and call `tooltip(anchor, content)` from `kerfjs/overlay` with
+  `exitClass: 'kui-tooltip-exit'` and `exitDuration: 100`: the help tag's look,
+  wrapping at 40 characters. Icon-only Kerf controls already get help tags.
+  Never use `wa-tooltip`.
+- **Show and hide content with `Disclosure`** (`@kerfjs/ui/disclosure`): a
+  native details element with a DisclosureArrow on content-item geometry,
+  `plain` / `framed` / `sunken`, or `embedded` inside a `ContentItem` (no
+  margin, border, or padding of its own, a compact summary, `flush` `Text`
+  content); Disclosures sharing a `name` form an accordion. Never use `wa-details` or `wa-accordion`.
+- **Show progress with `ProgressBar` or `ProgressRing`** (`@kerfjs/ui/progress-bar`,
+  `@kerfjs/ui/progress-ring`): `value` of `max` (omit `value` for
+  indeterminate), a `label`, `valueText`, tones. Never use `wa-progress-bar` or
+  `wa-progress-ring`.
+- **Pick a value on a range with `Slider`** (`@kerfjs/ui/slider`): a native
+  range input drawn as a track, fill, and thumb, with `showValue`/`unit`,
+  `ticks`, and `hint`; call `wireSliders(root)` once. Never use `wa-slider`.
+- **Collect tags with `TagField`** (`@kerfjs/ui/tag-field`): SearchField's
+  token editor as a form field, a hidden input per tag; call
+  `wireTagFields(root, { onChange })` and re-render. Never use `wa-tag-input`.
+- **Pick from a fixed palette with `ColorSwatches`** (`@kerfjs/ui/color-swatches`):
+  a native radio group of named round swatches, one Tab stop, a ring that
+  does not depend on hue, and a `'transparent'` no-color swatch.
+- **Choose any color with `ColorPicker`** (`@kerfjs/ui/color-picker`): an area,
+  channel sliders that follow the color model (R/G/B, H/S/L, H/S/B, or gray)
+  plus opacity, RGB/HSL/HSB/Grayscale fields, hex, presets, and
+  samples; call `wireColorPickers(root, { onChange })` and re-render.
+- **Put a color in a form with `ColorField`** (`@kerfjs/ui/color-field`): a
+  swatch-and-hex trigger that opens a ColorPicker below it; call
+  `wireColorFields(root, { onChange, pickers })` and re-render. Never use
+  `wa-color-picker`.
+- **Size a Select through its API.** `triggerWidth` chooses `fit-content`,
+  `max-content`, or `fill`; `maxTriggerWidth`/`minTriggerWidth` bound it under any
+  presentation, ellipsizing even `renderSelected` content. For custom
+  selected text, use the public color, font-size, and font-weight tokens; the
+  closed value ellipsizes when space runs out. `presentation="title"` gives a
+  rail view heading a 36px bold, flush-start trigger and adjacent caret;
+  `focusRingInset` keeps its ring inside clipping ancestors.
+- **Configure application tabs at their owners.** TabBarItem's `icon-only`
+  presentation keeps `name` accessible, `labelMaxWidth` ellipsizes a long name,
+  `nameOverflow="visible"` shows the full name during inline loading, and
+  `dropTarget` highlights a drag-over without changing selection. `attention`
+  uses `--kui-tab-bar-item-attention-color`. TabBar's public
+  `--kui-tab-bar-strip-*` tokens set compact strip geometry.
+  An inspector TabBar uses the shared rounded rectangle radius on its strip
+  and inset segmented tabs; an ordinary segmented TabBar keeps pill ends and
+  smaller interior tab corners. Configure the presentation instead of
+  restyling TabBarItem.
+  Set `pinned` on the first TabBarItem to keep it visible within a scrolling
+  tablist; it remains in keyboard order. Use `--kui-tab-bar-item-pinned-background`
+  for the surrounding surface and keep that backdrop opaque.
+- **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 `TabNavigator` tab shows the dot
+  with `badge: true` plus its required `badgeLabel`. A text badge takes a
+  decorative leading `icon`, a `title` tooltip, and `data-*` `rootAttributes`
+  for app identity; never wrap a Badge or nest a `Row` in it for those.
+  For app-supplied text that can run long (a tag or category name), set
+  `maxWidth` (a `CssLength`, such as `px(160)`): the label truncates with an
+  ellipsis and string or number content becomes the hover `title`.
+- **Use `Chip` for removable tags.** Give the native remove button a delegated
+  `removeAction` and a specific `removeLabel`; the application updates the tag
+  list. `itemId` identifies the chip to the action handler. `size="compact"`
+  gives a 20px chip and 16px remove button; `disabled` disables removal.
+- **Use a link `Chip` for downloadable files and short links.** `href` renders a
+  native `<a>` with chip geometry; `download` (`true` or a file name) and
+  `external` (new tab, safe rel, announced) are optional, and a link chip has
+  no remove button. Inside a ContentItem bubble set `tone="inherit"` so it
+  follows the bubble's foreground instead of styling an anchor yourself.
+- **Use an action `Chip` for a value the user activates once.** `action` (with
+  `itemId`) renders the whole chip as a native
+  `<button type="button" data-action data-item-id>` for a delegated handler,
+  such as a search help filter token that inserts itself into the query, with
+  hover, press, focus-ring, and `disabled` states. `actionLabel` is an optional
+  accessible name that contains the visible label. It cannot also take `href`
+  or `removeAction`. A compact rounded action chip keeps a compact `Badge`'s row
+  height in a compact `ValueTable` cell; never make a `Badge` clickable.
+- **Use `ChoiceChips` for a wrapping exclusive choice.** When one value comes
+  from a visible set too large for a `SegmentedControl` track (a nine-color
+  palette in a 560px dialog), render separate pills backed by native radios:
+  one Tab stop, arrow-key selection, and a real form value under `name`. Name
+  the group with `label` or `labelledBy`, lead choices with a `swatch`
+  (`CssColor` such as `fillColor('#3b82f6')`, or `'transparent'` for the struck-through no-color dot) or an
+  `icon`, and handle the delegated `action` on `change`. Never wrap a
+  `SegmentedControl` or a joined button group instead. Set
+  `multiple: 'toggle'` (with a `readonly Value[]` `value`) when any number may
+  be on and each pill toggles alone: native checkboxes in a `role="group"`,
+  each a Tab stop that Space toggles. Set `multiple: true` for the desktop
+  multi-select: a listbox where a click selects one, Cmd/Ctrl toggles, Shift
+  extends, and hidden inputs submit under `name`; wire it with
+  `wireChoiceChips` (`@kerfjs/ui/wire-choice-chips`) and read the set with
+  `readChoiceChips`. On dark
+  inverse chrome, place the chips in a dark appearance scope (`.wa-dark`)
+  instead of restyling them.
+
+- **Open a scrolling view with `BackdropImage`.** Place it first in a Pane or
+  NavStack view's scrolling content: `parallax` (`subtle` or a 0 to 1 factor)
+  lags the image on a compositor-only scroll timeline, `blur` (`radius`,
+  `blurredSrc`, `dim`) cross-fades in a once-blurred copy as it scrolls away
+  (only opacity animates, never the filter), `fadeTo` (a `CssColor`)
+  dissolves it into a color that keeps painting under its `children`, and
+  `overlay` content sits over its block end with an optional `scrim`. Pass
+  `alt=""` for a decorative image. It is static under reduced motion,
+  `data-kui-effects="static"`, or without scroll-driven animations, and ends on
+  a hard edge (overlay on a solid `fadeTo` band) under reduced transparency. Never hand-roll scroll listeners or
+  `background-attachment: fixed`.
+
+- **Use `MessageComposer` for a chat or prompt composer.** `@kerfjs/ui/message-composer`
+  renders a raised frame (standard border, large radius, `shadow-l`) whose
+  border turns brand while focus is within, a borderless textarea that grows
+  between `minRows` (default 1) and `maxRows` (default 8) lines and then
+  scrolls, and a compact `Toolbar` action row: optional `leading` controls
+  (attach, a model `Select`), an optional quiet `hint`, and `trailing` actions
+  (a brand Send `Button`). Name it with a title-style `label`; give it
+  an `id` so the hint describes the field. Pass it as a `DialogSurface`'s
+  floating `footer` (`footerInset="none"`) over a transcript. Never rebuild
+  composer chrome around a `wa-textarea` with app CSS. For Enter-to-send, set
+  `submitOnEnter` and call `wireMessageComposers(root)` from
+  `@kerfjs/ui/wire-message-composers` once: Enter or Cmd/Ctrl+Enter clicks the first
+  trailing action, Shift+Enter inserts a newline, and an IME composition
+  commit or an empty message never sends. Never hand-roll that handler.
 
 ## Public exports
 
-`LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `FloatingToolbar`, `ToolbarText`,
-`PanelHeader`, `ListItem`, `ListActionRow`, `ListHeader`, `SegmentedControl`,
-`Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
-`wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
+`Badge`, `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarActionLink`, `FloatingToolbar`, `ToolbarText`, `Text`,
+`ListItem`, `ListActionRow` (+ `wireListReorder`, `reorderListItems`), `wireListFocusScroll`, `ListHeader`, `ListInsetControl`,
+`ListInsetText`, `SegmentedControl`, `ChoiceChips`, `MessageComposer`,
+`Select`, `SearchField` (+ `readSearchField`, `placeSearchFieldCaret`,
+`wireSearchFields`), `TabBarItem`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
+`wireScrollDividers` (scroll-state dividers for every `Pane`, `NavStack`,
+`TabNavigator`, and `TabBar`),
 `ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
 `LoadingSpinner`, `Skeleton`, `ValueTable`, `ValueTableRow`. Whole-screen layouts (opt-in,
-tree-shakeable, declarative with `wire…` helpers, each with a companion CSS import):
-`NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
+tree-shakeable, declarative with `wire…` helpers; the browser build of each layout
+subpath loads its CSS and that of the components it renders, and a companion
+CSS subpath remains for pipelines without the `browser` condition):
+`NavStack`, `SplitView`, `Workbench`, `TabNavigator`, driven by `deviceClass()` from
 `@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
 shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
-+ `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
-`@kerfjs/ui/catalog` is another opt-in shell — a
-`Catalog` component + `wireCatalog` helper for building a component-gallery catalog
-(collapsible category sidebar + preview stage + resources footer) from your own
-entries; controlled/stateless like the layouts. `@kerfjs/ui/webawesome` is a
-type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
-declared side effects.
+
+- `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence; a compact overlay starts closed and opens only on a user action, and `inlineCollapsed` declares a panel's inline default).
+  `@kerfjs/ui/catalog` is another opt-in shell — a
+  `Catalog` component + `wireCatalog` helper for building a component-gallery catalog
+  (collapsible category sidebar + preview stage + resources footer, with
+  focus-preserving active-row reveal for long desktop sidebars) from your own
+  entries; controlled/stateless like the layouts. Its optional contrast, reduced
+  motion, theme, and preview-background controls are built in; pass state and
+  `wireCatalog` callbacks instead of recreating their toolbar markup, while your
+  app owns applying and persisting preferences. For any Catalog demo, follow
+  the [authoritative authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)
+  rather than inferring structure from the shell or private CSS. The shipped
+  Catalog stage fills the preview scroller for short specimens and grows with
+  tall ones in every consumer; do not add a demo-specific height or backdrop
+  override.
+  `@kerfjs/ui/webawesome` is a
+  type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
+  declared side effects.
 
 ## Reference
 
 - [skill.md](./ai/skill.md): the full rule set + a common-mistakes table (the shipped AI skill).
 - [design-philosophy.md](./docs/design-philosophy.md): why kerf UI is shaped this way — the decision principles behind the rules above.
+- [writing.md](./docs/writing.md): interface copy — the title-style vs. sentence-style capitalization rule per element, from Apple's guidance.
 - [layout.md](./docs/layout.md): the pane/content-item geometry, public roles/tokens, and the spacing scale.
 - [component-contract.md](./docs/component-contract.md): what a component owns vs. what the app owns.
 - [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
 - [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
-- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
-- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists).
-- [component-catalog.json](./ai/component-catalog.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts and exact signatures.
+- [workbench.md](./docs/workbench.md): the `Workbench` multi-panel shell, its collapse policies, and opt-in `resizable` panels driven by `wireWorkbench` (`@kerfjs/ui/wire-workbench`: drag, keyboard, min/max, persistence, compact suspension), the `mainMinSize` / `mainMinHeight` work-area minimums (default 320px wide beside any inline rail, 120px tall above the drawer) that resizable panels stop at and inline panels shrink around, and a panel's `responsiveOverlayAt` (`narrow` / `compact`, rails and the bottom drawer) that presents it as an overlay below a Workbench container breakpoint without a device-class check; a panel given its `collapsed` signal is a transient overlay (collapsed on entering the breakpoint, takes focus and keeps Tab inside while open, closed by Escape or an outside press, focus returned; `dismissOverlays`), and overlays are exclusive by default (opening one closes the others; `exclusiveOverlays: false` opts out).
+- [workbench-dialog.md](./docs/workbench-dialog.md): `WorkbenchDialog`, the modal workbench dialog type: the title, actions, and close control in the work area's toolbar, full-height rails with their own toolbars, and overlay rails on compact devices.
+- [list-detail-dialog.md](./docs/list-detail-dialog.md): `ListDetailDialog`, the modal list-detail dialog type: full-height list and detail columns, the title and close control in the detail column, and a compact full-screen `NavStack` drill-down.
+- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabNavigator` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
+- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome integration theme; catalog coverage means themed-and-supported for integration applications, not preferred. The UX sidebar tags every element a Kerf component replaces as `Discouraged`; Popup remains an available conditional positioning primitive.
+- [webawesome-migration.md](./docs/webawesome-migration.md): moving an application from Web Awesome elements to their Kerf replacements, then removing Web Awesome.
+- [ai/components/README.md](./ai/components/README.md): the generated per-component markdown reference — the assistant entry point over both JSON catalogs.
+- [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.
+- [compile-time-contracts-v1.json](./ai/compile-time-contracts-v1.json) + [type-contracts.md](./docs/type-contracts.md): stable compile diagnostics, packed-declaration proof, migrations, and explicit non-goals.
 - [README.md](./README.md): package overview and the component subpath table.
+
+Neutral lowered surfaces and decorative neutral fills/borders are translucent theme colors; compose nested public components directly. Default/raised canvases, foregrounds, focus indicators, and loud contrast-bearing fills remain opaque. Do not assign depth-specific component tokens in demo wrappers.
+
+Navigation transition continuity: `wireNavStack` slides the incoming view over the preserved previous view on push and the outgoing view off on pop, cross-fades both live chrome surfaces with inert snapshots, and settles/cancels an interrupted transition before starting the next. Reduced motion and duration zero settle immediately.
+
+For a tab scene with drill-down, put a `NavStack` directly in `TabNavigatorTab.content`, configure each view's top `toolbar` and `pane`, and omit `bottomToolbar` at both levels so the scaffold bar remains the only bottom chrome. Wire both components on their own roots. The catalog's **NavStack inside a tab** example exercises push and tab switching.
+
+`Pane.deepInset` (and `PaneConfig.deepInset`) or `TabNavigatorTab.deepInset` on a plain scene adds 8px on all four sides of the scroll content, so ordinary 8px item margins land 16px from the inline edge. Nested Row/List/Grid spacing stays at its default. Set a nested scene's Pane option instead of insetting its entire NavStack or toolbar.
+For a child table whose decoration spans the Pane while its text stays aligned, use the Pane content slot's inherited `--kui-pane-content-inset-inline-start` and `--kui-pane-content-inset-inline-end`: negate them for the child's logical margins and add them to cell padding. They include safe areas and `deepInset`; see `docs/app-layouts.md#edge-to-edge-content-inside-a-pane`.
+
+`ToolbarText` and `ToolbarControlGroup` accept typed `hideBelow`/`showBelow`
+lengths (for example `px(416)`). Wire `wireToolbarVisibility(root)` from
+`@kerfjs/ui/wire-toolbar-visibility` and dispose on unmount. Thresholds use the
+nearest Toolbar content-box width: hideBelow hides strictly below, showBelow
+shows strictly below, with complementary behavior at equality. Percentages use
+that content width; em and custom properties use the item's own context. Invalid,
+negative, unresolved, or contradictory values leave the item visible under this
+width policy. Keep primary actions visible and offer a complementary overflow
+group. See `docs/component-contract.md` "Toolbar width visibility" for lifecycle
+details.
+
+Select menus use native viewport shifting with 10px gutters: default menus grow to content (up to 20rem), while `fitMenu` matches trigger width and long labels wrap. A listbox (like a PopupMenu menu) shifts only along its trigger's edge, never over the trigger: when neither side fits, it opens on the side with more room and scrolls inside its capped height, so a second press on the trigger still closes it. Keep popup sizing and position repairs out of consumer CSS.
+
+Key sibling `DialogSurface`s that render conditionally with `rootAttributes={{ "data-key": "…" }}` so a re-render morphs each dialog into itself; never wrap one in a keyed app `div`. Modal `DialogSurface` bounds use typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`); explicit caps stay within the dynamic viewport minus both gutters. Omitted props keep the default caps (20px clear of each edge, 80% of the viewport height at 420px wide or narrower). Application render state chooses responsive values, and preview layout remains application-owned. `height` sets a definite bounded modal size and `bodyLayout="fill"` lets one child fill the body; `bodyLayout="fill-last"` keeps leading rows at their height above one filling last child, and `footerPresentation="floating"` (with a typed `footerOffset`) floats a chat composer over the body while the body reserves its measured height; give the transcript `scrollClearance="block-end"` (a `scrollable` `List` or a `Pane`) to let it scroll beneath the composer, with the last message still resting above it, through the published `--kui-scroll-clearance-block-end` context (overlaying chrome publishes `--kui-scroll-clearance-block-start` / `-end`; one scroller per covered edge opts in; a composed Pane opts in through `PaneConfig.scrollClearance` on a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`). `headerPresentation="floating"` lays the title bar over the body on the translucent `--kui-chrome-material-raised` (opaque under reduced transparency, increased contrast, and forced colors); the register measures it and the body reserves it, and a `fill` body's only child with `scrollClearance="both"` scrolls beneath both the title bar and a floating composer through the published `--kui-scroll-clearance-block-start`. `presentation="bottom-sheet"` attaches the dialog to the bottom edge with square bottom corners, safe-area and virtual-keyboard clearance behind the panel, and a slide in/out (`enterMotion` / `exitMotion`); `resizable` adds a top grabber separator bounded by `minHeight` and `maxHeight`. `PopoverDialogSurface` is the non-modal, light-dismiss counterpart on the native Popover API, with the same size props and an `embedded` in-flow presentation; `describedBy` sets its `aria-describedby` (usually a title `ToolbarText`'s `descriptionId`).
+
+Render a modal dialog as `DialogSurface` itself, a native `<dialog>` (`alert` renders `role="alertdialog"` for a destructive confirmation; pair it with `describedBy` on the message): `label` (or `labelledBy` with a `heading`, such as an xl `ToolbarText` with a description) names it, `describedBy` (the heading ToolbarText's `descriptionId`, or app-owned summary copy) describes it as `aria-describedby`, `children` is its body, `footer` holds its buttons, and `headerActions` sit before its close button (`withoutHeader` drops the header for content that owns its heading and close control). Open it with `openDialog(dialog)` and close it with `closeDialog(dialog)` from `@kerfjs/ui/surface-scaffold`; never toggle its `open` attribute. The close button, any `data-dialog-close` element inside (a Cancel button), Escape, and, with `lightDismiss`, a backdrop press dispatch a cancelable `kui-request-close` (`detail.source`: `close-button`, `escape`, or `backdrop`); cancel it to keep the dialog open (the panel pulses). The native `close` event fires once it closes. `openDialog` installs the listeners and, while the dialog is open, measures its floating header/footer, follows a bottom sheet's keyboard and grabber, and keeps that state across re-renders; import `@kerfjs/ui/surface-scaffold/register` only when a dialog may open some other way. Do not write `wa-dialog` inside a `DialogSurface`.
+
+Toolbar visibility measurement probes and invisible state children are helper-owned and survive Kerf rerenders through `data-morph-preserve`. Actual CSS visibility stays stable while rendering removes transient parent markers, preventing geometry-driven render feedback and repeated probe recreation. Toolbar replacement, explicit internal-node removal and disposal retain their existing behavior.