@kerfjs/ui 5.0.0-beta.6 → 5.0.0-beta.61

package/docs/component-contract.md

@@ -18,25 +18,250 @@ 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`.
+
+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.
+
+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, 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.
+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
 
+### 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.
+
 - Components own semantic markup, stable anatomy, documented variants, ARIA projection, and package CSS hooks.
 - 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.
 
-`MenuItem.rootAttributes`, `MenuActionRow.rootAttributes`,
-`MenuHeader.rootAttributes`, and `AppTab.rootAttributes` accept
+`ListItem.rootAttributes`, `ListActionRow.rootAttributes`,
+`ListHeader.rootAttributes`, `AppTab.rootAttributes`,
+`CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` accept
 application-owned `data-*` metadata without
-adding product fields to the shared API. A `MenuActionRow` trailing action uses
-`trailingActionAttributes`, and a `MenuHeader` action/disclosure uses
+adding product fields to the shared API. A `ListActionRow` trailing action uses
+`trailingActionAttributes`, and a `ListHeader` action/disclosure uses
 `triggerAttributes`, for `data-*`, native popover target/action attributes, and
 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.
 
@@ -46,10 +271,10 @@ component continues to own the named close button or focusable separator, and
 `wireTabBars()` / `wireResizableRegions()` continue to own transient behavior
 and disposal.
 
-`MenuItem.trailing`, `MenuActionRow.label`, `MenuActionRow.icon`, and
-`MenuActionRow.trailingActionIcon` are dormant SafeHtml slots. They must not
+`ListItem.trailing`, `ListActionRow.label`, `ListActionRow.icon`, and
+`ListActionRow.trailingActionIcon` are dormant SafeHtml slots. They must not
 contain controls. When a row needs an independently interactive trailing
-region, `MenuActionRow` owns the noninteractive root and the two sibling native
+region, `ListActionRow` owns the noninteractive root and the two sibling native
 buttons; the application owns their delegated behavior and controlled state.
 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
@@ -58,37 +283,143 @@ visual anchor.
 ### 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-menu-item [data-state]`, and `.kui-menu-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`. 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 `src/*.css` with a same-basename
+component), deriving the component names, the Web Awesome tags each component
+renders, and its composed children from `src/*.tsx`:
+
+- **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`); `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-l022)).
+
+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.
 
-In `MenuHeader` toggle mode, omitting `actionIcon` composes the production
+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-menu-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
@@ -96,39 +427,117 @@ segmented-control, app-tab, and tab-bar colors likewise use their public
 hover, and selected-state variables, so rounded, pill, and toolbar presentations
 remain opinionated but locally overridable.
 
+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. `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.
 
 `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. `MenuHeader` similarly separates its dormant title and
+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. 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. Reach for
+`wa-button` only when you need
+a Web Awesome feature; a popup menu is a `PopupMenu`, which renders its own
+trigger. Nothing wraps inside a group: an icon sits beside its label on one
+row, and a group's controls never break onto a second line — the group sizes
+to its content and the enclosing `Toolbar`'s responsive policy relocates whole
+groups. 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. 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, reserved
+check column, current-row fill, and group titles, all read from one private
+popup-choice contract in `foundation.css`. 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.
+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, and a stacked
+center zone, wrap whole groups onto another row. 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 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,
+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.
 
 `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 +548,16 @@ 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.
+
 ## Imports and side effects
 
 Every component has an explicit JS and CSS subpath. In CSS-aware browser builds,
@@ -161,27 +580,98 @@ 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.
 
+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
 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 `MenuHeader` `toggle` disclosure's `expanded` is
+changes through callbacks. A `ListHeader` `toggle` disclosure's `expanded` is
 likewise app-owned: it is a one-line boolean the app already tracks and must read to
 render the section body, so a managed helper would remove no real complexity. Reach
 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.
+
 CSS, the generated wrappers that make it
 reachable, and the registration module are the package's only declared side
 effects.
 
+A value-bearing component's `placeholder` prop is a first-class loading mode: the
+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). 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. 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.
+
+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
@@ -197,7 +687,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`, `#f2f2f7`), 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
@@ -216,4 +724,4 @@ 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.