@kerfjs/ui 5.0.0-beta.50 → 5.0.0-beta.52

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 composition CSS](../ux-demo/recipes/recipe-components.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,26 @@ 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
-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
+standard per-side glyph: a collapse toggle lives inside each panel, and the
+panel's expand toggle shows only while it is collapsed, so exactly one control
+owns each action and a collapsed panel is still reachable. The rail's expand
+toggle sits in the always-visible main header; the drawer's floats in a
+`FloatingToolbar` at the bottom edge the drawer opens from, next to where the
+action happens. `wireSidebar` owns the toggle delegation, moves focus into a
+panel on 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 +194,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. A recipe's own
-  component may style the structure it renders, but its stylesheet must not
-  select nested Kerf or Web Awesome components. Add missing configuration to the
-  owning component instead of copying markup or reaching through its boundary.
+- 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,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 `CssColor`; 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 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`:
@@ -120,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

package/docs/ux-demo.md

@@ -18,20 +18,20 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 
 - It imports public component subpaths, exercising their browser-selected reachable CSS rather than a catalog-only style path.
 - The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
-- The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding, closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
+- The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, pending, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding, closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
 - Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, and feedback scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component. The former aggregate Web Awesome theme specimen is intentionally omitted because its component families are covered by those focused routes.
 - `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Functional groups follow their authored importance order; components precede compositions inside each group, equal-importance entries use alphabetical order, and the Recipes group comes last. Composition names stay concise and project a visible `Composition` sidebar tag. Non-supported Web Awesome recommendations project to a visible `Discouraged` tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
 - Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
 - The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 15 discouraged choices. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
 - The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with supporting copy in its own aligned row; the current-view heading is also a toolbar. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The checkerboard belongs to the preview scroll owner rather than a viewport-height stage or nested card, and one explicitly repeated SVG tile keeps the pattern continuous through below-fold content. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
 - The composer-form recipe demonstrates one coherent visible form surface with toolbar title/supporting-copy hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
-- The list-detail dialog recipe places its header directly on the dialog edge while preserving the header's internal inset, gives the selected project title the complete outer-plus-inner content gutter, lets the value table fill the available detail column between the shared outer margins, and keeps record actions on one outer gutter without an extra content-item inset. Browser geometry coverage protects those relationships at wide and narrow widths.
+- The list-detail dialog recipe composes `DialogSurface`, the dialog's own labeled header and close control, `SplitView`, and footer actions. Its `SplitView` sits flush in the dialog body, both panes open with a `ListHeader` on one shared line, the dialog title and header text share the 17px text edge, the value table keeps the 8px outer margin, and the trailing actions keep the 16px footer gutter. Compact devices get a full-screen sheet with a list-to-detail drill-down. Browser geometry coverage protects those relationships at wide and narrow widths.
 - Catalog-only brand marks, preview dimensions, checkerboard tiles, and the compound display-settings control retain local geometry because they are specimen chrome or intrinsic control anatomy rather than reusable application spacing roles.
 - The menu composition route demonstrates toolbar/content/footer anatomy, 24px major gaps, 8/1/8 child geometry, the full-width `ListHeader` count-or-badge/action split, logical-end 44px action targets with 18px visuals, and 44px row/header/toolbar targets. Its one chevron is a production 18px `DisclosureArrow` inside a controlled Tools header that actually reveals and hides content; ordinary Projects navigation has no false disclosure affordance. Browser assertions cover stable naming, expanded/content transitions, visual rotation, node identity, reduced motion, RTL alignment and containment, and wide, narrow, dark, and 200% layouts. The focused ListHeader route separately shows the shared neutral count pill for Attachments, Notes (including zero), and Duplicates plus a non-count legacy badge, full-width logical-end actions, and no disclosure without content.
 - The `DisclosureArrow` route renders the production 18px root-scaled default without a catalog-only size override. Its two native buttons independently control the default right-to-down chevron and a recognizable right-facing replacement arrow with left-to-up custom directions; both use shortest-path rotation and their names stay stable while `aria-expanded` communicates state. Browser coverage verifies the custom clockwise path, pointer and native keyboard activation, focus, narrow and 200%-zoom stacking with contained labels, consumer sizing, and the independent `.5` Web Awesome glyph scale retained by Kerf `Select`.
 - A detail with relationships renders one content-fitted `Components` footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Its popup owns the standard surface inset so headings and even long component names stay clear of the menu border. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
-- Demo-only CSS supplies only the catalog shell and stages; component appearance stays in package CSS. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
-- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. Individual Web Awesome action, form, layout, navigation, feedback, media, and helper routes provide focused theme specimens without a redundant aggregate route; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges plus a scoped override; the Application tabs composition demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
+- Focused demos ship no local stylesheets, inline styles, or styling-only class names. They compose Kerf components first, Web Awesome surfaces where Kerf has no equivalent, and ordinary semantic HTML for the remainder. The catalog-owned `CatalogExample.viewport` contract supplies the few specimen constraints needed to demonstrate layout behavior. Recipes follow the same rule: they ship no stylesheets, inline styles, or styling-only classes, and the catalog frames each one in the `CatalogExample` viewport its exported `presentation` declares (full-width application arrangements span the canvas measure; narrower recipes sit in the centered example column). Demo-only CSS is limited to the document-shell `style.css`, which carries no recipe rules. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
+- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. Individual Web Awesome action, form, layout, navigation, feedback, media, and helper routes provide focused theme specimens without a redundant aggregate route; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges plus a scoped override; the Application tabs composition uses a Web Awesome card with semantic header/footer slots and Kerf `Text` while demonstrating overflow, edge autoscroll, and controlled pointer/keyboard reordering.
 - The ToolbarControlGroup route also demonstrates the public compact/tight,
   mixed-content, filled-selection, nested-dropdown, and avatar/scrim contracts
   added for consumers that previously restyled group descendants. The compact
@@ -42,7 +42,7 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
   paints only the pressed selection, with contain fitting in both cases. Its
   collapsible-search specimen follows the selected group shape with a
   concentric inner radius in both collapsed and expanded states.
-- Recipe ownership notes are hidden by default. A page-toolbar toggle reveals them as floating warning-toned notes with a folded corner, keeping instructional copy visually distinct and removable from the specimen flow.
+- Recipe ownership notes are hidden by default. A page-toolbar toggle reveals each recipe's note as its `CatalogExample` note above the framed specimen, so instructional copy never covers the composition.
 - Settings exercise light/dark, increased contrast, and reduced motion without changing component code. The theme action starts from the operating system's effective color scheme, always names the appearance it will switch to, and installs an explicit light or dark override when activated; contrast and reduced motion expose their independent preferences through `aria-pressed`.
 - 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.