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

package/docs/component-contract.md

@@ -2,6 +2,16 @@
 
 `@kerfjs/ui` components are plain functions that return Kerf `SafeHtml`. They have no component instance or lifecycle.
 
+### Shared semantic tones
+
+`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`.
+
 ## Selection boundary
 
 Begin with the [need-first component matrix](./component-selection.md). Reuse a
@@ -18,16 +28,292 @@ package delivery paths, Web Awesome's installed manifest, AI guidance, and
 documentation links. Nuanced prose in this contract and the selection guide
 remains authored rather than generated.
 
+### Markdown component reference (AI entry point)
+
+[`ai/components/README.md`](../ai/components/README.md) and one
+`ai/components/<id>.md` page per catalog entry are the assistant-facing view of
+both catalogs. An assistant reads the index, then only the pages it uses,
+instead of loading the full JSON. Each page merges the entry's selection facts
+(purpose, use/avoid, alternatives), delivery (JavaScript subpath, CSS,
+registration, wiring helpers), a link into `public-api-signatures-v1.md` for
+exact props, composition (parents, contexts, zones with their JSX prop and
+cardinality, children), state and wiring ownership including wiring-owned
+state attributes, geometry, accessibility obligations, public class and token
+hooks framed as a styling boundary (components own their styles; configure
+through props rather than overriding internals), and `KUI-C###` diagnostics
+with their conditions. `scripts/sync-component-docs.mjs` renders them only from
+`component-catalog.json` and `component-composition.json` (plus the signature
+file's module headings for anchors), sorted and Prettier-formatted;
+`check:catalog` rejects a stale, missing, or orphaned page. The JSON files stay
+the canonical tool-facing sources.
+
+### Composition catalog
+
+[`component-composition.json`](../ai/component-composition.json) adds a formal,
+machine-evaluable composition layer beside `component-catalog.json` without
+changing its selection and delivery contract; it is a generated companion, not
+a newer version of that catalog. Every component-catalog entry projects once,
+in order, under the stable qualified key `package:id`. Each composition entry
+explicitly covers parents/contexts,
+named zones and cardinality, optional explicit JSX prop bindings, child concepts, state ownership, required wiring,
+responsive ownership, layout and geometry, accessibility obligations, public
+CSS boundaries, diagnostics, and provenance. A wrapper entry may add
+`rendersAs`: the cataloged roots it renders (any one of them, or nothing), so
+composition checks treat its elements as each root rather than as an unknown
+child. A placement with listed parent constraints produces one `KUI-L201`
+diagnostic even when both the wrapper and a rendered root reject that parent.
+When one catalog entry exports another JSX component with different placement,
+`jsxExports` gives that export its own parent contract. The extra export does
+not stand for the entry's root when a parent zone is checked.
+An entry whose own geometry an owner already provides in some configuration
+declares `insetFreeChildren`: `{ prop, equals }` conditions under which its
+direct JSX children must bring no content-item inset (`Disclosure` with
+`appearance="embedded"`). A child brings that inset when its
+`layout.geometry` owns its margin, border, and padding (`self` on all three),
+unless one of its own `insetFreeWhen` conditions holds (`Text` with `flush` or
+`variant="span"`). `ui-composition` reports a child that statically brings the
+inset as `KUI-L204` and names the child's inset-free form when it has one.
+Generated `boundaries.rootClass` prefers the public `kui-<entry-id>` class when
+present, so a sibling export's class cannot become the entry's root class.
+
+`boundaries.placeableClasses` names the subset of `publicClasses` an
+application may write onto its own elements (layout utilities, the document
+root, item geometry on another carrier); absent means none, and every other
+public class is the component's rendered anatomy. `boundaries.rootElement`
+names the element a component renders around its own placeable classes
+(`content-item`: `div`), so a plain element of that tag carrying them is still
+the component recreated. `eslint-plugin-kerfjs`'s `ui-public-boundaries`
+reports both as `KUI-L103` with the export to render — for `@kerfjs/ui` and for
+every consumer catalog a `.kerf-ui-profile.json` declares, whatever the class
+prefix. `create-kerf-component` packages declare the same fields in
+`kerf.components.json`.
+
+`descendantRootAttribute` optionally names a `data-*` attribute on a
+cataloged `rootElement`. It anchors ownership of arbitrary unclassed child
+element selectors below that exact root, as `LucideIcon` does with
+`svg[data-lucide]`. Without the attribute in a selector, the analyzer uses
+only cataloged `descendantElements` and composed JSX evidence.
+
+An entry's optional `cssValueProps` makes CSS-adjacent prop grammar equally
+machine-evaluable. Each path records the property grammar, finite shorthands,
+canonical versus exceptional spacing choices, standalone and expression-only
+helpers, raw/unsafe policy, and serialization examples. Nested paths are
+dot-separated object members, each optionally suffixed with `[]` to visit
+every array element: `items[].property` for a value inside each array item,
+`iconTile.color` for a member of an object-valued prop. A member that is not a
+literal object or array (a tone string such as `iconTile="brand"`, a variable)
+is skipped rather than guessed. Consumer catalogs can publish the same facts;
+ESLint, `kerf-ui-analyze`, and `kerf-ui-doctor` then issue the same stable
+`KUI-L013`–`KUI-L017` feedback for application and third-party components.
+
+`wiring.stateAttributes` lists the **wiring-owned state attributes**: the
+`data-*` attributes a wiring helper writes at runtime, such as
+`data-handle-inset` and `data-resizing`, which `wireResizableRegions` puts on a
+`ResizableRegion`. Each entry names the attribute, the element that carries it
+(`on`), the `helper` that writes it, and what it means. An application must not
+render, remove, or treat these attributes as its own state; tools use the list
+to tell them apart from app-authored attributes. They are declared once, on the
+helper's wiring item in the component catalog, and the composition catalog
+flattens them. `check:catalog`
+reads each `wire*` helper's source and fails when its declarations differ from
+the `data-*` attributes it actually writes. First-party entries always carry
+the list, empty when their helpers write none; it is optional in extension
+catalogs.
+
+An extension catalog may add `wiring.sources` entries with `export` and
+`source` for each application-owned helper. The source path is relative to its
+package root; `ui-wiring` resolves helper imports through this file, including
+relative re-export barrels. Every named export must also appear in
+`wiring.helpers`.
+
+When a component's required wiring is the application's own root-delegated
+handlers rather than a named helper, list the `data-action` values it must
+handle in `wiring.actions`. Required wiring names at least one helper or action.
+`ui-wiring` accepts an action when a reachable module that imports `delegate`,
+`delegateCapture`, or `delegateActions` (from `kerfjs` or `kerfjs/actions`)
+names it as a string, selector, or table key; a cataloged component's own
+source never counts, because it renders the attribute.
+
+The selection catalog's `wiringProviders` lists public helpers that install
+other wiring helpers. The `ui-wiring` rule accepts a provider call for each
+helper it declares; `wireCatalog` provides `wireScrollDividers`.
+
+The generator starts with permissive defaults. An `any` mode records that the
+catalog has no defensible prohibition; it does not claim every composition is
+recommended. Objective rules live in
+`component-composition-rules.json` and may carry stable `KUI-C###`
+diagnostics. A tool reports a diagnostic only after proving its exact `when`
+condition. Subjective choice, product policy, and visual taste remain prose.
+
+Kerf UI calls component content positions **named `SafeHtml` prop slots**.
+Use `children` for one homogeneous primary region; use explicit named
+`SafeHtml` props for semantic positions or replacement content such as
+`header`, `footer`, `leading`, `trailing`, `icon`, and `action`. These are typed
+function-component props, not native web-component `<slot>` elements and not a
+generic `slots={{...}}` object. A composition zone declares `jsx.prop` only when tooling
+can soundly bind that zone to one public JSX prop; `children` is spelled
+explicitly. Zones without that binding remain guidance and are never guessed
+from their ids. Static tools inspect only visible JSX structure and leave
+dynamic `SafeHtml` expressions to runtime and accessibility evaluation.
+
+### Native named-slot assignment
+
+Every public visual component with one stable conceptual root accepts an
+explicit `slot?: string` prop and forwards it to that root on every render
+branch. Use it when a Kerf component is a light-DOM child of a custom element,
+for example `StateBanner({ title: 'Ready', slot: 'status' })`. Omitting the prop
+omits the attribute.
+
+This contract does not open a generic native-attribute bag: components still
+accept only their documented props and narrow extension-attribute objects.
+`ResizableRegion` and `CollapsiblePanel` are deliberately excluded because each
+can return a region plus a sibling restore control, leaving no single root that
+can truthfully own native slot assignment. Their single-root controls and all
+alternate-root branches of supported components retain the contract.
+
+Component-catalog consumers continue unchanged. Composition-aware consumers
+read `component-catalog.json` for selection/delivery and
+`component-composition.json` for composition. `npm run catalog:sync` projects every new component,
+recipe, and supported Web Awesome entry, and the completeness gate prevents
+silent omissions. Downstream catalogs use the composition extension schema and types,
+retain their own package identity, and qualify cross-catalog references. See
+the checked
+[`component-composition-extension.json`](./examples/component-composition-extension.json)
+application-owned example.
+
+### Compile-time contract boundary
+
+The versioned
+[`compile-time-contracts-v1.json`](../ai/compile-time-contracts-v1.json)
+artifact maps stable `KUI-T###` ids to public imports, emitted symbols, and
+catalog identities. Its positive/negative fixture compiles against both source
+and a freshly packed package, so source declarations and shipped declarations
+cannot silently diverge. See [Compile-time contracts](./type-contracts.md) for
+the full audit, migration guidance, and the relationships deliberately left to
+runtime/catalog checks because TypeScript cannot prove them.
+
+### Application UI profile
+
+The component catalogs describe what packages provide; an application profile
+describes which supported choices a project has approved. A workspace may
+check in `.kerf-ui-profile.json` conforming to
+[`application-ui-profile.schema.json`](../ai/application-ui-profile.schema.json).
+Keep package-qualified catalog locations and recurring-concept preferences,
+allowed color schemes and density, public semantic-token overrides,
+layout/responsive conventions, application wiring entry paths, and narrow rule exceptions there. Product
+records, copy, permissions, user preferences, and transport state do not belong
+in this policy file.
+
+Every catalog location names a composition artifact. `selection` is optional
+for consumer packages whose generated metadata declares component-catalog
+selection guidance not applicable; `@kerfjs/ui` retains its required
+`component-catalog.json` selection artifact. This
+lets a generated `component-composition.json` participate directly without a
+fabricated compatibility file.
+
+Discovery and precedence are deterministic:
+
+1. Load `application-ui-profile.defaults.json` from `@kerfjs/ui`.
+2. Load `.kerf-ui-profile.json` at the workspace root when present.
+3. Walk from the workspace root toward the target directory and load each
+   directory-local profile in parent-to-child order.
+
+Later scalar and object-map values win. Catalogs merge by package; preferences
+and token overrides merge by key; exceptions merge by stable id. Lists such as
+allowed themes/densities replace the earlier list rather than accumulating.
+`wiring.entries` similarly names workspace-relative application entry modules;
+later profile layers replace the entry list. The `ui-wiring` ESLint rule checks
+application-scoped helper calls and registration imports once at each entry
+that reaches a rendering module, while a composition entry with
+`wiring.scope: "module"` keeps a local obligation. See the
+[`ui-wiring` rule](../../eslint-plugin/docs/rules/ui-wiring.md).
+Every resolved field retains its source file. The shipped
+`application-ui-profile.mjs` API implements discovery, merge, loading, and
+validation and reports actionable originating file + JSON-path diagnostics for stale
+catalogs, unknown component/rule/token references, preference conflicts, and
+broad exceptions. Each raw layer is validated against the catalogs effective at
+that exact precedence point before merge, so a broken parent catalog, stale
+parent reference, invalid value, or unknown field cannot disappear merely
+because a child profile replaces it. The shipped
+`application-ui-profile-sync.cjs` projects the same merge and validation contract
+for synchronous hosts such as ESLint rules; it deliberately performs no async
+I/O.
+See the
+[`application-ui-profile.json`](./examples/application-ui-profile.json) example.
+
+The package defaults avoid every `Discouraged` Web Awesome entry — each
+`webawesome` catalog entry whose `recommendation` is not `supported` — under a concept whose `preferred` value is the
+Kerf component that wraps or replaces it (`command-menu` → `PopupMenu`,
+`value-selection` → `Select`, `application-tabs` → `TabBar`, `icon` →
+`LucideIcon`, `resizable-pane` → `ResizableRegion`, `exclusive-choice` →
+`SegmentedControl`, `hierarchy-navigation` → `List`, `embedded-media` →
+`ContentItem`, `anchored-surface` → `AnchoredSurface`, `content-container` →
+`ContentItem`, `inline-status` → `StateBanner`, `application-shell` → the
+app-shell recipe, `modal-dialog` → `DialogSurface`). `eslint-plugin-kerfjs` `ui-preferences` (`KUI-L301`, also run by
+`kerf-ui-doctor`) therefore reports a Discouraged element written directly as a
+JSX tag (`<wa-dropdown>`) as well as through an imported component. A declared
+component's own source file is exempt, because that wrapper is the sanctioned
+owner of the element it renders. A unit test holds the avoid set and the
+catalog's Discouraged set equal in both directions, so neither can drift. A
+product that genuinely needs one of these elements records a narrow `KUI-L301`
+profile exception for the file that renders it.
+
+Catalog detail footers use one standard resource vocabulary and order. Build
+them with `catalogResources()` from `@kerfjs/ui/catalog-resources`: `Demo Source`
+first, optional `Component Source` and `Design Template`, then `Guidance`.
+Third-party entries use the typed `integrationGuidance` kind, which renders
+`Integration Guidance`, and omit `Component Source` when the implementation is
+not owned by the catalog's project. Prefer these semantic kinds over local labels
+such as “View source” or “Read UI guidance”; the helper makes that convention a
+compile-time choice while still returning ordinary `CatalogResource[]` values.
+
 ## Ownership boundaries
 
-- Components own semantic markup, stable anatomy, documented variants, ARIA projection, and package CSS hooks.
+### Geometry ownership metadata
+
+The canonical [`component-catalog.json`](../ai/component-catalog.json) records
+the margin, border, and padding owner for every component and composition under
+`geometry`. Read it before adding a wrapper or local spacing rule:
+
+- `self` means the entry's public visual contract supplies that geometry.
+- `parent` means the embedding layout must supply it.
+- `child` means composed descendants supply it; the entry's outer shell does not.
+- `none` means that dimension is intentionally absent from the standard contract.
+- `conditional` means a variant, part, or configuration changes ownership; the
+  accompanying `notes` explain the boundary.
+
+The values describe public ownership, including themed shadow parts, rather
+than merely asking whether a CSS declaration appears on the host element.
+Recipes are exempt because they arrange entries whose individual ownership is
+already cataloged.
+
+Downstream packages and applications should publish the same contract for their
+reusable visual components. Use
+[`component-catalog-extension.schema.json`](../ai/component-catalog-extension.schema.json)
+and copy the structure of the checked
+[`component-catalog-extension.json`](./examples/component-catalog-extension.json)
+example. Keep app and Kerf entries as package-qualified inputs, then let people
+or AI tools search their combined entries and compare `geometry` before adding
+wrappers or insets. Do not add app-owned entries to Kerf's canonical catalog or
+claim Kerf delivery paths for them.
+Packages that keep a `kerf.components.json` can generate this file instead of
+hand-maintaining it: set `kerfComponentCatalog.selectionOutput` and run
+`kerf-component-catalog` (see `create-kerf-component`'s README).
+Extension entries may add `uses` for direct composition dependencies and
+repository-relative `source` and `demoSource` files. Resolve each dependency
+against the combined Kerf and consumer catalogs; do not duplicate a Kerf id.
+For Doctor's opt-in component ownership mode, add `styleSources` with the CSS
+paths each entry owns, relative to the consumer package root.
+
+- Components own semantic markup, stable anatomy, documented variants, ARIA projection, and package CSS hooks. They may render and style raw HTML or Web Awesome implementation elements they create and control. A nested Kerf or application component remains its own owner even when the parent renders it.
 - Applications own signals/stores, product copy, domain-state mapping, persistence, routing, permissions, and transport.
 - Actions are `data-action` strings. Wire them at a stable root with `delegate()` or `delegateActions()` and retain the disposer.
 - A reusable component never owns per-instance mutable module state.
-- Consumers style through `--kui-*` semantic tokens and public component classes. Foundation tokens provide opinionated neutral, brand/info, success, warning, and danger fill/border/foreground roles. Stateful components expose local override variables; prefer an equivalent prop or token before writing a selector.
+- Consumers configure presentation through component props and documented `--kui-*` semantic tokens. Foundation tokens provide opinionated neutral, brand/info, non-status pop, success, warning, and danger fill/border/foreground roles. Application stylesheets must not select package component classes or descendants. If genuinely new structure needs CSS, encapsulate that structure and its stylesheet in an application-owned component; configure any nested Kerf components through their public APIs. A thin composition that only connects other components should normally have no stylesheet. It may style only raw elements or layout it owns, never its component children.
 
 `ListItem.rootAttributes`, `ListActionRow.rootAttributes`,
-`ListHeader.rootAttributes`, and `AppTab.rootAttributes` accept
+`ListHeader.rootAttributes`, `TabBarItem.rootAttributes`,
+`CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` accept
 application-owned `data-*` metadata without
 adding product fields to the shared API. A `ListActionRow` trailing action uses
 `trailingActionAttributes`, and a `ListHeader` action/disclosure uses
@@ -36,11 +322,11 @@ the corresponding `aria-controls`/`aria-haspopup` relationship. These slots do
 not accept roles or component-owned action, selection, disclosure, accessible
 name, disabled, or icon fields. Extension objects are filtered at runtime,
 including case-insensitive rejection of protected `data-*` names, and the
-component writes its protected attributes after the accepted metadata. Typed,
+component or helper writes its protected attributes after the accepted metadata. Typed,
 structurally widened, and JavaScript callers therefore cannot replace its
 contract.
 
-`AppTab.closeIcon` and `ResizableRegion.handleIcon` replace dormant decorative
+`TabBarItem.closeIcon` and `ResizableRegion.handleIcon` replace dormant decorative
 glyph content only. They must not contain controls or interactive roles. The
 component continues to own the named close button or focusable separator, and
 `wireTabBars()` / `wireResizableRegions()` continue to own transient behavior
@@ -51,29 +337,166 @@ and disposal.
 contain controls. When a row needs an independently interactive trailing
 region, `ListActionRow` owns the noninteractive root and the two sibling native
 buttons; the application owns their delegated behavior and controlled state.
+A `ListActionRow` with `trailingMenu` composes a real `PopupMenu` as that
+sibling trailing control instead of a button; the menu styles its trigger in
+the row's context from `popup-menu.css`, and the row never styles it.
 Both row components align a leading icon with the first label line when
 `multiline` allows the label to wrap; additional lines extend below that fixed
 visual anchor.
 
+`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.
+
 ### Public CSS anatomy
 
 The `publicClasses` array on each entry in
-[`component-catalog.json`](../ai/component-catalog.json) is the exact supported
-anatomy boundary. A scoped selector may join documented public classes, such as
-`.workspace .kui-toolbar .kui-toolbar__trailing`, when composition-specific
-layout cannot be expressed by a prop or token. A class being public does not
-make copied component markup an invocation or transfer state and accessibility
-ownership to the application.
-
-Do not select a component's descendant by element name, id, attribute alone, or
-an unlisted implementation class. Selectors such as `.kui-state-banner span`,
-`.kui-list-item [data-state]`, and `.kui-list-item .local-label` depend on
-private structure. If no prop, token, or cataloged class expresses a recurring
-need, request a supported hook instead of inferring one from rendered markup.
-
-`DisclosureArrow` uses an 18px root-scaled visual by default. Override
-`--kui-disclosure-arrow-size` on the component or its containing scope when a
-consumer needs another size. Kerf `Select` uses a separate Web Awesome expand
+[`component-catalog.json`](../ai/component-catalog.json) identifies stable
+anatomy for diagnostics, tooling, browser assertions, and package-owned
+composition. It is not an application customization API. Applications choose
+documented props and tokens; package components may compose other components
+only through those public contracts, never by styling a child's classes from a
+parent stylesheet.
+
+Inside the package, a component never styles another component or writes
+another component's variables. When a child must adapt to a composing parent,
+the child styles itself in that context from its own stylesheet: the parent's
+class and state appear only in an ancestor compound, the styled compound is
+the child's own class (or one of the child's own unclassed internals below
+it), and the child reads context values the parent provides under the
+parent's name. `ResizableRegion` widens its edge extent by the unsafe inset a
+split `SplitView` provides, and a `Skeleton` derives its fill from a solid
+`Badge`'s on-solid color, both in their own stylesheets; an `TabBarItem` rounds its
+outer corners in a segmented `TabBar` and shares a fill-allocated strip from
+`tab-bar-item.css`. An inspector `TabBar` uses the shared 12px rounded rectangle
+radius on its strip; its segmented `TabBarItem` corners follow that strip's inner
+curve, while an ordinary segmented strip keeps its pill ends and smaller
+interior corners. A `PopupMenu` sizes
+its trigger and applies a group's `menuInset` in its own stylesheet, and an
+icon-only `Select` reads the control slot a `ToolbarControlGroup` provides
+(`--_kui-toolbar-control-group-slot-*`). A parent may still style its own
+elements keyed on a child's state, naming the child by class inside `:has()`
+(`:has(> .kui-select[open])`, or `TabBar` insetting a segmented strip that
+holds compact tabs), and it keeps styling raw native and raw Web
+Awesome children no kerf component owns, excluding kerf children by class
+(`wa-dropdown:not(.kui-popup-menu)`). `npm run check:css-ownership` enforces
+this in every component stylesheet (a same-basename `.css` and `.tsx` pair
+under `src/components/<family>/<component>/`), deriving the component names,
+the Web Awesome tags each component renders, and its composed children from the
+colocated component source:
+
+- **Foreign classes.** Another component's class or `[data-component]` may
+  appear only in an ancestor compound or inside `:has()` / `:not()`; the
+  styled compound is the stylesheet's own class.
+- **Owned Web Awesome tags.** Kerf components are named by class, never by a
+  `wa-*` tag they render. A tag another component renders — as the
+  subject, or as an ancestor whose internals the rule reaches — must be scoped
+  to that component by its class or excluded with `:not()`. A direct child
+  that cannot be the owner's internal
+  (`.kui-toolbar-control-group > wa-button`) needs no exclusion.
+- **Variables.** A stylesheet writes only its own `--_kui-<self>-*` private
+  variables, and never overrides a public `--kui-<other>-*` token that another
+  component reads. Shared foundation tokens (`--kui-layout-*`,
+  `--kui-color-*`, …) are not any one component's. Context a parent provides
+  is named after the parent.
+- **Context on any child.** Custom properties set on a subject that can be any
+  element (`.kui-x > *`, `> :not(…)`) also land on composed components' roots.
+- **Hook classes.** A class the component places on a composed kerf child's
+  root (`<ToolbarText className="kui-nav-stack__title">`, a class NavStack once styled) may not be styled;
+  the child styles itself in that context instead.
+
+The documented exceptions live with their reasons in
+`scripts/lib/css-ownership.mjs`, and an exception that stops matching fails the
+check, so the list only shrinks. The layout regions' inherited edge-inset
+context (`--kui-edge-inset-*` handed to a sole Pane or layout child and cleared
+for any other content, and a Toolbar clearing it for its zones) is the one
+design exception; the others name the open fix ticket. The scroll-clearance
+context (`--kui-scroll-clearance-block-*`) needs no exception: overlaying
+chrome publishes it on its own element (a `DialogSurface` on its dialog body,
+a `Pane` overlay header, through `wireScrollDividers`, on its own Pane root).
+A scroll owner reads it only through its own `scrollClearance` prop, or, for an
+overlay-header Pane's content, through its own `headerPresentation`.
+
+The surface context needs no exception either. A component that changes the
+background behind its children publishes, on its own painted element, the
+foundation tokens `--kui-color-surface-current` (the opaque surface beneath:
+a raised `DialogSurface`, popover dialog, `AnchoredSurface`, or `List`
+`surface`, and a sunken Pane's opaque auto chrome, set it and clear both
+layers), `--kui-color-surface-current-region` (a layout region's fill: a sunken
+`Pane`, `Workbench` area, or `TabNavigator` scene, and a `Pane`'s or
+`TabNavigator`'s app `background`), and `--kui-color-surface-current-tint` (a
+content surface's fill: a `SunkenPanel`, a sunken `Disclosure`, a lowered
+`FramedList` and its highlighted row, a quiet, hovered, pressed, or selected
+`ContentItem`, a `TabBar` strip, and translucent glass chrome at rest — a
+`Pane` overlay header, `NavStack` overlay chrome or bottom toolbar, a
+`TabNavigator` overlay bar, and a dialog's floating header; clear chrome
+paints nothing and keeps the inherited context). Interactive rows (`ListItem`,
+`ListActionRow`, `SummaryRow`) are buttons or links themselves, so no control
+nests on their hover or selection fill and they publish nothing. They are undeclared at `:root`
+and a scoped `[data-kui-tint]` resets them. A control that must match what
+lies behind it (the inset focus ring's inner line on `Button` and
+`SplitButton`) layers tint over region over the opaque color, falling back to
+`--kui-color-surface`. Custom properties cannot fold an inherited value into a
+new one, so a content surface inside a sunken region composes exactly while a
+third translucent level keeps only the innermost content tint. An application
+surface that paints its own background sets the same tokens on its own root.
+
+Applications and component packages built on the package follow the same
+rules, and the downstream tools enforce them against the composition catalog
+instead of package source: `kerf-ui-analyze` / `kerf-ui-doctor` report a rule
+whose subject is another package's component (`KUI-L019`), another
+component's private `--_*` variable (`KUI-L020`), an override of a token a
+typed prop sets (`KUI-L021`), and a hook class on a component's root
+(`KUI-L022`), plus borrowed public classes in source markup (`KUI-L023`);
+`eslint-plugin-kerfjs`'s `ui-component-ownership` reports
+`KUI-L020` / `KUI-L021` in script. Both share the selector parsing in
+`analyzer/selectors.mjs` with `check:css-ownership`, and
+`check:css-ownership` fails when a component renders a Web Awesome tag the
+catalog does not list, so `KUI-L019` keeps covering every tag a kerf component
+renders. Each finding names the configuration to use and routes a missing
+prop to a component-gap report (see [the analyzer guide](./ui-analyzer.md#component-ownership-kui-l019kui-l023)).
+
+The composition catalog additionally requires `boundaries.rootClass` to be
+either one exact member of `publicClasses` or `null` when the entry has no
+rendered class root. Runtime geometry tooling uses this explicit field; array
+order never implies root ownership.
+
+Do not select a component root or descendant by class, element name, id, or
+attribute. Selectors such as `.workspace .kui-toolbar`,
+`.kui-state-banner span`, and `.kui-list-item [data-state]` cross the ownership
+boundary. If no prop or token expresses a recurring need, add the configuration
+to the owning component instead of inferring it from rendered markup.
+
+`Badge` owns the complete visual treatment for compact status, count, category,
+and metadata labels. Configure its semantic `tone`, `appearance`, `shape`, and
+`size`; do not recreate or override badge anatomy in an application or consuming
+component. Use `label` when visible content is abbreviated and `ariaHidden` only
+when a surrounding component already includes the same value in its accessible name.
+Every tone's text and solid fill use that tone's `--kui-color-{tone}-on-fill`
+token (`neutral` uses the text colors), the foreground tuned to clear WCAG AA
+(4.5:1) on the tone's fills in light and dark mode.
+
+`ListItem` renders its leading icon and nested SVG at a root-scaled 18px by
+default while retaining the row's 44px minimum interactive target. Multiline
+rows align that 18px visual with the first inherited text line. The row clips
+descendant painting to its rounded root so labels, status, and dormant trailing
+content cannot escape its visible boundary. Rows with descriptions grow enough
+to keep their owned two-line label stack readable; use `multiline` when the
+primary label should wrap rather than truncate. A single-line row ends its
+primary label and description with an ellipsis before the trailing status
+slot, even when the label is one long word; a `multiline` row wraps instead,
+breaking a word wider than the label column (a long component or file name)
+rather than letting it run under the trailing slot. A string label in a
+`multiline` row gets line-break opportunities at its camelCase and acronym
+boundaries, so `QuickTicketComposer` wraps as `QuickTicket` / `Composer`
+rather than mid-word; breaking anywhere is only the last resort for a single
+word that is still too wide. The text and accessible name are unchanged. `ListActionRow` labels
+follow the same single-line and `multiline` rules before the trailing action.
+
+`DisclosureArrow` uses an 18px root-scaled visual by default. Pass its typed
+`size` prop when a consumer needs another size. Kerf `Select` uses a separate Web Awesome expand
 glyph contract, `--kui-disclosure-icon-scale: .5`; changing one contract does
 not implicitly change the other. Direction changes take the shortest rotation
 path; a 180-degree closed-to-open tie uses counterclockwise rotation.
@@ -82,53 +505,246 @@ In `ListHeader` toggle mode, omitting `actionIcon` composes the production
 `DisclosureArrow` and derives its visual direction from `expanded`. The app
 must update that controlled state and reveal or hide real content. Passing a
 custom `actionIcon` replaces the default rather than layering or rotating both.
-The root fills the available inline width after its standard margins. A
-separate action stays at the logical end in its 44px target while the visible
-glyph defaults to 18px through `--kui-list-header-action-icon-size`.
+The root fills the available inline width after its standard margins by
+default. Set `inline` when it must shrink-wrap beside surrounding content; that
+presentation removes the root margin, border, and padding while retaining the
+title and optional action's own control geometry. A separate action stays at
+the logical end while the visible glyph defaults to 18px through
+`--kui-list-header-action-icon-size`.
 
 `StateBanner` exposes instance-level `--kui-state-banner-background`,
 `--kui-state-banner-border`, `--kui-state-banner-foreground`,
-`--kui-state-banner-detail`, and action background variables. Its five built-in
+`--kui-state-banner-detail` and action background variables. Its optional
+badge composes `Badge` beside the title and follows the banner tone by default. The
+title, badge, and detail flow as inline text: a wrapping title keeps the badge one item
+gap after its last word, and a detail that does not fit whole beside them moves to its
+own line and truncates at the full copy width (below 576px it always takes its own
+line). The title and detail both use the tone's `--kui-color-{tone}-on-fill`
+foreground (`info` uses `brand`) at full strength, clearing WCAG AA over the tone's fill in light and dark
+mode; the detail reads as secondary through its smaller, regular-weight type, and
+only the neutral tone quiets it, to `--kui-color-neutral-on-quiet`. Its five built-in
 tones can be rethemed globally with
 `--kui-state-banner-{tone}-{background|border|foreground}`. Toolbar control,
-segmented-control, app-tab, and tab-bar colors likewise use their public
+segmented-control, tab-bar-item, and tab-bar colors likewise use their public
 `--kui-*-*` variables. `SegmentedControl` exposes surface, border, foreground,
 hover, and selected-state variables, so rounded, pill, and toolbar presentations
-remain opinionated but locally overridable.
+remain opinionated but locally overridable. Its label color switches with the
+theme without Web Awesome's native button color transition, so a dark filled
+track never briefly pairs with an interpolated low-contrast label.
+
+Inset hover and selection surfaces follow the outer control shape instead of
+choosing an independent radius. `--kui-layout-highlight-inset` is the full
+distance between those edges; the inner radius is the outer radius minus that
+inset. `ToolbarControlGroup` publishes its derived radius to nested toolbar
+`SegmentedControl` choices, keeping both direct buttons and exclusive-choice
+highlights concentric when the group switches between pill and rounded shapes.
 
 `ResizableRegion` owns the Hot Sheet 2 split treatment: a persistent 1px
-separator with a compact grip that appears on hover or keyboard focus. Override
+separator with a compact grip that appears on hover or keyboard focus. The grip
+is drawn centered on the separator line even though the pointer target is wider
+than the line, so the handle never reads as offset into a pane. Override
 `--kui-resizable-region-separator-color`,
 `--kui-resizable-region-handle-color`, or
 `--kui-resizable-region-handle-active-color` on a region when its containing
 surface needs a different contrast level.
 
-`@kerfjs/ui/layout.css` defines one structural model for sidebars, main areas,
-inspectors, and dialogs. `.kui-pane` is unpadded and contains an optional
-toolbar, one scrolling `.kui-pane__content`, and an optional footer.
+`Pane` defines one structural model for sidebars, main areas, inspectors, and
+dialogs. Its `.kui-pane` root is unpadded and contains an optional vertical
+header, one scrolling vertical `.kui-pane__content`, and an optional footer.
+Logical-edge separator lines are independently opt-in and default off.
+`@kerfjs/ui/layout.css` retains the pane roles and supplies the related content
+geometry classes.
+`List` is the corresponding layout-only vertical stack: its children stretch by
+default, while `gap`, `flex`, and `scrollable` opt into typed spacing,
+flex growth, and vertical scroll ownership. `Row.flex` uses the same typed flex
+participation contract on the horizontal counterpart. `dividerSides` accepts canonical
+physical top/right/bottom/left combinations such as `tr` and `trbl`; the stack
+adds no list semantics, margin, or padding of its own. Use a direct finite
+spacing shorthand such as `gap="2xs"`, or pass a `CssLength` created by the
+CSS-free `@kerfjs/ui/css-values` helpers: `space('m')`, `rem(0.25)`,
+`lengthVar('--app-gap')`, or `calc(plus(rem(0.25), pct(10)))`. `plus` returns a
+non-standalone `CssLengthExpression`; only `calc` turns it into a complete
+length. `gap={{ column: 'none', row: 'm' }}` sets the two CSS gap axes
+independently; each axis keeps the same typed spacing contract. `remify(18)` is
+the runtime twin of source CSS's `remify(18px)`: it
+takes a pixel count and returns a `CssLength` in rem (`1.125rem`) against the
+same fixed 16px baseline. Raw CSS strings, and the source-only `remify(4px)`
+string form, are not valid runtime props. The `CssLength` name intentionally includes percentages for UI dimension
+props. Its opaque string brand improves authoring correctness; it is not a CSS
+sanitizer or security boundary.
+`Row.flex` and `List.flex` likewise accept their boolean default, finite keywords, or `CssFlex`
+from `flex(grow, shrink, basis)`. `Skeleton` width/height use `CssSize`, radius
+uses `CssLength`, and `SelectChoice.color` uses `CssForegroundColor` from
+`uiColor()` with a foreground token such as `success-on-quiet`, or from
+`foregroundColorVar()`. Fill tokens such as `success` are pale background tints
+and do not type-check there. Never exchange these property grammars. List rows expose
+`className`, public tokens, and semantic props instead of unrestricted `style`
+declarations.
 `.kui-content` gives major children 24px vertical separation.
-`.kui-content-item` gives one child 8px inline margin, a real 1px border,
-8px padding, and 12px corners; border and background may be transparent without
-changing geometry. `.kui-content-item--pill` selects the 22px radius.
+`ContentItem` (`@kerfjs/ui/content-item`, rendering `.kui-content-item`) gives
+one child 8px inline margin, a real 1px border, 8px padding, and 12px corners;
+the border stays transparent unless `frame="framed"`, so framing never changes
+geometry. `shape="pill"` selects the 22px radius. `appearance="surface"`
+paints the base surface, while `neutral`, `info`, `pop`, `success`, `warning`,
+and `danger` coordinate the same quiet background, border, and readable
+foreground tokens as `StateBanner`. The default `transparent` appearance
+preserves the surrounding surface.
+`flush` removes block padding and borders while preserving inline geometry;
+`title` passes through as the native tooltip. Interactive hover uses the normal
+neutral fill so it remains visible on a lowered surface. For a card with
+multiple actions, put sibling buttons in a static ContentItem (or use
+`ListActionRow` for a simple two-action row).
+For an interactive ContentItem, `wireContentItems` activates the card on Enter
+or Space only when the key event originated from the card itself. A nested
+native control, including one inside a custom element's shadow root, keeps its
+own keyboard activation. The activation click carries the key's Shift, Ctrl,
+and Cmd state (Space uses the state at press), so one delegated click handler
+implements range and toggle selection for pointer and keyboard alike.
+Alt-modified keys are left to the platform.
 
 `ToolbarControlGroup` is the unit of toolbar organization, even for dormant
 text. Each group reserves `calc(2px + remify(42px))`, or 44px, with 8px between
-groups and inside items. `ListHeader` similarly separates its dormant title and
-optional count or badge from its optional 44px action. Use the mutually
-exclusive `count`/`countLabel` pair for non-negative safe-integer section
-quantities; reserve `badge` for non-count `SafeHtml`. Do not concatenate counts
-into the section label. Do not add padding to pane shells,
+groups and inside items. For an ordinary icon/action control inside a group, use
+a plain `<button>` — the group styles `> button` fully, and it keeps the group
+free of a Web Awesome dependency and shadow DOM. Use `ToolbarActionLink` when
+the action must retain native anchor navigation; the group owns its geometry,
+hover, and focus treatment. Set `overflow="scroll"` when a row of controls must
+stay inside the available toolbar width. A disabled native button — `disabled`,
+or `aria-disabled="true"` when it must stay focusable — keeps the group's
+geometry, dims to half opacity, uses the `not-allowed` cursor, and paints
+neither its own nor a lone group's hover surface; a disabled raw `wa-button`
+likewise paints no hover surface.
+Set `visibility="compact-only"` for a
+group that replaces wider toolbar controls below the Toolbar's compact container
+breakpoint; do not hide the group with an application class.
+Use `sizing="grow"` on an expanded search group in a wrapping zone: it grows from
+`growBasis` (19rem by default) into available row space, then takes a whole
+row at 480px container width or less. The basis remains its intrinsic minimum
+in a wider, non-stacked Toolbar, so sibling trailing groups can share the
+row. The collapsed search stays icon-sized. The group owns the open and
+close motion: its flex size animates while a collapsible `SearchField`
+inside fills it on every frame, laid out at least basis-wide and clipped by the
+group, so a query never wraps or leaves an empty band mid-transition. At 480px
+container width or less, and under reduced motion, it opens in one frame.
+A plain collapsible search group (no `sizing`) animates its own width the same
+way: the `SearchField` follows the group on every frame and keeps its
+query on one line until the opening ends, so it never shows an empty band or a
+query wrapped in a narrow, still-opening field.
+Use `sizing="fill"` for a group, including a non-search segmented control,
+that spans its wrapping row. Set `visibility="hide-collapsed-tiny"` on a
+collapsible group to omit its closed icon at 224px or less; expanded content
+remains visible. These sizes use the enclosing Toolbar's container width.
+In a stacked Toolbar, set `placement="end"` on a collapsed group that should
+sit at the trailing edge of its flex row. An expanded search with
+`sizing="fill"` takes a whole row and enters from the row above; reduced-motion
+preferences remove that entrance animation.
+Use `visibility="yield-to-expanded-sibling"` on trailing groups that should
+leave a 480px-or-narrower toolbar while a sibling trailing group is expanded.
+They return when it collapses or the toolbar widens; leading and center zones
+remain visible. In a `responsive="trailing-priority"` Toolbar, use
+`visibility="yield-to-priority-row"` instead: the group leaves exactly while
+the expanded trailing control has its own row, from the same container query
+as the row at the Toolbar's `responsiveAt` (832px for `narrow`, 704px for
+`compact`, both inclusive). Do not restate that width with `hideBelow`, which
+hides strictly below its threshold: at exactly 704px the row is active while
+`hideBelow={rem(44)}` still shows the group, which then wraps onto a third
+row.
+A group's controls are plain `<button>`s (a standalone `Button` belongs outside a group); a popup menu is a `PopupMenu`, which renders its own
+trigger. By default a group stays on one row: each icon sits beside its label,
+and the enclosing `Toolbar`'s responsive policy relocates whole groups. Set
+`overflow="wrap"` only for independent links that should move as whole actions
+to another row within the group; use `overflow="scroll"` for a bounded one-row
+action strip. A wrapping group centers in the toolbar band on one row and
+starts at its top when it grows to multiple rows. For a compact mixed-content
+group, set `nestedDropdown`; a
+text-and-caret trigger grows to its intrinsic width while an icon-only trigger
+can remain square. A compact icon `<button>` is a 32px circle, so a selected
+compact segment never becomes an oval. An icon-only `Select` joins a group as
+one more segment with its siblings' inset, radius, hover, and focus ring; only a
+lone Select grows the group to its icon-and-caret pill.
+
+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.
+
+For a rail view heading, use `Select presentation="title"`: its intrinsic
+36px borderless trigger has a bold large label flush with its leading edge and
+a caret beside that label. Set `focusRingInset` when a NavStack or panel clips
+outside painting; the Select keeps its focus outline 3px inside the trigger
+and drops it while the listbox is open. Both settings belong to Select, not an
+application `::part()` override. `Button` and `SplitButton` take the same
+`focusRingInset` for a clipping ancestor: the ring moves inside the box (each
+half's, for a SplitButton) with a line inside it in the color of the surface
+it sits on (the surface context), so it stays visible on a loud fill of its
+own hue without a halo on a sunken or tinted surface. Never re-offset their outline from
+application CSS.
+
+Set `menuInset` to configure the menu surface
+without application `::part(menu)` CSS; the default `standard` keeps each menu's
+own inset (8px for a raw `wa-dropdown`, the Select listbox's 4px for a
+`PopupMenu`), while `compact` and `list-zero` apply to every nested menu. A
+`PopupMenu` and a `Select` draw one popup: the same caret that turns to face the
+open popup, fade-in surface, surface inset, row height and padding, current-row
+fill, group titles, and scroll cue, all read from one private popup-choice
+contract in `foundation.css`. A capped popup that scrolls (a long listbox, a
+menu, or a phone submenu) shows a soft shadow along each edge with more
+choices beyond it, so overlay scrollbars never leave it looking complete; the
+cue is CSS-only, appears only toward hidden rows, and a popup whose choices
+all fit draws none. Checkbox items reserve a check column, and so does every
+plain command in a level (the top menu or one submenu) that holds a checkbox
+item, through an `aria-hidden` icon-slot spacer, so check, icon, and label
+columns align across the level. A level without a checkbox item keeps the
+compact start: plain commands begin at the checkmark's leading edge, beside the
+group title rather than the farther-in Select option label. Checked submenu
+items keep their checkmark inside the submenu surface with the same check-column
+advance as the top level. Compact mixed controls retain the standard
+item padding, omit an internal separator, and let the raised selected item paint
+over the outer border instead of shrinking to an inset highlight. The
+PopupMenu trigger sizes to max-content, so icons, localized text, and the caret
+determine the width without a fixed measurement.
+At viewport widths of 480px or less, `PopupMenu` places an open submenu above
+or below its parent menu, choosing the side with room and constraining the
+submenu to the viewport. It never paints over the parent list. The reverse
+horizontal arrow (ArrowLeft in LTR, ArrowRight in RTL) returns focus to its
+parent item, Escape closes it, and choosing a child dispatches the normal
+`data-action` and `kui-menu-select` events. Wider viewports retain the side cascade.
+The enclosing `Toolbar` owns zone alignment and responsive topology: use
+`centerAlign="stretch"` when the center group should consume its track, and
+choose `responsive="stack"` with `responsiveAt="compact" | "narrow"`,
+`responsive="wrap"` for a heading whose title must stay whole, or
+`responsive="center-priority"` instead of selecting its zone classes from a
+parent stylesheet. No policy clips an action: the trailing zone wraps whole
+groups and its standalone primary `Button` onto another row; a stacked
+center zone wraps its groups. The center zone never
+compresses below its content width, so when the leading identity, center, and
+trailing zones share a row that is too narrow, the leading title is what gives
+way: it truncates with an ellipsis (as a platform toolbar's title does) instead
+of the center group painting over it. When everything fits, the center group
+keeps its place, centered in the track between the leading and trailing zones.
+`ListHeader` similarly separates its dormant title and optional indicators
+from its optional 44px action. Use the `count`/`countLabel` pair for a sole
+non-negative safe-integer section quantity; it excludes `badge` and `status`.
+`badge` and `status` may appear together, and either may be explicitly
+`undefined` as app state changes. Give a contextual quantity in a badge a full
+spoken phrase, such as "3 lines unpriced". Do not concatenate counts into the
+section label. Set `width="content"` to shrink-wrap while retaining
+normal header geometry; `inline` is the separate zero-outer-geometry mode. Do
+not add padding to pane shells,
 double child-owned geometry with wrapper insets, or create competing scroll
 owners. The [layout contract](./layout.md) lists the public roles and tokens.
 
-`PanelHeader` is a plain top `Toolbar` used as a panel, dialog, or page heading;
-it overrides no Toolbar styles. The leading zone holds an optional icon (a normal
-bordered `ToolbarControlGroup` given a brand fill with a matching border) and the
-title as extra-large `ToolbarText`, and the app's `actions` go straight into the
-trailing zone (typically as a `ToolbarControlGroup`). The icon group is omitted
-when no icon is passed. The optional summary is a separate row aligned below the
-title, so it cannot pull the icon group out of vertical alignment with the
-title and action row.
+Panel, dialog, and page headings are direct `Toolbar` compositions. The leading
+zone holds an optional icon `ToolbarControlGroup` and a direct extra-large
+`ToolbarText`; app actions belong in a trailing `ToolbarControlGroup`. Omit the
+icon group when it has no content. A short supporting line is the title's
+`ToolbarText` `description`: it renders quiet, single-line, truncating copy
+under the title, starting at the title's text with or without an icon group,
+and the title and description share the control band so the icon and actions
+stay aligned. Longer supporting copy is app-owned content below the toolbar.
+For an editable title, `ToolbarText action="edit-title"` renders a native button
+directly in the leading zone. It keeps content width when there is room, shrinks
+and ellipsizes beside a status chip when space is tight, and emits the delegated
+action on click or keyboard activation. The application owns the editing control
+and the swap between display and edit states. An actionable title is a button,
+so place any required heading landmark on another element in the view.
 
 `ValueTable` composes typed `ValueTableRow` entries. A row owns its `dt`/`dd`
 semantics and may receive a leading `SafeHtml` icon. Every row keeps 8px of
@@ -139,6 +755,23 @@ padding + 24px icon + 8px gap) and 8px from the right edge for an icon-bearing
 row. Applications own the values, formatting, and whether an icon is decorative
 or meaningfully labeled.
 
+A row follows the settings-style key/value priority: the value keeps its
+content and the label gives way. The label and value are two content-sized
+columns that share the row's free space equally, each stopping once its content
+fits. A short value therefore stays whole on one line beside any label, and a
+long label takes the remaining width, wrapping at its spaces and ending a word
+wider than its column (a long component or file name) in an ellipsis before the
+value rather than running under it. A short label keeps its width beside a
+long value, which wraps; when both are long they split the row, so neither is
+starved.
+
+`ValueTable` defaults to the shared lowered surface and uses the normal text
+color for normal-weight labels, including when nested in a
+sunken `Pane`. Set `--kui-value-table-background` on an application-owned
+ancestor to change that surface for its tables; the table reads the inherited
+token and falls back to the lowered surface when it is absent. The application
+is responsible for checking text contrast when it supplies a custom background.
+
 ## Imports and side effects
 
 Every component has an explicit JS and CSS subpath. In CSS-aware browser builds,
@@ -153,23 +786,53 @@ overrides load later in the cascade or set scoped `--kui-*` variables. JavaScrip
 modules are pure except the browser style wrappers and `@kerfjs/ui/select/register`,
 which registers exactly the Web Awesome elements used by `Select`. Eventful
 helpers such as `wireResizableRegions` and `wireTabBars` attach listeners only
-when called and return disposers. `wireTokenSearchFields` goes one step further:
+when called and return disposers. `wireSearchFields` goes one step further:
 by default it also owns the collapsible field's transient expand/collapse/focus
 (activate to reveal and focus, Escape or empty blur to collapse), holding that
 state in a signal it exposes on the returned handle. An app reads that signal in
 render, hands in its own via `collapsible.signals`, drives it through
 `handle.open`/`handle.close`, or disables any individual behavior — so transient
-UI is consistent by default without every app reinventing it.
+UI is consistent by default without every app reinventing it. A collapsed
+field may reveal its editor after the current microtask; the helper keeps a
+bounded render-frame focus handoff for that reveal and cancels it on disposal.
+When a pointer press moves focus out of an empty field, the collapse waits until
+the pressed control has received its click and every app handler has run, then
+renders in a microtask in that same click task, so the click's render and the
+collapse share one style recalculation and layout. A click that stops
+propagating before the window, or a press without a click, collapses in the
+next task instead.
+`SearchField.trailingAction` supplies an icon, accessible `label`, delegated
+`action`, and optional `id`; the field renders a 24px wide button that fills its
+34px line slot (32px in `toolbar-group`), including the hit target, disabled
+state, hover, focus ring, and the clear button's radius in each presentation.
+`expanded` renders `aria-expanded` and `pressed` renders `aria-pressed` (one or
+the other, never both); either `true` state keeps the hover fill at full text
+strength. `controls` and `haspopup` render `aria-controls` and `aria-haspopup`,
+and `attributes` carries domain `data-*` metadata but never `data-action`.
+Use `trailing` for passive content. The two props are mutually exclusive.
+For a collapsible search in a stretched Toolbar center, `fill` lets the expanded
+field and its enclosing search `ToolbarControlGroup` consume the available width;
+the collapsed action retains its fixed icon width.
+Grammar suggestion rows align their labels to one leading edge inside the
+anchored popover, including when the labels have different lengths.
+
+A public subpath that exposes several visual components is a folder-backed
+surface. Put each component in its own source file and give each visual
+component exactly one owned stylesheet alongside it. Keep the public
+compatibility entrypoints implementation-free: the JavaScript/TypeScript
+entrypoint only re-exports the folder modules, and the CSS entrypoint only
+imports their owner stylesheets. A shared public name is not permission to put
+several component implementations or visual contracts back into one file.
 
-`wireTokenSearchFields` is a deliberate exception, not the rule for `wire…`
-helpers. Its collapse behavior was *rich and error-prone* — reveal, focus
+`wireSearchFields` is a deliberate exception, not the rule for `wire…`
+helpers. Its collapse behavior was _rich and error-prone_ — reveal, focus
 transfer, Escape, empty-blur collapse, focus return — the kind of transient chrome
 apps kept reimplementing inconsistently, so the helper owns it. Everywhere else the
 app's state is **domain or persisted, not transient chrome, and stays app-owned**: a
-`NavStack`'s view stack is navigation history, a `TabBar`/`TabScaffold`'s selection
+`NavStack`'s view stack is navigation history, a `TabBar`/`TabNavigator`'s selection
 and tab order are data, a `ResizableRegion`'s committed size and a
 `Workbench`/`SplitView` rail's `collapsed` flag are persisted layout preferences.
-Each helper already owns only the *ephemeral mechanics* around that state —
+Each helper already owns only the _ephemeral mechanics_ around that state —
 `wireNavStack` the push/pop animation, `wireTabBars` the overflow autoscroll and
 drag preview, `wireResizableRegions` the live drag preview — and reports committed
 changes through callbacks. A `ListHeader` `toggle` disclosure's `expanded` is
@@ -178,6 +841,35 @@ render the section body, so a managed helper would remove no real complexity. Re
 for a managed default only when the transient behavior is substantial enough that
 hand-rolling it produces genuine, inconsistent variation.
 
+TabBar itself owns the inline geometry around those mechanics. Its tab list is
+the only shrinking, horizontally scrolling region; `leading`, `trailing`, and
+`end` action regions remain fixed. Set `trailingPlacement="adjacent"` when the
+trailing action belongs immediately after the final tab and use `end` for a
+separate action pinned to the far edge. Applications own the action content,
+but must not restyle TabBar descendants to recreate that allocation.
+When a leading TabBarItem is pinned, the leading scroll divider appears at that
+tab's trailing edge while peer tabs scroll beneath it, including in RTL.
+With `snapTabs`, `wireTabBars` measures the pinned tab and settles peers at
+whole-tab starts after scroll and selection changes, reserving end room so the
+last peer can align there. That room is scrollable content after the last tab,
+inside the strip, so it lengthens the scroll range without widening the strip:
+the strip still shrinks to its allocation, and `trailing` and `end` stay inside
+the bar. The room is still in-flow content, so it counts toward the strip's
+content-based flex basis: when another zone also shrinks (a trailing zone
+given `--kui-tab-bar-trailing-flex: 0 1 auto` with shrinkable content), the
+strip keeps a proportionally larger share. The share converges within a few
+frames and never pushes `trailing` or `end` out of the bar; keep the trailing
+zone non-shrinking with `snapTabs` to avoid it. The application still owns
+selection and tab order.
+ResizeObserver notifications coalesce snap measurements into the next animation
+frame, so inset writes cannot resize the observed strip during observer delivery.
+`wireTabBars` watches the whole root it is given, but a mutation re-measures only
+the bars it touched: a change inside a bar, a newly inserted bar, or a `dir`
+change on an element above one. Content elsewhere in the root (terminal output,
+list updates, streamed text) triggers no style or layout reads. A pinned strip
+re-measures when its own size changes, so a layout change outside the bar still
+reaches it.
+
 CSS, the generated wrappers that make it
 reachable, and the registration module are the package's only declared side
 effects.
@@ -186,14 +878,78 @@ A value-bearing component's `placeholder` prop is a first-class loading mode: th
 component renders its own real chrome (labels, icon and action affordances,
 container geometry) while replacing each **value** slot with a subtle, deliberately
 unanimated `Skeleton` block and disabling its own interactive controls
-(`aria-busy`, dropped `data-action`, disabled buttons). Sizes and shapes stay
+(`aria-busy`, dropped `data-action`, disabled buttons). Only unknown values become
+skeletons; nothing else may change. Sizes, shapes, typography, color, and opacity stay
 identical to the populated component, so a parent composes a faithful loading view —
 an inspector, a detail pane — from placeholder children without hand-rebuilding
 markup. The application still owns the loading lifecycle (when to pass `placeholder`)
-and which slots are unknown; the standalone `Skeleton` covers custom slots. It is a
+and which slots are unknown; the standalone `Skeleton` covers custom slots. A
+`Skeleton` is `inline-block` so it sits in a text line; pass `block` to lay it out
+as `display: block` where it stands in for a box, such as an icon, so it takes no
+line of its own and centers in its slot. It is a
 placeholder, not progress: use `LoadingSpinner` for known busy activity, and never
 animate the skeleton.
 
+`LucideIcon` defaults to `appearance="outline"`. Pass
+`appearance="solid"` for a filled state glyph such as a selected star or
+triangle. The SVG uses `fill="currentColor"`, so fill follows the icon's text
+color without styling its internal SVG from the application. Choose a Lucide
+node whose geometry supports a solid fill; the prop does not replace an icon
+node's own fill attributes.
+The SVG is block-level by default. Pass `inline` when it belongs inside a
+sentence or `Text`: the SVG becomes `inline-block`, keeps its inherited 1em
+size unless `size` is supplied, and stays decorative unless `label` is set.
+`LucideIcon` serializes an icon node's child markup once per node identity and
+reuses it on every later render (Lucide nodes are module constants), so a list
+that repeats a glyph per row does not re-escape its path data each render.
+Treat a node as immutable once rendered; build a new node for new geometry.
+
+`LoadingSpinner` accepts the same `size` steps as `LucideIcon`: `xs`, `s`, `m`,
+`l`, `xl` (12/16/20/24/32px at a 16px root) or a positive finite pixel
+number converted to rem. Omit `size` to keep its inherited 1em box. A supplied
+size is exposed as `data-size`; callers configure the spinner through this prop
+instead of sizing its SVG from outside.
+
+A placeholder is loading, not unavailable, so it keeps the `disabled` attribute (its
+controls stay inert and out of the keyboard order) but never shows disabled chrome.
+`skeleton.css`, which every component that renders a skeleton loads, neutralizes generic
+disabled styling under `[data-placeholder="true"]` — including Web Awesome's native
+`button:disabled { opacity: 0.5; cursor: not-allowed }` when `webawesome.css` is
+loaded — to full opacity and the non-interactive `default` cursor. That opacity reset
+carries zero specificity, so a component's own opacity (a control hidden until
+interaction) still wins, and each component excludes placeholders from its own
+disabled tone and hover feedback — including hover reveals: a `ListActionRow` with
+`trailingActionVisibility="interaction"` keeps its trailing action hidden when its
+placeholder is hovered, as the resting live row does. The cursor is the one intentional difference from the
+live state: a placeholder is not clickable, so it never advertises a pointer.
+
+A control the author disabled is different: it will be unavailable once loaded, so its
+placeholder keeps the live disabled tone. Each such control carries the component-owned
+`data-kui-disabled="true"` marker whenever its own disabled prop is set, independent of
+`placeholder` — `ListItem` and `ListActionRow` `disabled`, `trailingActionDisabled`,
+a `SegmentedControl` choice's `disabled`, and `ListHeader` `actionDisabled` (on the
+action or disclosure toggle). The placeholder reset skips the marker and components key
+their disabled tone on it, so only the `placeholder`-only `disabled` attribute is
+neutralized. That tone is each component's own, never Web Awesome's native
+`button:disabled`, so an author-disabled control is dimmed with or without
+`webawesome.css`. The marker is reserved: the extension-attribute channels
+(`rootAttributes`, `trailingActionAttributes`, `triggerAttributes`) cannot set it. A
+disabled placeholder still shows the `default` cursor, never `not-allowed`.
+Chrome a component draws itself from a known prop stays live, even inside a slot that
+also holds values. `ListItem`'s trailing slot has three inputs: the `busy` spinner is
+component-owned chrome and stays live, while `status` text and author-supplied
+`trailing` content are values and each become a skeleton (the component cannot tell an
+author's chevron from a count, so all `trailing` content is treated as a value).
+`ListActionRow`'s status line follows the same split: its `busy` spinner stays live and
+only the `status` text becomes a skeleton.
+`SegmentedControl` is the one placeholder without a skeleton: its choices are known
+chrome and only the selection is unknown, so it renders every choice's live label or
+icon at its live geometry, selects none, and neutralizes its own disabled chrome.
+`tests/browser/placeholder-fixture.spec.ts` enforces the rule: it renders every
+placeholder component live and as a placeholder from identical props and diffs each
+element's geometry and computed chrome, excluding only the value slots, and checks that
+every author-disabled control is dimmed in both renders.
+
 Package source styles express root-scaled geometry with `remify(<px>)`; the
 build converts it against the 16px authoring baseline and exposes only ordinary
 `rem` CSS. Literal pixels remain for intentional hairlines, and `em` remains
@@ -209,7 +965,25 @@ Kerf JSX declaration boundary for every catalog-supported `wa-*` tag.
 Consumers register only the individual Web Awesome modules they render and can
 override `--wa-*` values after the theme import. The shared `--wa-*` values feed
 both Web Awesome controls and Kerf's `--kui-*` foundation aliases, preventing a
-second application palette.
+second application palette. Without the theme, every foundation color token,
+every elevation token (`--kui-shadow-*`), and the focus-ring color fall back to
+the same value the theme assigns, including its `light-dark()` pair, so
+surfaces (including the dark `surface-raised`), links (`text-link` is the brand
+on-quiet text color, not the brand fill), tone text, fills, and raised-surface
+shadows keep their light and dark appearance and contrast either way. The
+theme's elevation shadows are scheme-aware: light keeps the soft Hot Sheet 2
+alphas, and dark raises them (`--wa-shadow-s` 14% to 50% black, `-m` 11% to
+40%, `-l` 9% to 32%) so a raised surface still separates from a near-black
+page.
+Kerf owns the light `brand`, `success`, and `warning` `on-quiet` values in that
+theme layer: each keeps its hue but is dark enough to clear WCAG AA (4.5:1) on
+the lowered page background (`--kui-color-surface-lowered`, approximately `#f2f2f7` over white), not
+only on the white surface, so toned text reads on every background a page
+paints. It likewise owns every tone's loud pair: each `on-loud` text color
+clears AA on its `fill-loud` in both schemes. Light brand and danger keep white
+text on a slightly deeper fill of the same hue (`#0075db`, `#eb0005`); success
+keeps its bright green with dark text, as warning does; the dark-mode brand and
+danger fills keep their color with dark text.
 
 `Select` owns its custom-element reconciliation seam. It gives each slotted
 option icon a stable key and leaves the upgraded Web Awesome-owned slot subtree
@@ -228,4 +1002,38 @@ Keep product adapters outside the package: connection-state maps, ticket empty-s
 
 ## Testing contract
 
-Each behavior has focused unit coverage and a real-browser flow through the production-backed catalog. Consumer bundle tests enforce subpath CSS reachability, transitive component styles, root/SSR isolation, optional registration boundaries, and the CSS-only Web Awesome theme boundary. Visual evidence supplements—never replaces—keyboard, focus, state, and event assertions.
+Each behavior has focused unit coverage and a real-browser flow through the production-backed catalog. Consumer bundle tests enforce subpath CSS reachability, transitive component styles, root/SSR isolation, optional registration boundaries, and the CSS-only Web Awesome theme boundary. `npm run check:css-ownership` rejects application selectors into Kerf or Web Awesome components, a non-minimal catalog compatibility stylesheet, or a return of the shared recipe stylesheet. Visual evidence supplements—never replaces—keyboard, focus, state, and event assertions.
+
+### Toolbar width visibility
+
+`ToolbarText` and `ToolbarControlGroup` accept typed `hideBelow` and
+`showBelow` CSS lengths. Call `wireToolbarVisibility(root)` from
+`@kerfjs/ui/wire-toolbar-visibility` after mounting, and call its disposer when
+the application unmounts. The nearest Toolbar's **content-box width**, excluding
+padding, borders, and safe-area insets, determines visibility. `hideBelow={px(416)}`
+hides strictly below 416px; `showBelow={px(416)}` shows strictly below 416px. At
+416px the first is visible and the second hidden. Together they define the visible
+interval `[hideBelow, showBelow)`. Width rules intersect existing visibility and
+expanded-state rules; they never force a CSS-hidden group visible.
+
+Use `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, or `calc`/`plus` to construct
+lengths. Percentages resolve against that content box, `em` uses the child item's
+font size, and custom properties use its inherited and own token context. The
+helper follows resizes, theme/token/font changes, inserted items, nested toolbars,
+and relocated groups. Invalid, unresolved, negative, or contradictory thresholds
+leave the item visible under this width policy. Server-rendered content is visible
+until wiring runs; without browser observers, initial wiring and window resize
+still update it. Probe context and lengths are reconciled only when their CSSOM
+values change, so unrelated DOM observers can redraw without feeding an ongoing
+mutation loop. Probes are helper-owned imperative nodes preserved across Kerf
+rerenders, preventing repeated probe creation and resize/DOM observer churn.
+Invisible preserved state children keep actual CSS visibility stable while a render
+removes transient parent markers, so post-render geometry measurements cannot
+feed a show/hide render loop. These children never enter layout, focus or the
+accessible tree. Toolbar replacement or deliberate internal-node removal is
+still repaired. Dispose to
+remove measurement probes and restore prior markers.
+
+Hidden controls leave layout and keyboard navigation. A hidden busy group also
+hides only its own adjacent busy status. Keep primary actions always available;
+show a complementary overflow group for secondary actions at narrow widths.