@kerfjs/ui 5.0.0-beta.9 → 5.0.0-beta.90

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,268 @@ 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.
+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 use the
+bounded `items[].property` form. 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`.
+
+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`, except the
+encouraged `wa-popup` primitive — 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`). `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.
+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`, `AppTab.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,7 +298,7 @@ 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.
 
@@ -55,25 +317,127 @@ 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.
+
 ### 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 `AppTab` rounds its
+outer corners in a segmented `TabBar` and shares a fill-allocated strip from
+`app-tab.css`. An inspector `TabBar` uses the shared 12px rounded rectangle
+radius on its strip; its segmented `AppTab` 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 (`wa-dropdown`,
+  `wa-select`, `wa-option`, a `PopupMenu`'s trigger `wa-button`) — 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.
+
+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 +446,214 @@ 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
 `--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.
 
 `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 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.
+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.
+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.
+Reach for `wa-button` only when you need a Web Awesome feature; 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. 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.
+
+Set `menuInset` to configure the dropdown 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, and group titles, all read from one private popup-choice contract in
+`foundation.css`. Checkbox items reserve a check column; plain commands start
+at the checkmark's leading edge, beside the group title rather than the
+farther-in Select option label. Checked submenu items keep their checkmark and
+label inside the submenu surface. 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 Web
+Awesome trigger's shadow base owns max-content sizing, so icons, localized text,
+and the shadow caret determine the width without a fixed host measurement.
+With `popup-menu/register` loaded, PopupMenu and a raw dropdown inside
+`PopupSurface` preserve item navigation made during the Web Awesome show
+animation across its final initial-focus handoff.
+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 submenu
+remains a native Web Awesome `menu`: the reverse horizontal arrow (ArrowLeft in
+LTR, ArrowRight in RTL) returns focus to its parent item, Escape dismisses the
+menu, and choosing a child dispatches the normal
+`data-action` and `wa-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 `wa-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. Supporting copy is app-owned content below
+the toolbar so it cannot pull the icon or actions out of alignment.
+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 +664,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,
@@ -159,17 +701,36 @@ by default it also owns the collapsible field's transient expand/collapse/focus
 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.
+`TokenSearchField.trailingAction` supplies an icon, accessible `label`, delegated
+`action`, and optional `id`; the field renders a 24px wide button that fills its
+34px line slot, including the hit target, disabled state, hover, and focus ring.
+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
+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 +739,20 @@ 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 AppTab 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. 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.
+
 CSS, the generated wrappers that make it
 reachable, and the registration module are the package's only declared side
 effects.
@@ -186,14 +761,74 @@ 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.
+
+`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 +844,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 +881,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.