@kerfjs/ui 5.0.0-beta.49 → 5.0.0-beta.51

package/docs/document-baseline.md

@@ -0,0 +1,31 @@
+# Document baseline
+
+Import `@kerfjs/ui/document.css` when an application wants Kerf UI to own its
+document-level defaults:
+
+```ts
+import "@kerfjs/ui/document.css";
+```
+
+```html
+<body>
+  <div id="app" class="kui-app-root"></div>
+</body>
+```
+
+The opt-in stylesheet applies `border-box` sizing to every element and
+pseudo-element, removes the body margin, and gives the body the foundation
+font, foreground, lowered surface, and `1.45` line height. Plain links use the
+semantic `--kui-color-text-link` token with zero selector specificity.
+
+`html`, `body`, and `.kui-app-root` form a definite `height: 100%` chain. Add
+`.kui-app-root` to the one direct mount container of a full-height application
+whose child is a `Workbench`, `SplitView`, `NavStack`, or another percentage-
+height shell. Ordinary document-flow pages can import the baseline without the
+class. Do not put `.kui-app-root` on several sibling containers: each requests
+the full available document height.
+
+The stylesheet is intentionally absent from `@kerfjs/ui/styles.css` and every
+component browser import because its global selectors would otherwise change
+consumer documents implicitly. Import it once and load application overrides
+after it.

package/docs/layout.md

@@ -35,6 +35,14 @@ each enabled side uses `--kui-pane-separator-width` (1px) and
 `--kui-pane-separator-color` (`--kui-color-border`). Logical sides keep pane
 boundaries correct in both left-to-right and right-to-left layouts.
 
+A pane is safe-area aware. Its background and separators paint through a
+device's unsafe areas while its header, content, and footer pad for each side
+the pane still reaches; the content's block insets are scroll padding, so its
+first and last items can always be scrolled clear. Layouts clear the sides a
+pane does not reach. In an app-owned arrangement, pass `safeAreaEdges` (the
+same logical sides as `separators`; all four by default, `[]` to opt out). See
+[Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+
 `.kui-content` is a vertical stack with a 24px gap between major children.
 Sections may contain adjacent `ListItem` rows without adding another major gap.
 Ordinary surface-like children use `.kui-content-item` and own their complete
@@ -66,17 +74,18 @@ semantic status.
 
 ## Public roles and tokens
 
-| Need                                     | Class                     | Token / default                       |
-| ---------------------------------------- | ------------------------- | ------------------------------------- |
-| Unpadded header/content/footer structure | `Pane`, `.kui-pane`       | —                                     |
-| Scrolling pane content                   | `.kui-pane__content`      | —                                     |
-| Optional logical-edge separators         | `Pane.separators`         | `--kui-pane-separator-width: 1px`     |
-| Major vertical rhythm                    | `.kui-content`            | `--kui-layout-content-gap: 24px`      |
-| Self-contained child geometry            | `.kui-content-item`       | 8px margin + 1px border + 8px padding |
-| Pill child                               | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px`      |
-| Related controls                         | `.kui-control-cluster`    | `--kui-layout-control-gap: 8px`       |
-| Inline metadata                          | `.kui-inline-metadata`    | `--kui-layout-metadata-gap: 4px`      |
-| Explicit scroll owner outside a pane     | `.kui-scroll-owner`       | `overflow: auto`                      |
+| Need                                     | Class                     | Token / default                                                             |
+| ---------------------------------------- | ------------------------- | --------------------------------------------------------------------------- |
+| Unpadded header/content/footer structure | `Pane`, `.kui-pane`       | —                                                                           |
+| Scrolling pane content                   | `.kui-pane__content`      | —                                                                           |
+| Optional logical-edge separators         | `Pane.separators`         | `--kui-pane-separator-width: 1px`                                           |
+| Safe-area sides a pane may pad           | `Pane.safeAreaEdges`      | `--kui-safe-area-*: env(safe-area-inset-*)`, routed as `--kui-edge-inset-*` |
+| Major vertical rhythm                    | `.kui-content`            | `--kui-layout-content-gap: 24px`                                            |
+| Self-contained child geometry            | `.kui-content-item`       | 8px margin + 1px border + 8px padding                                       |
+| Pill child                               | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px`                                            |
+| Related controls                         | `.kui-control-cluster`    | `--kui-layout-control-gap: 8px`                                             |
+| Inline metadata                          | `.kui-inline-metadata`    | `--kui-layout-metadata-gap: 4px`                                            |
+| Explicit scroll owner outside a pane     | `.kui-scroll-owner`       | `overflow: auto`                                                            |
 
 The component layer applies the same contract to `Toolbar`, `ListHeader`,
 `ListItem`, `Toolbar`, `StateBanner`, `ValueTable`,
@@ -87,6 +96,12 @@ also keeps 8px of root-scaled block padding independently of its semantic inline
 inset. Most interactive rows and toolbar groups are 44px tall.
 Toolbar groups reserve a real 1px outer border around a 42px inner area, even
 when their border and background are transparent.
+Trailing icon actions share one axis: a toolbar control centers its glyph in
+that 44px slot at the 8px inline margin, and a `ListHeader` action centers its
+fitted 36px square in a slot of the same size (a transparent hit layer extends
+its pointer target to fill that 44px slot), so a Pane header's trailing toolbar
+action and the `ListHeader` action beneath it line up (30px from the pane edge
+at the default scale).
 Panel, dialog, and page headings are plain `Toolbar` compositions. The leading
 zone holds an optional icon `ToolbarControlGroup` and a direct extra-large
 `ToolbarText`; actions belong in a trailing group. Omit empty groups. Supporting
@@ -120,18 +135,30 @@ CSS strings.
 
 ## Text
 
-Use `Text` from `@kerfjs/ui/text` for ordinary semantic headings and
-paragraphs. It renders a native `p` by default; set `variant` to `h1`–`h6` when
-the document outline calls for a heading. Ordinary global, `data-*`, and
-`aria-*` attributes pass through. Every variant resets its native margin, owns a
-1px transparent border, and supplies the standard 8px item padding; native
-typography remains available to the surrounding composition. Choose heading
-levels from the document outline, not for visual size. Toolbar identity and
-page-heading compositions continue to use `ToolbarText`.
+Use `Text` from `@kerfjs/ui/text` for ordinary semantic headings, paragraphs,
+and inline secondary text. It renders a native `p` by default; set `variant` to
+`h1`–`h6` when the document outline calls for a heading, or `span` for inline
+copy inside a row, label, or table cell. Ordinary global, `data-*`, and `aria-*`
+attributes pass through. Block variants reset their native margin, own a 1px
+transparent border, and supply the standard 8px item padding. The `span`
+variant owns no margin, border, or padding. Choose heading levels from the
+document outline, not for visual size. Toolbar identity and page-heading
+compositions continue to use `ToolbarText`.
+
+`Text` is also the answer for a normal-color subsection title. `ToolbarText`
+below `xlarge` (`large`, `default`, `small`) is deliberately quiet: it labels a
+toolbar's identity — a pane name or a status — and must not compete with the
+content and controls around it, so it has no tone option. A subsection title is
+document content, not toolbar identity: use `Text` with the `h2`–`h6` variant
+the outline calls for (inside a `List` with `controlInsets`, its text lines up
+with content items). Use `ListHeader` when the section is a list or menu group
+that needs a count, badge, action, or disclosure, and keep extra-large
+`ToolbarText` for the panel, dialog, or page title.
 
 Presentation is independent of the native element: use `tone="quiet"` for
 supporting copy, `tone="danger"` for error or validation copy, `size="compact"`
-for compact metadata, and `font="monospace"` for code or identifiers. These
+for compact metadata, and `font="monospace"` for code or identifiers (the
+`--kui-font-mono` stack, which Kerf owns even with Web Awesome loaded). These
 finite props compose with each other and with every semantic `variant`; omit
 them to inherit the surrounding color, size, and font.
 
@@ -139,8 +166,10 @@ them to inherit the surrounding color, size, and font.
 import { Text } from "@kerfjs/ui/text";
 
 <Text variant="h2" id="details-title">Details</Text>;
+<Text variant="h3">Notifications</Text>; // normal-color subsection title
 <Text aria-describedby="details-title">Supporting copy</Text>;
 <Text tone="quiet" size="compact">Updated yesterday</Text>;
+<strong>Inbox<Text variant="span" tone="quiet" size="compact"> · 3 msg</Text></strong>;
 <Text tone="danger" font="monospace">ERR_INVALID_ID</Text>;
 ```
 
@@ -221,6 +250,35 @@ for the CSS initial value, pass `true` for `1 1 auto`, select the finite
 shorthand. A `CssLength` is not a flex shorthand, and arbitrary strings are
 rejected by the type contract.
 
+### Filling a fixed-height parent
+
+`flex` sizes a Row, List, or Grid inside a flex layout. When one of them is the
+layout **root** of a parent with a definite height (an app mount container
+with the `.kui-app-root` height chain, a dialog body, or a fixed-height catalog
+frame), pass `fill` instead: the root takes the parent's full height
+(`height: 100%`), so its `flex` children can grow into it. Use `fill` only on
+that sole layout root; a sibling inside a flex layout keeps using `flex`.
+
+Put route, test, or recipe metadata on the same root with `rootAttributes`,
+which accepts safe `data-*` pairs and keeps each component's structural
+attributes (`data-component`, `data-flex`, `data-fill`, alignment, inset, and
+column markers) protected:
+
+```tsx
+<Row gap="none" fill rootAttributes={{ "data-recipe": "sidebar" }}>
+  <CollapsiblePanel id="rail" side="left" collapsed={railCollapsed.value}>
+    …
+  </CollapsiblePanel>
+  <List flex>…</List>
+</Row>
+```
+
+Do not wrap a layout in a frame `Pane` just to get a definite height or a root
+attribute: the pane's content slot becomes a scroll owner that never scrolls,
+and its safe-area padding keeps an edge-docked rail or drawer from painting
+through the unsafe area. A `Pane` is for a real column with a header, one
+scrolling content region, or a footer.
+
 Both components also accept `textInsets` and `controlInsets` using the shared
 physical `Sides` union. Values follow canonical top/right/bottom/left order
 (`t`, `rb`, `tbl`, `trbl`, and so on). A selected control side adds 8px of
@@ -229,11 +287,18 @@ padding. A selected text side adds the complete content-item alignment inset —
 container padding. When both props select the same side, the text inset wins.
 Each nested `Row` or `List` resolves its own four inset sides; unselected sides
 reset to zero instead of inheriting a same-type parent's inset selection.
+The same holds for `gap` and `flex` on a nested `List`, `Row`, or `Grid`: an
+omitted prop falls back to that component's own default (no gap for `List`,
+`xs` for `Row` and `Grid`; the CSS initial `flex`) rather than the enclosing
+instance's value.
 
 `ListInsetText` and `ListInsetControl` use the same `sides` vocabulary and
 default to `trbl`. The text wrapper applies its complete 8/1/8 geometry only on
 selected sides; the control wrapper applies its 8px outer margin only on
-selected sides. `ListInsetText.horizontalOnly` remains a deprecated alias for
+selected sides. Every direct child of `ListInsetControl` grows to fill the row
+(a `Select`, a `wa-input`, or a `wa-button` spans the full inset width), and
+several children share the row with an 8px gap; stack controls vertically with
+a `List` using `controlInsets` instead. `ListInsetText.horizontalOnly` remains a deprecated alias for
 `sides="rl"`; an explicit `sides` value takes precedence.
 
 `--kui-space-s` (12px) and `--kui-space-xl` (32px) exist but are **off the

package/docs/nav-stack.md

@@ -65,6 +65,14 @@ 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.
 
+## Safe areas
+
+The stack paints through a device's unsafe areas. Its chrome pads for the top
+and side insets, its bottom toolbar for the bottom and side insets, and each
+view pads the remaining edges inside its scroller, so content scrolls under the
+unsafe area but can always be scrolled clear. A view whose only child is a
+`Pane` or layout lets that child own the insets. See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+
 ## Transitions
 
 `wireNavStack(root, { onBack, duration? })` observes the rendered stack and

package/docs/recipes.md

@@ -1,10 +1,10 @@
 # Production composition recipes
 
-These seven reference compositions sit between individual primitives and product
-code. Open each stable UX-catalog route to run it, then copy the linked TSX and
-CSS. The examples import public package subpaths, use semantic layout owners,
-and keep state in a per-instance application adapter. They are not new
-monolithic components.
+These ten reference compositions sit between individual primitives and product
+code. Open each stable UX-catalog route to run it, then copy the linked TSX. The
+examples import public package subpaths, compose components through their
+props and tokens, and keep state in a per-instance application adapter. They
+ship no stylesheet of their own and are not new monolithic components.
 
 Copy the recipe source together with the catalog-independent
 [`mount-recipe.ts`](../ux-demo/recipes/mount-recipe.ts) adapter. It mounts the
@@ -28,11 +28,22 @@ specific dispatch; either way, wire once at a stable root and retain disposal.
 
 ## Desktop application shell
 
-[Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx) · [shared CSS](../ux-demo/recipes/recipes.css)
-
-Use `Toolbar`, controlled `ResizableRegion` panes, and one
-`.kui-pane__content` scroll owner per pane. The recipe owns the shell topology;
-the app owns routing, responsive pane visibility, sizes, persistence, and data.
+[Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx)
+
+A filling `List` (`fill`, with the recipe's `data-*` markers through
+`rootAttributes`) stacks the app-bar `Toolbar` above a `Row` that places
+controlled `ResizableRegion` navigation and inspector panes around a content
+`Pane` that a one-column `Grid` grows to fill. Each region's lone `Pane` fills
+the region's full height, so it reaches the bottom edge the separator does.
+Only those three real panes own a
+`.kui-pane__content` scroll owner; no frame `Pane` wraps the layout in a scroll
+owner that never scrolls. Each pane lists the screen edges it reaches in
+`safeAreaEdges` (the bottom plus its outer side, or both sides when it is the
+only pane shown), and the app-bar `Toolbar` claims the top edge and both sides
+with its own `safeAreaEdges`, so it clears the status area. Below desktop sizes the app reads `deviceClass()` and shows one
+pane at a time, switched by a pressed-state `ToolbarControlGroup`. The recipe
+owns the shell topology; the app owns routing, responsive pane visibility,
+sizes, persistence, and data.
 Keep each visible pane's collapse action in its own toolbar. Once hidden, put
 its restore action in the adjacent main toolbar on the same logical edge:
 leading for an inline-start sidebar and trailing for an inline-end inspector.
@@ -64,17 +75,19 @@ controls relocate without changing focus order.
 
 [Open the recipe](../ux-demo/?component=recipe-list-detail-dialog) · [TSX source](../ux-demo/recipes/list-detail-dialog.tsx)
 
-The production Web Awesome dialog owns modal focus and Escape; the thin recipe
-adapter restores the invoking control consistently after the hide event.
-`Toolbar`, `ListHeader`, `ListItem`, and `ValueTable` own their included
-anatomy. The application owns open state, selection, dismissal policy, and
-record actions. A `ToolbarControlGroup` places the app's trailing controls in
-the top toolbar's trailing zone.
-The header sits on the dialog edge while retaining its internal control inset;
-the selected title receives the full content gutter, the metadata table fills
-the available detail width between the usual outer margins, and the action
-cluster uses one outer gutter without a second content-item inset.
-Do not rebuild the dialog or reach into private shadow parts.
+The production Web Awesome dialog owns modal focus, Escape, its labeled header,
+and its close control; the thin recipe adapter restores the invoking control
+after the hide event. `DialogSurface` chooses the large modal with no body
+inset, because `SplitView` and its rows own list geometry, and a comfortable
+footer inset for the record actions. On roomy devices `SplitView` shows the
+project list beside its detail; each pane opens with a `ListHeader` on one
+shared line, and the dialog title, both headers, and the list text share the
+17px text edge while the `ValueTable` keeps the 8px outer margin. On compact
+devices the dialog becomes a full-screen sheet and `SplitView` becomes a
+`NavStack` drill-down whose back control the application pops. The
+application owns open state, selection, the pushed detail, dismissal policy,
+and record actions. Do not rebuild the dialog or reach into private shadow
+parts.
 
 ## Composer form
 
@@ -82,12 +95,13 @@ Do not rebuild the dialog or reach into private shadow parts.
 
 A direct `ToolbarText` supplies the task title, with app-owned supporting copy
 below; their ids are referenced by the form. `ListInsetText` gives that bare
-supporting copy the same content-item text inset as the fields instead of
-duplicating its geometry in recipe CSS. Production fields own labels, help, and
-native focus. The field
-and footer control edges sit directly on the shared 8px inline gutter rather
-than acquiring a second content-item padding inset; major children remain 24px
-apart and related controls use 8px gaps. The app owns
+supporting copy the same content-item text inset as the fields. The title and
+supporting line share a nested heading `List` with `gap="none"`, so the heading
+unit stays together instead of taking the form's 24px section gap. Production
+fields own labels, help, and native focus. One `List` owns the 24px major
+rhythm; the field `List` and the action `Row` use `controlInsets` to sit on the
+shared 8px inline gutter with 8px gaps between related controls, rather than
+acquiring a second content-item padding inset. The app owns
 validation, drafts, permissions, and transport. Persistent error or success
 feedback is the only nested semantic surface and uses `StateBanner`, not a toast.
 Because upgraded Web Awesome fields retain live value properties, controlled
@@ -111,8 +125,10 @@ Use `ToolbarControlGroup` for related commands, `SegmentedControl` for a few
 visible exclusive choices, `Select` for a longer value list, and an ordinary
 button for an independent command. Even that independent button sits in a
 single-control `ToolbarControlGroup`, which keeps its height, pill shape, focus,
-and hover treatment aligned with the adjacent toolbar controls. The app owns
-values, actions, persistence, and responsive priority.
+and hover treatment aligned with the adjacent toolbar controls. At compact
+widths the toolbar stacks its zones and wraps whole trailing groups onto another
+row, so the last action is never clipped. The app owns values, actions,
+persistence, and responsive priority.
 
 ## Navigation stack
 
@@ -121,8 +137,8 @@ values, actions, persistence, and responsive priority.
 Drill from a library list into a detail and back with `NavStack`
 (`@kerfjs/ui/nav-stack`): the app owns the stack as a signal of views and
 pushes/pops it, `NavStack` renders it, and `wireNavStack` slides the content and
-settles the chrome (reduced motion collapses the slide to instant). A live
-`deviceClass()` badge shows the current size/orientation. See the layout guide
+settles the chrome (reduced motion collapses the slide to instant). See the
+layout guide
 [`app-layouts.md`](app-layouts.md) for choosing among `NavStack`, `SplitView`,
 `Workbench`, and `TabScaffold`.
 
@@ -135,7 +151,9 @@ value-bearing component (`ToolbarText`, `ValueTable`/`ValueTableRow`, `Select`,
 `SegmentedControl`, `ListItem`, `StateBanner`) takes its `placeholder` from one
 loading flag, so the same real chrome renders a faithful loading state and then
 the populated record — no separate skeleton markup. The composition is the point;
-`Skeleton` is the primitive it builds on. The app owns the loading lifecycle and
+`Skeleton` is the primitive it builds on. Its heading `Toolbar` uses
+`responsive="wrap"`, so on a narrow inspector the toggle moves below a whole
+record title instead of truncating it. The app owns the loading lifecycle and
 which values are still unknown.
 
 ## Collapsible sidebar
@@ -145,14 +163,24 @@ which values are still unknown.
 A mini app frame whose left navigation rail and bottom activity drawer are
 standalone `CollapsiblePanel`s (`@kerfjs/ui/collapsible-panel`) driven by
 `wireSidebar` (`@kerfjs/ui/wire-sidebar`). `CollapsiblePanelToggle` supplies the
-standard per-side glyph: a collapse toggle lives inside each panel and an expand
-toggle lives in the always-visible main header, so a collapsed panel is still
+standard per-side glyph: a collapse toggle lives inside each panel, and the
+always-visible main header shows that panel's expand toggle only while it is
+collapsed, so exactly one control owns each action and a collapsed panel is still
 reachable. `wireSidebar` owns the toggle delegation, moves focus into a panel on
-open and restores it to the trigger on close, and — when a `deviceClass()` reports
-`compact` — switches the open panel to a dismissable **overlay** (backdrop, Escape
-and backdrop-click collapse, and a trapped Tab ring, the ARIA dialog pattern). It
-also persists each panel's collapsed state through a supplied storage hook. The app
-owns each `collapsed` signal, the panel sizes, and the content; the wire owns the
+open, restores it on close (to the trigger, or to the panel's expand toggle when
+the trigger sits inside the collapsed panel), and — when a `deviceClass()` reports
+`compact` — presents the panels as a dismissable **overlay** (backdrop, Escape
+and backdrop-click collapse, and a trapped Tab ring, the ARIA dialog pattern).
+The overlay starts closed and opens only from a toggle; the rail's signal is
+seeded from the device class with `inlineCollapsed: false`, so the first compact
+render has no overlay and a wide crossing restores the open inline rail. It
+also persists each panel's inline collapsed state through a supplied storage hook. A
+filling `Row` (`fill` plus `rootAttributes`) is the root: it takes the frame's
+definite height and places the rail beside a `List` column, and a one-column
+`Grid` grows the main pane above the drawer. Because the panels sit at the real
+frame edges, each grows through its edge's safe area and hands that edge back to
+its siblings when it collapses; the drawer's activity log is a `ValueTable`. The app owns each
+`collapsed` signal, the panel sizes, and the content; the wire owns the
 ephemeral interaction. For a full three-pane shell use `Workbench` instead — see
 [`app-layouts.md`](app-layouts.md). This recipe is covered end-to-end across
 Chromium, Firefox, and WebKit by `tests/browser/collapsible-sidebar-recipe.spec.ts`.
@@ -164,9 +192,16 @@ Chromium, Firefox, and WebKit by `tests/browser/collapsible-sidebar-recipe.spec.
 - For direct `wa-*` JSX, import types from `@kerfjs/ui/webawesome`. Import only
   individual Web Awesome registration modules and theme them with
   `@kerfjs/ui/webawesome.css`.
-- Prefer public props and variables at the composition boundary. When a recipe
-  needs responsive topology, join only classes listed in the catalog's
-  `publicClasses`; do not copy component markup or select descendants by tag,
-  id, attribute alone, or an unlisted implementation class.
+- 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
+  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
+  every file in `ux-demo/recipes/`.
+- Each recipe also exports a catalog-only `presentation`: the `CatalogExample`
+  viewport that frames it in the UX catalog and its ownership note. An
+  application that copies the recipe ignores that export and mounts the
+  controller into its own container.
 - Start from the copyable mount adapter, or reproduce its complete boundary:
   wire stable `data-action` hooks once and retain every disposer.

package/docs/split-view.md

@@ -13,6 +13,14 @@ import "@kerfjs/ui/split-view.css";
 // wireResizableRegions / wireNavStack for the interactive behavior.
 ```
 
+## Safe areas
+
+The list pane grows by the inline-start unsafe inset and pads for the edges it
+touches; the detail pads for its own outer edges. Neither is inset on the
+shared interior edge. A pane whose only child is a `Pane` lets that child own
+the insets, and the compact form hands them to its `NavStack`. See
+[Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+
 ## Responsive by device class
 
 `SplitView` is declarative; the app derives `compact` from the device class and

package/docs/tab-scaffold.md

@@ -45,8 +45,10 @@ const dispose = wireTabScaffold(root, {
 ```
 
 Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, and `content`. The
-bottom bar respects the home-indicator safe area (`env(safe-area-inset-bottom)`)
-and keeps 44px targets. Its single-line labels preserve their full line box and
+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
+[Choosing an app layout › Safe areas](app-layouts.md#safe-areas)). The bar keeps 44px targets. Its single-line labels preserve their full line box and
 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.

package/docs/type-contracts.md

@@ -11,21 +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 `CssColor`; row declaration strings are absent.                                                                                                |
+| 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.                                                       |
 
 `KerfUiContent` lets conditionals and mapped component collections be direct
 siblings without an otherwise-unnecessary `Fragment`:
@@ -119,7 +120,11 @@ move errors into casts without making the integration safer.
   `gap="0.25rem"` with `gap={rem(0.25)}` and wrap sums with `calc(plus(...))`.
 - Replace raw `List.flex` shorthands with `flex(grow, shrink, basis)` or a finite
   keyword; replace raw Skeleton dimensions with `px`/`rem`/`em`/`pct` builders;
-  and replace raw choice colors with `uiColor()` or `colorVar()`.
+  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
+  unqualified `colorVar()` values because a fill paints a nearly invisible
+  icon.
 - Remove `style` from `ListItem` and `ListActionRow`; use `className`, public
   tokens, and cataloged props. These breaking cleanups land before 5.0 stable.
 

package/docs/ui-analyzer.md

@@ -17,6 +17,25 @@ composition catalog by `package:id`, parses literal JavaScript/TypeScript
 component calls, TSX/JSX, and CSS, and reports portable repository-relative
 locations.
 
+An imported component name is resolved to a catalog entry by `package:id`, not
+by display name: several entries share one (the Kerf `Select` and the Web
+Awesome `wa-select` are both "Select"), so the analyzer joins each composition
+entry to its selection-catalog public exports and import subpaths and picks
+the entry that the import actually names. That keeps the Kerf component's
+CSS-value contracts (`KUI-L013`–`KUI-L017`) in force for `Select` and
+`Skeleton`.
+
+Only component exports resolve to an entry. A selection-catalog
+`publicExports` list also carries the helpers a component's props consume
+(`Select` ships `uiColor`, `List` ships `px`, `rem`, and `flex`), and a helper
+never inherits its entry's contracts, so `uiColor({ choices: [...] })` is not
+checked as a `Select` call. A component export is one whose name starts with
+an uppercase letter, the same rule JSX uses to tell a component tag from an
+intrinsic element; `eslint-plugin-kerfjs` applies the identical rule, and the
+package's catalog check fails if a cataloged render function (a value
+returning `SafeHtml`) is lowercase or any other runtime value is uppercase.
+Third-party catalogs should follow the same naming convention.
+
 Analysis is scoped per source file. Each TSX/JSX file resolves package,
 workspace, and parent-to-child directory profiles from its own location, then
 follows its relative CSS imports (including nested CSS `@import`s). Stylesheet

package/docs/ui-evaluator.md

@@ -61,6 +61,23 @@ shared container and `data-kui-align-edge` on two or more elements whose logical
 start edges must align. Use `data-kui-scroll-scope` only for an application-owned
 scope that is not a `.kui-pane`.
 
+Target size (`KUI-B050`) measures the area the pointer can actually reach, not
+just the border box. When a control's box is under 44 × 44, the evaluator
+hit-tests outward from its center with `elementFromPoint`, so a transparent hit
+layer (a positioned `::before`/`::after` that receives pointer events, as on the
+`ListHeader` action) counts toward the target, while a pseudo-element with
+`pointer-events: none`, a clipping ancestor, or an overlapping neighbor does
+not. Where the probe reaches the viewport edge it mirrors the opposite side's
+reach; a control whose center is off-screen or covered keeps its border box.
+The diagnostic evidence reports the measured `width`/`height` and the border
+`box`.
+
+Compact density is a documented exception. Inside `[data-density="compact"]` —
+the compact `List`/`ListHeader` family, whose rows are 36px tall — a target
+still needs the full 44px width but only the 36px row height, because a taller
+hit layer would reach into the neighboring row. The evidence's `required` field
+names the floor that applied (`44×44`, or `44×36` in compact density).
+
 Accessible names follow ARIA/native naming inputs, including labels, referenced
 content with `aria-hidden` descendants removed, and native input values.
 Geometry checks use each catalog entry's explicit `boundaries.rootClass`; the