@kerfjs/ui 5.0.0-beta.55 → 5.0.0-beta.57

package/docs/nav-stack.md

@@ -5,14 +5,19 @@ and out over one another while the top chrome settles. A **single-pane layout is
 a `NavStack` with one entry**. It is one of the opt-in app layouts (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 
-Import the component and its companion stylesheet:
+Import the component and its wiring helper:
 
 ```ts
 import { NavStack, type NavStackView } from "@kerfjs/ui/nav-stack";
 import { wireNavStack } from "@kerfjs/ui/wire-nav-stack";
-import "@kerfjs/ui/nav-stack.css";
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads NavStack's stylesheet and those of the components it renders internally
+(`Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `LucideIcon`). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/nav-stack.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
 ## State lives in the app
 
 Like every `@kerfjs/ui` component, `NavStack` is declarative: the app owns the
@@ -49,11 +54,55 @@ views.value = [
 `NavStack` renders every entry stacked, the last one active and the rest kept
 mounted (so their DOM state survives) but hidden. Each entry carries a
 `key` (stable identity), `content`, an optional `title`, optional per-view
-`toolbar` actions, and an optional per-view `bottomToolbar`. The component-level
+`leading`, `center`, and trailing `toolbar` groups for the top toolbar, and an
+optional per-view `bottomToolbar`. The component-level
 `bottomToolbar` remains a persistent fallback for views that do not provide one.
 The back control appears automatically once the stack has more than one entry;
 `wireNavStack`'s `onBack` is where the app pops its own signal.
 
+## The top toolbar
+
+The top chrome is a real `Toolbar`, so it follows the same zone,
+group, and responsive rules as every other toolbar. Its leading zone holds the
+back control (a borderless `ToolbarControlGroup`, shown once the stack has
+depth), then the active view's `leading` groups, then the view's `title` as a
+`ToolbarText`. The view's `center` fills the center zone and its `toolbar`
+fills the trailing zone. Give each zone `ToolbarControlGroup`s or `ToolbarText`,
+as in any toolbar.
+
+Configure the toolbar with `toolbarConfig` instead of styling it:
+
+```tsx
+<NavStack
+  id="mail"
+  label="Mail"
+  views={views.value}
+  backText={previousTitle}
+  toolbarConfig={{
+    headingLevel: 1,
+    titleSize: "xlarge",
+    dividerSides: "b",
+    responsive: "wrap",
+  }}
+/>
+```
+
+- `toolbarConfig` forwards the `Toolbar` configuration (`dividerSides`,
+  `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) and adds
+  `label` (the toolbar's accessible name), `titleSize` (the title's
+  `ToolbarText` size, default `large`), and `headingLevel` (expose the title as
+  a heading; default a plain span). The defaults keep the stack's own chrome:
+  no divider, the standard Toolbar height (a 44px control band with 8px above and below), and the top and side safe-area edges
+  claimed.
+- `backIcon` replaces the default chevron-left icon. `backText` adds visible
+  text beside it (for example, the previous view's title); visible text names
+  the control, so `backLabel` applies only to the icon-only control.
+
+The catalog's **Configured toolbar** example shows these together: a level-2
+heading title over a bottom divider, leading and center groups on the root
+view, a trailing group on the pushed view, and `backText` set to the previous
+view's title.
+
 Focus follows the controlled stack automatically. On push, `wireNavStack`
 remembers the focused descendant of the departing view and moves focus into the
 new top view. On pop it restores that exact descendant when it still exists. A
@@ -65,6 +114,31 @@ When a remembered control was removed during the controlled rerender, the same
 fallback order applies. Disposing the helper stops future transitions and
 cleans up any temporary fallback `tabindex` it added.
 
+## Scroll dividers
+
+The stack draws no permanent line between its chrome and the view. With
+`wireScrollDividers(appRoot)` installed (see
+[Layout › Scroll dividers](layout.md#scroll-dividers)), the top chrome shows a
+line along its bottom edge only while the active view's content is scrolled
+beneath it, and the bottom toolbar a line along its top edge only while more
+content lies below it — neither when the content fits. The line follows the
+active view across a push or pop. The chrome's line is overlaid on its bottom
+edge and the bottom toolbar's is its always-present 1px top border, colored
+only while shown, so neither ever moves the chrome or the content. When the view's only child is a `Pane`,
+the line keys on whichever actually scrolls — the view, or the Pane's content —
+and a Pane header or footer draws its own boundary instead. An explicit
+`toolbarConfig.dividerSides` still draws a permanent Toolbar edge.
+
+`chromeDividers` configures both lines, with the same values as a `Pane`'s:
+`scroll` (the default) follows the scroll state above and draws nothing until
+the wiring runs; `always` keeps both lines, with or without the wiring; `none`
+drops them even when the wiring reports scroll state. It does not change the
+top Toolbar's own `dividerSides`.
+
+```tsx
+<NavStack id="settings" label="Settings" views={views.value} chromeDividers="always" />
+```
+
 ## Safe areas
 
 The stack paints through a device's unsafe areas. Its chrome pads for the top

package/docs/recipes.md

@@ -57,8 +57,8 @@ component variables.
 [Open the recipe](../ux-demo/?component=recipe-navigation-sidebar) · [TSX source](../ux-demo/recipes/navigation-sidebar.tsx)
 
 One unpadded `.kui-pane` owns toolbar/content/footer structure. Its
-`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and other
-`.kui-content-item` children own their 8px margin, 1px border, and 8px padding.
+`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and
+`ContentItem` children own their 8px margin, 1px border, and 8px padding.
 Rows and footer toolbar groups remain 44px tall. The app owns routes,
 permissions, labels, selection, valid section counts and their localized
 `countLabel` phrases, non-count badge content, disclosure state, and revealed
@@ -205,7 +205,8 @@ Chromium, Firefox, and WebKit by `tests/browser/collapsible-sidebar-recipe.spec.
   `@kerfjs/ui/webawesome.css`.
 - Compose, don't style. A recipe ships no stylesheet, sets no inline style, and
   names no class outside the published layout vocabulary (`.kui-content`,
-  `.kui-content-item`, …) and themed Web Awesome classes; it configures
+  `.kui-control-cluster`, …) and themed Web Awesome classes — a content item is
+  a `ContentItem`, not a hand-written `.kui-content-item`; it configures
   components through props, `rootAttributes`, and tokens. When a recipe needs a
   capability no component offers, record it as a component gap rather than
   papering over it with CSS. `npm run check:recipes` enforces these rules on

package/docs/split-view.md

@@ -8,11 +8,16 @@ on compact ones. One of the opt-in app layouts (see
 ```ts
 import { SplitView } from "@kerfjs/ui/split-view";
 import { deviceClass } from "@kerfjs/ui/device-class";
-import "@kerfjs/ui/split-view.css";
-// plus nav-stack.css when the compact path is reachable, and
-// wireResizableRegions / wireNavStack for the interactive behavior.
+// plus wireResizableRegions / wireNavStack for the interactive behavior.
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads SplitView's stylesheet and those of the components it renders internally
+(its compact `NavStack`, `ResizableRegion`, and the toolbar
+components). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/split-view.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
 ## Safe areas
 
 The list pane grows by the inline-start unsafe inset and pads for the edges it
@@ -53,11 +58,55 @@ const selected = signal<string | null>(null);
   app's selection). This is the portrait-tablet / handset presentation; as a
   dialog the compact form is a full-screen or large partial-cover modal.
 
+## Configuring the list region and the compact stack
+
+`resizable` forwards the list's `ResizableRegion` configuration alongside
+`size`, `min`, and `max`: `separator` (`"hidden"` keeps the resize hit target
+but paints no line), `handleIcon`, `contentOverflow`, and collapse —
+`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`, and
+`restorePosition`. A collapsed list snaps to zero width, renders `inert` and
+`aria-hidden`, and the detail fills the split; the app owns the `collapsed`
+flag and renders the restore control (usually a `FloatingToolbar`). Omitted
+options keep the region's defaults.
+
+```tsx
+resizable={{
+  size: listWidth.value,
+  min: 220,
+  max: 480,
+  collapsed: listCollapsed.value,
+  restoreControl: <ShowThreadsToolbar />,
+}}
+```
+
+`compactStack` configures the compact `NavStack`: `toolbarConfig`, `backIcon`,
+`backText`, `hideToolbar`, the persistent `bottomToolbar`, and `chromeDividers`
+forward to the stack, and `list` / `detail` give each view its own top-toolbar groups
+(`leading`, `center`, trailing `toolbar`) and `bottomToolbar`:
+
+```tsx
+compactStack={{
+  backText: "Threads",
+  toolbarConfig: { headingLevel: 1 },
+  list: { toolbar: <ComposeGroup /> },
+  detail: { toolbar: <ReplyGroup />, bottomToolbar: <MessageActions /> },
+}}
+```
+
 The catalog's **Interactive compact drill-down** example exercises this exact
 controlled flow: a list action sets the selected message, `detailActive` pushes
 its detail, and the wired Back action clears the selection to reveal the
-preserved list. Use the same structure in application demos so compact examples
-show the interaction rather than rendering a disconnected detail state.
+preserved list. It also forwards `compactStack`: a level-2 heading title over
+a bottom divider, a Compose group on the list view, and a Reply group plus a
+bottom toolbar on the detail. Use the same structure in application demos so
+compact examples show the interaction rather than rendering a disconnected
+detail state.
+
+The catalog's **Resizable, collapsible list** example forwards `resizable`: a
+hidden separator that still resizes the list (its committed width comes back
+through `wireResizableRegions`' `onCommit` into the app's size signal), a Hide
+control in the list's own toolbar, and a `FloatingToolbar` restore control in
+the split's bottom-start corner.
 
 Compose the interactive wiring from the existing helpers — `SplitView` adds no
 wire of its own.

package/docs/tab-scaffold.md

@@ -9,9 +9,14 @@ It is distinct from `TabBar` (document-oriented, reorderable strips).
 ```ts
 import { TabScaffold } from "@kerfjs/ui/tab-scaffold";
 import { wireTabScaffold } from "@kerfjs/ui/wire-tab-scaffold";
-import "@kerfjs/ui/tab-scaffold.css";
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads TabScaffold's stylesheet and those of the components it renders internally
+(the tab `Badge`). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/tab-scaffold.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
 ## Controlled selection
 
 The app owns the active tab (a signal); `TabScaffold` renders every tab's scene
@@ -44,7 +49,8 @@ const dispose = wireTabScaffold(root, {
 });
 ```
 
-Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, and `content`. The
+Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, optional `badge`
+and `badgeLabel` (see [Tab badges](#tab-badges)), and `content`. The
 bottom bar paints through the home-indicator safe area and pads for it and for
 the side insets, while each scene pads for the top and side insets (a scene
 whose only child is a `NavStack` or `Pane` lets that child own them; see
@@ -52,3 +58,68 @@ whose only child is a `NavStack` or `Pane` lets that child own them; see
 truncate horizontally with an ellipsis when a destination name exceeds its
 share of the bar. On larger device classes, promote the tab set to a
 `Workbench` rail or a persistent sidebar instead of a bottom bar.
+
+## Scroll divider
+
+The bar has no permanent top border. With `wireScrollDividers(appRoot)`
+installed (see [Layout › Scroll dividers](layout.md#scroll-dividers)), it shows
+a line along its top edge only while the active scene's content continues below
+it — not at the scroll end and not when the content fits. The line keys on
+whatever actually scrolls in the scene: the scene itself or, through a sole
+child, a `NavStack`'s active view or a `Pane`'s content. A `NavStack` with its
+own bottom toolbar sits between them, so that toolbar's line applies instead.
+The line is the bar's always-present 1px top border, colored only while shown,
+so it never moves the bar or a tab.
+
+`chromeDividers` configures it, with the same values as a `Pane`'s: `scroll`
+(the default) follows the scroll state and draws nothing until the wiring runs;
+`always` keeps the line, with or without the wiring; `none` drops it even when
+the wiring reports content below.
+
+## Tab badges
+
+Give a tab a `badge` (a count or short string such as `3`, `"99+"`, or
+`"New"`) to show the iOS tab-bar badge: a compact, solid `danger` `Badge` at the
+top-trailing corner of the tab's icon, growing outward as the text lengthens
+(without an icon it sits above the label). The badge is decorative
+(`aria-hidden`); its meaning reaches assistive technology through `badgeLabel`,
+which the tab folds into its accessible name as `"<label>, <badgeLabel>"`:
+
+```tsx
+{
+  id: "inbox",
+  label: "Inbox",
+  icon: <LucideIcon icon={Inbox} name="inbox" />,
+  badge: unread.value,
+  badgeLabel: `${unread.value} unread`,
+  content: <InboxStack />,
+}
+```
+
+`badgeLabel` defaults to the badge text itself, so supply a localized phrase
+whenever the bare text would be ambiguous. Omitting `badge` (or passing an
+empty string or a non-finite number) renders no badge and leaves the tab's name
+as its label; `0` renders, so pass `undefined` when a count should disappear.
+Keep the text short — clamp large counts (`"99+"`) in the app. The tone follows
+the platform convention and is fixed; do not restyle the badge.
+
+### Dot badges
+
+For new content without a count, pass `badge: true`. The tab shows the iOS
+tab-bar dot — an 8px solid `danger` `Badge` (`size="dot"`) centered on the
+icon's top-trailing corner (above the label without an icon). A dot has no
+text to fall back on, so `badgeLabel` is required by the types:
+
+```tsx
+{
+  id: "feed",
+  label: "Feed",
+  icon: <LucideIcon icon={Rss} name="rss" />,
+  badge: hasNewPosts.value ? true : undefined,
+  badgeLabel: "New activity",
+  content: <FeedStack />,
+}
+```
+
+The tab's accessible name becomes `"Feed, New activity"`. Pass `undefined` to
+clear the dot; `false` is not a badge value.

package/docs/type-contracts.md

@@ -11,22 +11,22 @@ public-signature artifact.
 
 ## Strengthened contracts
 
-| ID         | Compile-time guarantee                                                                                                                                                                                                                                                                                                        |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `KUI-T001` | `ListHeader` is a passive heading, a fully named/icon-bearing trailing action, or a controlled disclosure with `action` + `expanded`. Props ignored by the selected mode are rejected.                                                                                                                                        |
-| `KUI-T002` | `Select` has a visible `label` or an `ariaLabel`.                                                                                                                                                                                                                                                                             |
-| `KUI-T003` | A literal `Select.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                    |
-| `KUI-T004` | A literal `SegmentedControl.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                          |
-| `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `TokenSearchField({ collapsible: true })`.                                                                                                                                                                                                                        |
-| `KUI-T006` | `TokenSearchEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                                                                                                                                                           |
-| `KUI-T007` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                                                                                                                                                                     |
-| `KUI-T008` | A literal `TabScaffold.active` id belongs to its literal `tabs`.                                                                                                                                                                                                                                                              |
-| `KUI-T009` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                                                                                                                                                             |
-| `KUI-T010` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all AppTab, TabBar, ToolbarControlGroup, and Select presentation axes; the convenience root barrel re-exports them.                                                                                      |
-| `KUI-T011` | Semantic component zones use the recursive `KerfUiContent` type: `SafeHtml`, runtime-empty booleans/nullish values, and readonly nested arrays are valid; arbitrary strings, numbers, and signals are rejected. Explicit text positions such as `ListInsetText` retain their text exception.                                  |
-| `KUI-T012` | `List.gap` accepts finite `UiSpaceName` shorthands or a complete branded `CssLength`; raw strings and non-standalone `CssLengthExpression` arithmetic are rejected. `calc(plus(...))` promotes a typed expression to a complete value.                                                                                        |
-| `KUI-T013` | CSS-valued props preserve property grammar: `List.flex` uses `CssFlex`, `Skeleton` dimensions use `CssSize`/`CssLength`, and choice icons use `CssForegroundColor` (foreground tokens via `uiColor()` or `foregroundColorVar()`; fill aliases such as `uiColor('success')` are rejected); row declaration strings are absent. |
-| `KUI-T014` | Stable single-root visual components accept the explicit native `slot` attribute. Multi-root `ResizableRegion` and `CollapsiblePanel` remain excluded because no single returned element can own the assignment, and other arbitrary native attributes remain rejected.                                                       |
+| ID         | Compile-time guarantee                                                                                                                                                                                                                                                                                                                  |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KUI-T001` | `ListHeader` is a passive heading, a fully named/icon-bearing trailing action, or a controlled disclosure with `action` + `expanded`. Props ignored by the selected mode are rejected.                                                                                                                                                  |
+| `KUI-T002` | `Select` has a visible `label` or an `ariaLabel`.                                                                                                                                                                                                                                                                                       |
+| `KUI-T003` | A literal `Select.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                              |
+| `KUI-T004` | A literal `SegmentedControl.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                    |
+| `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `TokenSearchField({ collapsible: true })`.                                                                                                                                                                                                                                  |
+| `KUI-T006` | `TokenSearchEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                                                                                                                                                                     |
+| `KUI-T007` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                                                                                                                                                                               |
+| `KUI-T008` | A literal `TabScaffold.active` id belongs to its literal `tabs`.                                                                                                                                                                                                                                                                        |
+| `KUI-T009` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                                                                                                                                                                       |
+| `KUI-T010` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all AppTab, TabBar, ToolbarControlGroup, and Select presentation axes; the convenience root barrel re-exports them.                                                                                                |
+| `KUI-T011` | Semantic component zones use the recursive `KerfUiContent` type: `SafeHtml`, runtime-empty booleans/nullish values, and readonly nested arrays are valid; arbitrary strings, numbers, and signals are rejected. Explicit text positions such as `ListInsetText` retain their text exception.                                            |
+| `KUI-T012` | `List.gap` accepts finite `UiSpaceName` shorthands or a complete branded `CssLength`; raw strings and non-standalone `CssLengthExpression` arithmetic are rejected. `calc(plus(...))` promotes a typed expression to a complete value.                                                                                                  |
+| `KUI-T013` | CSS-valued props preserve property grammar: `List.flex` uses `CssFlex`, `Skeleton` dimensions use `CssSize`/`CssLength`, and choice icons use `CssForegroundColor` (foreground tokens via `uiColor()` or `foregroundColorVar()`; fill tokens such as `uiColor('success-fill-quiet')` are rejected); row declaration strings are absent. |
+| `KUI-T014` | Stable single-root visual components accept the explicit native `slot` attribute. Multi-root `ResizableRegion` and `CollapsiblePanel` remain excluded because no single returned element can own the assignment, and other arbitrary native attributes remain rejected.                                                                 |
 
 `KerfUiContent` lets conditionals and mapped component collections be direct
 siblings without an otherwise-unnecessary `Fragment`:
@@ -113,9 +113,10 @@ move errors into casts without making the integration safer.
   `{ keyboard: { removeAdjacentToken: false } }` when only caret navigation is
   wanted.
 - Add `wrap: true` anywhere `ToolbarText.maxLines` is used.
-- Replace `Toolbar({ divider: false })` with `dividerSides: ''`; the default
-  remains a bottom divider, while canonical combinations such as `tr` and
-  `trbl` select more physical edges.
+- Replace `Toolbar({ divider: false })` with `dividerSides: ''`, which is now
+  the default (a toolbar pinned over scrolling content gets its divider from
+  `wireScrollDividers` through its `Pane`); canonical combinations such as `b`,
+  `tr`, and `trbl` select permanent physical edges.
 - Replace raw `List.gap` strings with a direct spacing shorthand (`"xs"`,
   `"m"`) or a complete value from `@kerfjs/ui/css-values`. Replace
   `gap="0.25rem"` with `gap={rem(0.25)}` and wrap sums with `calc(plus(...))`.
@@ -123,7 +124,7 @@ move errors into casts without making the integration safer.
   keyword; replace raw Skeleton dimensions with `px`/`rem`/`em`/`pct` builders;
   and replace raw choice colors with a foreground token such as
   `uiColor('success-on-quiet')` or an app-owned `foregroundColorVar()`.
-  `SelectChoice.color` rejects fill aliases (`uiColor('success')`) and
+  `SelectChoice.color` rejects fill tokens (`uiColor('success-fill-quiet')`) and
   unqualified `colorVar()` values because a fill paints a nearly invisible
   icon.
 - Remove `style` from `ListItem` and `ListActionRow`; use `className`, public

package/docs/ui-analyzer.md

@@ -61,7 +61,7 @@ policy, or analysis inputs to the containing application.
 | `KUI-L002` | error  | A stylesheet references an unknown or private `--kui-*` token.                        |
 | `KUI-L003` | error  | One element combines public classes that claim the same geometry.                     |
 | `KUI-L004` | review | Nested literal classes both add a content inset.                                      |
-| `KUI-L005` | review | Consumer CSS forces a public component's dimensions.                                  |
+| `KUI-L005` | —      | Retired; folded into `KUI-L019` (see below).                                          |
 | `KUI-L006` | review | Literal spacing falls outside Kerf's approved scale.                                  |
 | `KUI-L007` | error  | A declared scroll owner is nested inside another scroll owner.                        |
 | `KUI-L008` | review | A dynamic class expression cannot be classified soundly.                              |
@@ -75,6 +75,10 @@ policy, or analysis inputs to the containing application.
 | `KUI-L016` | error  | A removed declaration-list escape hatch is used.                                      |
 | `KUI-L017` | review | A valid but exceptional off-scale shorthand needs justification.                      |
 | `KUI-L018` | review | A loud fill override lacks a governing `on-loud`, or the literal pair is below 4.5:1. |
+| `KUI-L019` | error  | A rule's subject is another package's component (class, `data-component`, or tag).    |
+| `KUI-L020` | error  | CSS reads or writes another component's private `--_*` variable.                      |
+| `KUI-L021` | error  | CSS overrides a component token that a typed prop sets.                               |
+| `KUI-L022` | error  | A class placed on a component's root is styled by the application (a hook class).     |
 
 Errors are provable contract violations and make the command exit 1. Review
 findings are deliberately heuristic and do not fail by default; pass
@@ -92,9 +96,10 @@ CSS extension points. A component catalog may additionally list shadow-part
 names in `boundaries.publicParts`; all other `::part()` targets are private.
 Part names are scoped to that entry's `boundaries.rootClass`, so an extension
 point on one component does not authorize the same-named part on another.
-Parent-owned placement and selectors for application-owned content remain
-allowed because the analyzer only reserves `.kui-*`, `--kui-*`, and cataloged
-shadow boundaries.
+Selectors for application-owned content remain allowed, including in a
+component's context (`.kui-pane > .my-content`): a public class is an
+extension point for naming a context, not for restyling the component itself,
+which `KUI-L019` reports.
 
 Catalog entries may also publish `cssValueProps`. Each path names its grammar,
 finite shorthands, canonical and exceptional scale steps, accepted typed
@@ -103,6 +108,94 @@ uses that same metadata for direct component calls and JSX, including nested
 paths such as `choices[].color`; consumer catalogs receive identical checks.
 Dynamic values remain a type-system responsibility rather than being guessed.
 
+## Component ownership (`KUI-L019`–`KUI-L022`)
+
+Components own their styles and are configured, never overridden. These
+diagnostics apply the package's own `check:css-ownership` rules to
+applications and component packages; the selector parsing is the same module
+(`analyzer/selectors.mjs`), so the package rule and the consumer rule agree on
+which element a selector styles.
+
+- **`KUI-L019` — a rule restyles a cataloged component.** The rule's subject
+  (the rightmost compound of each selector, ignoring `:has()` and `:not()`
+  arguments) names a public class of a cataloged component (`.kui-toolbar`,
+  `.kui-list-item__label`, `.acme-meter`), its `[data-component="…"]` root, or
+  a Web Awesome tag the package themes (`wa-button`, `wa-select`), and the rule
+  sets at least one ordinary property. A `::part()` subject is left to
+  `KUI-L011`; a rule that only sets custom properties is configuration, judged
+  by the token rules. Forcing a component's dimensions is one such restyle
+  and reports here once: `.kui-pane { width: 300px }`.
+- **`KUI-L020` — another component's private variable.** CSS reads or writes a
+  `--_<root>-*` variable of a cataloged component (`--_kui-list-gap`), or any
+  `--_kui-*` variable.
+- **`KUI-L021` — a token a typed prop sets.** CSS assigns `--<root>-<prop>`
+  where the component has that typed prop (`--kui-list-gap` is `List gap`,
+  `--kui-floating-toolbar-inset` is `FloatingToolbar inset`). The message
+  quotes the prop's cataloged example.
+- **`KUI-L022` — a hook class on a component's root.** A literal class on an
+  imported component's JSX (`<Toolbar className="header" />`) is the subject
+  of a rule in a stylesheet that file imports, so the application restyles the
+  component through it. The evidence names the stylesheet, line, and selector.
+
+Every message names the configuration to use (the component's typed props,
+public tokens, and variants from its catalog entry) and ends with the same
+route for a real need that has none: report the component gap to the owning
+package (open a feature request) instead of overriding it.
+
+What stays allowed mirrors the package rule, where a child styles itself in a
+parent's context:
+
+```css
+/* Your own element in a component's context. */
+.kui-toolbar > .my-widget {
+  margin-inline-start: auto;
+}
+/* Keying your own element on a component's state. */
+.shell:has(.kui-select[open]) .my-status {
+  opacity: 0.5;
+}
+/* Configuring a component through a public token with no typed prop. */
+.kui-list {
+  --kui-list-divider-color: var(--kui-color-neutral-border-quiet);
+}
+
+/* KUI-L019, KUI-L020, KUI-L021. */
+.kui-toolbar {
+  padding: 0;
+}
+.app {
+  --_kui-list-gap: 2px;
+  --kui-list-gap: 4px;
+}
+```
+
+Ownership is decided per package: a stylesheet belongs to the package whose
+`package.json` is nearest it, and only other packages' catalog entries are
+foreign to it. A component package built on Kerf UI therefore styles its own
+cataloged components (including `.kui-toolbar > .acme-meter` from its own
+stylesheet) without findings, while an application that restyles
+`.acme-meter` is reported against `@acme/widgets`. All four ids are
+ownership-boundary diagnostics, so `--adoption` reports them as review
+findings. `eslint-plugin-kerfjs`'s `ui-component-ownership` rule reports
+`KUI-L020` and `KUI-L021` in JavaScript and TypeScript (style strings, style
+objects, and `style.setProperty()`), where this analyzer reads only CSS.
+
+### Retired: `KUI-L005` (forced component dimension)
+
+`KUI-L005` used to report, as a review finding, any `width`/`height`/`min-*`/
+`max-*` declaration in a rule that mentioned a public component class
+anywhere in its selector. `KUI-L019` now reports every restyle whose subject is
+a cataloged component — dimensions included — so the subject case was
+double-reported (an error and a review finding for one declaration). Its only
+other shape, a public class as an ancestor
+(`.kui-pane .app-sidebar { width: 240px }`), sizes the application's own
+element in the component's context, which the ownership rules explicitly
+allow. With no unique true positive left,
+the rule was retired rather than narrowed. The analyzer no longer emits it;
+the id stays in `ai/application-ui-diagnostic-ids-v1.json` (listed under
+`retired`) so a profile exception that already names it still loads. Remove
+such exceptions at your convenience.
+
 ## Loud fill / on-loud pairing (`KUI-L018`)
 
 The shipped Web Awesome theme pairs every `--wa-color-{tone}-fill-loud` with a
@@ -207,6 +300,7 @@ validator.
 
 Review findings remain visible until explicitly suppressed. Avoid suppressing
 `KUI-L001`, `KUI-L002`, `KUI-L003`, `KUI-L007`, `KUI-L009`, `KUI-L010`,
-`KUI-L011`, `KUI-L012`, `KUI-L013`, `KUI-L014`, `KUI-L015`, or `KUI-L016`:
+`KUI-L011`, `KUI-L012`, `KUI-L013`, `KUI-L014`, `KUI-L015`, `KUI-L016`,
+`KUI-L019`, `KUI-L020`, `KUI-L021`, or `KUI-L022`:
 those indicate a
 definite boundary or parsing failure rather than an aesthetic judgment.

package/docs/ui-doctor.md

@@ -30,6 +30,16 @@ that lacks a governing `--wa-color-{tone}-on-loud` (in the same or an ancestor
 scope, in any stylesheet the same entry loads), or whose literal pair measures
 below 4.5:1 (see [the analyzer rule](./ui-analyzer.md#loud-fill--on-loud-pairing-kui-l018)).
 
+Component ownership is part of the same loop. The analyzer stage reports
+application or third-party CSS that restyles another package's component
+(`KUI-L019`), touches its private `--_*` variables (`KUI-L020`), overrides a
+token a typed prop sets (`KUI-L021`), or styles it through a hook class on its
+root (`KUI-L022`); the ESLint stage's `ui-component-ownership` rule reports
+`KUI-L020` / `KUI-L021` in script. Each finding's `action` points at the
+component's configuration, and its message routes a need with no prop to a
+component-gap report instead of an override (see
+[the analyzer rule](./ui-analyzer.md#component-ownership-kui-l019kui-l022)).
+
 The browser evaluator is different: it runs the application and is disabled by default. It only runs when configuration supplies `browser.url` or the command receives `--browser-url`. Start and authorize the target application separately.
 
 An unavailable or failed stage does not prevent independent stages from reporting. Its final exit is still a configuration failure, so a partial run cannot appear clean.

package/docs/ux-demo.md

@@ -1,6 +1,6 @@
 # UX catalog contract
 
-Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
+Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server reloads component source edits without a restart: component entries still load through their `dist/browser` wrappers, so each component's reachable CSS is exercised as consumers receive it, but the JavaScript those wrappers re-export (and every other `@kerfjs/ui` subpath) resolves to `src/`, and CSS resolves to `src/` as well. A component that gains a new CSS dependency needs a restart, because the wrapper listing its stylesheets is regenerated only by the build. Production demo builds, previews, and the browser tests use `dist/`. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
 
 Every Playwright entry point builds current source before the preview server
 starts. `npm run test:e2e -- tests/browser/row.spec.ts` and a direct focused
@@ -51,6 +51,6 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - The footer action log is an `aria-live` region, making interactions visible to both people and browser tests.
 - The focused Toast route calls Web Awesome's documented programmatic stack API and notes that Hot Sheet 2 still uses its own app-level toast implementation; the catalog demonstrates ecosystem support without implying current product adoption.
 - Browser coverage walks every Kerf, composition, and Web Awesome route, checks every listed Web Awesome custom element is registered in its focused specimen, exercises the ecosystem disclosure and both relationship directions, validates offline source/guidance hrefs and accessible wide/narrow/200%-zoom wrapping, and covers tab selection/reordering/overflow, semantic palettes and scoped overrides, light/dark rendering, toolbar popup and responsive find behavior, single/multiline search alignment, menu alignment, banner urgency, keyboard resizing, live custom-element values, and representative wide/narrow captures.
-- The production build keeps the catalog shell and Kerf routes in the entry chunk, then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
+- The production build keeps the catalog shell and Kerf routes in the entry chunk and moves the third-party code loaded at startup (the Web Awesome select and popup-menu registrations with their Lit and Floating UI runtime) into an eagerly preloaded `vendor` chunk, so neither nears the largest-chunk limit in `demo-bundle-budget.json`; only modules statically reachable from the entry qualify, so lazy-only dependencies stay in their lazy chunks. It then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
 
 Before handoff, inspect the actual captures for readability, context, alignment, clipping, spacing, responsiveness, focus, and obvious defects. Fix and recapture rather than treating the screenshot as proof by itself.

package/docs/webawesome-theme.md

@@ -176,8 +176,7 @@ their open state uses the independent `rotate` property.
 
 That scale applies to each Web Awesome component's intrinsic glyph and is
 independent of Kerf `DisclosureArrow`, whose default box is 18px relative to
-the root font size and whose consumer override is
-`--kui-disclosure-arrow-size`.
+the root font size and whose consumer override is its typed `size` prop.
 
 Tooltip and Popover use arrowless floating surfaces by default, matching Hot
 Sheet 2. The theme sets Web Awesome's public `--wa-tooltip-arrow-size` token to