@kerfjs/ui 5.0.0-beta.8 → 5.0.0-beta.81

package/llms.txt

@@ -6,12 +6,41 @@
 > 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/menu-item`, `@kerfjs/ui/toolbar`,
+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"`.
+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 or photo-backed toolbar surface to
+match dark control groups. 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)
 
@@ -21,25 +50,255 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 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.
+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.
 
 ## Core rules (do the right thing)
 
+- **Prefer a Kerf UI component over a Web Awesome component over a raw HTML
+  tag**, using each for what it is good at. Never render a `Discouraged` Web
+  Awesome element (`wa-dropdown`, `wa-button-group`, `wa-select`, `wa-tab-group`,
+  `wa-icon`, …) directly; reach it only through the Kerf component that wraps or
+  replaces it (`PopupMenu`, `SegmentedControl`, `Select`, `TabBar`,
+  `LucideIcon`), 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`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
+  visibly bounded content item — over overriding its `--kui-*` token. CSS for genuinely new structure
+  belongs to the application-owned component that renders it and must not select
+  nested Kerf or Web Awesome components.
 - **Never double-inset.** A `.kui-pane` has no padding; its `.kui-content` children
-  own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
+  own the geometry (8px inline margin + 1px border + 8px padding). Render an
+  ordinary surface-like child as `ContentItem` (`@kerfjs/ui/content-item`) with
+  typed `frame` (`none`/`framed`) and `shape` (`rounded`/`pill`) props instead
+  of hand-writing `<div class="kui-content-item">`. Do not add a
   container padding on top of a content-item's own margin — pick one owner. Use
   `.kui-content` for 24px major vertical rhythm.
+- **Opt into document globals explicitly.** Import `@kerfjs/ui/document.css`
+  once for border-box sizing, token-backed body/link presentation, inherited
+  native table-cell and form-control font metrics, and zero body
+  margin. 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. 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; `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
+  `TokenSearchField` editor shrinks in narrow groups; its minimum width can be
+  set with `--kui-token-search-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.
+- **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. 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). 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.
+- **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. 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 and Enter/Space activation.
+- **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 also receive the shared 8px inline
+  outer inset because those groups have no bordered field shell. The Color
+  Picker trigger receives the same inset for the same unbordered geometry.
+  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` Web Awesome help tag repeating that name (and a Select's
+  choice) on hover and keyboard focus, hidden while the popup is open; the
+  register import installs it, so do not add a `title` or tooltip of your own.
+  The same installer tags an icon-only `<button>` or link inside a
+  `ToolbarControlGroup` named by `aria-label` (no visible text or `title`);
+  import `@kerfjs/ui/help-tags/register` once when a toolbar has such buttons
+  but no registered Select or PopupMenu.
+  The package names the internal combobox, including custom
+  selected content; consumers do not need shadow-DOM naming workarounds.
+  Import `select/register` once for the canonical animation lifecycle: stale
+  close/show completions cannot override a later request. Consumers must not
+  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
@@ -47,23 +306,101 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 - **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.
+  `TokenSearchField`, 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; reach for `wa-button` only when you
+  need a Web Awesome feature. 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;
+  use `context` with `openPopupMenuAt`/`closePopupMenu` for pointer-anchored row
+  menus. 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. Supporting 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.
+  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-token-search-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`.
+  Never add a border, or a permanent `dividerSides`, to fake one.
+  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,37 +409,130 @@ 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 or a standalone `wa-button` for its own
+  Web Awesome chrome. Managed
+  TokenSearchField 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.
+  The one richer case is `wireTokenSearchFields`, 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.
+  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`,
+  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.
 - **Placeholder loading state, don't rebuild it.** For a value or component that is
-  still loading, set `placeholder` on the component (`Select`, `MenuHeader`,
-  `MenuItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`,
-  `AppTab`, `ToolbarText`, `MenuActionRow`): 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`
+  still loading, set `placeholder` on the component (`Select`, `ListHeader`,
+  `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`,
+  `AppTab`, `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`
   (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
-  `LoadingSpinner` for known busy activity instead.
+  `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"` gives the
+  action a separate trailing row. The inline defaults remain compact.
+- **Size a Select through its API.** `triggerWidth` chooses `fit-content`,
+  `max-content`, or `fill`; `--kui-select-trigger-max-width` caps it. 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.** AppTab'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-app-tab-attention-color`. TabBar's public
+  `--kui-tab-bar-strip-*` tokens set compact strip geometry.
+  Set `pinned` on the first AppTab to keep it visible within a scrolling
+  tablist; it remains in keyboard order. Use `--kui-app-tab-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`.
+- **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.
 
 ## Public exports
 
-`LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarText`,
-`PanelHeader`, `MenuItem`, `MenuActionRow`, `MenuHeader`, `SegmentedControl`,
+`Badge`, `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarActionLink`, `FloatingToolbar`, `ToolbarText`, `Text`,
+`ListItem`, `ListActionRow`, `ListHeader`, `ListInsetControl`,
+`ListInsetText`, `SegmentedControl`,
 `Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
 `wireTokenSearchFields`), `AppTab`, `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
-`@kerfjs/ui/device-class`. `@kerfjs/ui/webawesome` is a type-only boundary for
-`wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the declared side effects.
+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; 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 an opt-in
+  transparent-bound and margin geometry overlay plus focus-preserving active-row
+  reveal for long desktop sidebars) from your own
+  entries; controlled/stateless like the layouts. 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.
+  `@kerfjs/ui/webawesome` is a
+  type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
+  declared side effects.
 
 ## Reference
 
@@ -111,8 +541,39 @@ tree-shakeable, declarative with `wire…` helpers, each with a companion CSS im
 - [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, master-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.
+- [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
+- [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).
+- [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 theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
+- [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. Keep popup sizing and position repairs out of consumer CSS.
+
+Modal `DialogSurface` bounds use typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`); explicit caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Application render state chooses responsive values, and preview layout remains application-owned.
+
+Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog` and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
+
+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.