@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/docs/overlay-toast.md

@@ -0,0 +1,62 @@
+# Toasts
+
+`kerfjs/overlay`'s `toast()` shows a brief, auto-dismissing notification in
+one body-level live region. The core ships no CSS. Import
+`@kerfjs/ui/overlay-toast.css` once and every toast takes Kerf's look:
+
+```ts
+import "@kerfjs/ui/overlay-toast.css";
+import { toast } from "kerfjs/overlay";
+
+const exit = { exitClass: "kui-toast-exit", exitDuration: 200 };
+
+toast("Draft saved.", exit);
+toast("Project published.", { ...exit, variant: "success" });
+```
+
+## What the stylesheet does
+
+- **Placement.** The region (`.kerf-toasts`) sits above the bottom edge,
+  centered, 16px from the viewport edge plus the bottom safe area, at most
+  480px wide. It never blocks the page; only the toasts take presses.
+- **Stacking.** Toasts stack newest last with an 8px gap.
+- **Surface.** Each toast (`.kerf-toast`) is the raised surface with a neutral
+  border, the rounded radius, and the large shadow.
+- **Tones.** `variant: 'info' | 'success' | 'warning'` lays the brand,
+  success, or warning quiet fill over the opaque surface, with the matching
+  border and text.
+- **StateBanner content.** A toast whose only content is a `StateBanner` takes
+  the banner's tone, border, and inset, and keeps its own elevation:
+
+  ```tsx
+  toast(
+    () => <StateBanner title="Export Finished" detail="report.csv is ready." tone="success" />,
+    { ...exit, duration: 6000 },
+  );
+  ```
+
+- **Motion.** A new toast rises and fades in on its own (no `enterClass`
+  needed). Pass `exitClass: 'kui-toast-exit'` with `exitDuration: 200` and it
+  sinks and fades out before removal. Under `prefers-reduced-motion` or
+  `:root[data-kui-effects="static"]` it only fades, or not at all.
+- **Forced colors.** Toasts draw a `CanvasText` border on `Canvas`.
+
+## Choices the app owns
+
+- What to say and when: a toast confirms a completed action (saved, copied,
+  published) or reports a status. An error the person must act on, or a
+  decision, belongs in a `StateBanner` in the affected surface or a
+  `DialogSurface`, not a toast that disappears.
+- `duration` (default 4000ms; `0` keeps it until you call `dismiss()`), and
+  `mode: 'replace'` to collapse a rapid sequence to the latest message.
+- Top-edge stacking: pass your own region as `container` with
+  `data-placement="top"` (and the `kerf-toasts` class); it stacks from the top
+  safe area down.
+- Stacking order above other layers: set `--kui-overlay-toast-z-index`
+  (default 1100).
+
+The region is `aria-live="polite"` and each toast is `role="status"`, so a
+screen reader announces it without moving focus. Never make a toast the only
+path to an action.
+
+Use this instead of `wa-toast` and `wa-toast-item`, which are Discouraged.

package/docs/overlay-tooltip.md

@@ -0,0 +1,53 @@
+# Tooltips
+
+`kerfjs/overlay`'s `tooltip(anchor, content, options?)` shows a hover and
+keyboard-focus tooltip beside any element and positions it there. The core
+ships no CSS. Import `@kerfjs/ui/overlay-tooltip.css` once and every tooltip
+takes the help tag's look:
+
+```ts
+import "@kerfjs/ui/overlay-tooltip.css";
+import { tooltip } from "kerfjs/overlay";
+
+const stop = tooltip(
+  deployButton,
+  "Builds the current branch and deploys it to staging.",
+  { exitClass: "kui-tooltip-exit", exitDuration: 100 },
+);
+// Later: stop() removes the listeners and any shown tooltip.
+```
+
+## What the stylesheet does
+
+- **Look.** The `.kerf-tooltip` wrapper takes the loud neutral fill with
+  on-loud text at 14px and a 3px radius: the same look as the help tags that
+  icon-only Kerf controls show.
+- **Width.** It sizes to its text and wraps at 40 characters, staying 8px
+  inside a narrow viewport.
+- **Pointer.** It never takes the pointer, so it cannot block the control
+  beneath it.
+- **Motion.** It fades in on its own (no `enterClass` needed). Pass
+  `exitClass: 'kui-tooltip-exit'` with `exitDuration: 100` and it fades out as
+  it hides. Under `prefers-reduced-motion` or
+  `:root[data-kui-effects="static"]` it appears and leaves at once.
+- **Forced colors.** It draws `CanvasText` on `Canvas`.
+- **Stacking.** Set `--kui-overlay-tooltip-z-index` (default 1200) to change
+  its stacking order. With `native: true` it is in the top layer instead.
+
+Structured content from a render function inherits the tooltip's colors, so
+use plain inline markup (`<strong>`, a line break) rather than components that
+set their own text color.
+
+## When to use it
+
+- A control or value needs a short explanation on hover and focus: a longer
+  description of an action, a chart point, or a truncated label.
+- Not for icon-only Kerf controls: `@kerfjs/ui/help-tags-register` already
+  shows their help tag.
+- Not for interactive content or the only copy of important information. Use an
+  `AnchoredSurface` the person opens, or visible text.
+
+Keep the anchor's accessible name complete without the tooltip; the wrapper is
+`role="tooltip"` and appears on keyboard focus as well as hover.
+
+Use this instead of `wa-tooltip`, which is Discouraged.

package/docs/progress.md

@@ -0,0 +1,62 @@
+# Progress
+
+Two components show progress: `ProgressBar` (`@kerfjs/ui/progress-bar`), a
+linear bar on the native `<progress>` element, and `ProgressRing`
+(`@kerfjs/ui/progress-ring`), a compact circle for a line of text, a row, or a
+toolbar. Both are determinate (`value` of `max`, default `max` 1) or, without a
+`value`, indeterminate.
+
+```tsx
+import { ProgressBar } from "@kerfjs/ui/progress-bar";
+import { ProgressRing } from "@kerfjs/ui/progress-ring";
+
+<ProgressBar
+  id="upload"
+  label="Uploading Files"
+  value={3}
+  max={12}
+  valueText="3 of 12 files"
+  showValue
+/>;
+<ProgressRing label="Claim Time Remaining" value={0.75} valueText="45 minutes left" />;
+```
+
+## ProgressBar
+
+- **Name.** `label` is a visible line above the bar that also names it (with
+  an `id`, through `aria-labelledby`); `ariaLabel` names a bar without one.
+- **Readout.** `showValue` puts the percentage, or `valueText`, at the end of
+  the label row. `valueText` also replaces the spoken percentage.
+- **Indeterminate.** Omit `value` and a band sweeps across the track. It holds
+  still under `prefers-reduced-motion` or the static-effects switch.
+- **Tone and size.** `tone` is `brand` (default), `success`, `warning`, or
+  `danger`; `size="compact"` is a 4px track for a row or table cell (default
+  6px).
+
+The bar takes the full available width and the shared block-content inset (a
+transparent 1px border and 8px padding), so its label sits on the same text
+column as `Text`.
+
+## ProgressRing
+
+- **Name.** `label` is required: the ring is `role="progressbar"` with
+  `aria-valuenow` as a percentage, or `valueText`.
+- **Size.** `small` (16px) for a line of text, `medium` (24px, the default)
+  beside an icon in a row or toolbar, `large` (40px) on its own. Its box is
+  exactly its diameter, so it aligns with icons of the same size.
+- **Indeterminate.** Omit `value` and it spins a quarter arc, which holds still
+  under reduced motion.
+- **Tone.** The same tones as the bar.
+
+## Choosing
+
+- A measurable task with room for a label row: `ProgressBar`.
+- Compact progress beside an item: `ProgressRing`.
+- A brief busy glyph inside a control: `LoadingSpinner`.
+- App-wide progress with no home beside the work: `CornerStatus` or
+  `EdgeActivityIndicator`.
+- A reading on a scale that is not progress (a rating, a level): a native
+  `<meter>`.
+
+Forced colors draw the fills in `Highlight`. Use these instead of
+`wa-progress-bar` and `wa-progress-ring`, which are Discouraged.

package/docs/recipes.md

@@ -1,62 +1,75 @@
 # 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
 controller at one stable application root, uses `delegateActions()` for recipe
-commands, forwards form and dialog lifecycle events, wires resize commits with
-the public `onCommit` callback, retains every disposer, and returns one
-idempotent disposer:
+commands, forwards form and dialog lifecycle events, runs the recipe's own
+`wire()` (for example `wireWorkbench` or `wireSidebar`), retains every
+disposer, and returns one idempotent disposer:
 
 ```ts
-import { createRecipe } from './navigation-sidebar.js';
-import { mountRecipe } from './mount-recipe.js';
+import { createRecipe } from "./navigation-sidebar.js";
+import { mountRecipe } from "./mount-recipe.js";
 
-const root = document.querySelector<HTMLElement>('#navigation')!;
+const root = document.querySelector<HTMLElement>("#navigation")!;
 const stopRecipe = mountRecipe(root, createRecipe(announce));
-window.addEventListener('pagehide', stopRecipe, { once: true });
+window.addEventListener("pagehide", stopRecipe, { once: true });
 ```
 
 The adapter is delivered as reference source, not a new package runtime export.
 `delegate()` remains a valid alternative when an application needs selector-
 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.
-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.
-Collapse the pane completely rather than preserving an empty icon rail.
-Adapt only public `--kui-layout-*` and component variables.
-
-## Navigation sidebar
+## Desktop Application Shell
+
+[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 `Workbench`
+(`@kerfjs/ui/workbench`): resizable navigation and inspector rails around the
+task list. Each rail composes its own panel toolbar — a default-size title and
+the standard hide toggle — and the work area's `mainToolbar` carries the xl
+view title. While a rail is hidden, `Workbench` relocates its show toggle into
+the work-area toolbar on the same logical edge (leading for the navigation
+rail, trailing for the inspector), and `wireWorkbench` hands focus between the
+two positions. Collapse a rail completely rather than preserving an empty icon
+rail. Only the three real panes own a `.kui-pane__content` scroll owner; no
+frame `Pane` wraps the layout in a scroll owner that never scrolls, and the
+app-bar `Toolbar` claims the top edge and both sides with its own
+`safeAreaEdges`.
+
+On a narrow container the rails overlay the task list one at a time instead of
+squeezing it, leaving a 44px strip on the far side that dismisses the overlay
+(`responsiveOverlayAt`, on by default; `compactOverlay: 'full'` covers the
+whole width). The app owns each rail's collapsed and size signals — which
+`wireWorkbench` keeps in sync with resizing and overlay dismissal — plus
+routing, persistence, and data. Adapt only public `--kui-layout-*` and
+component variables.
+
+## Navigation Sidebar
 
 [Open the recipe](../ux-demo/?component=recipe-navigation-sidebar) · [TSX source](../ux-demo/recipes/navigation-sidebar.tsx)
 
 One unpadded `.kui-pane` owns toolbar/content/footer structure. Its
-`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and other
-`.kui-content-item` children own their 8px margin, 1px border, and 8px padding.
+`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and
+`ContentItem` children own their 8px margin, 1px border, and 8px padding.
 Rows and footer toolbar groups remain 44px tall. The app owns routes,
 permissions, labels, selection, valid section counts and their localized
 `countLabel` phrases, non-count badge content, disclosure state, and revealed
 content. A toggled `ListHeader` supplies the production `DisclosureArrow` when
 no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
 
-## Workspace header
+## Workspace Header
 
 [Open the recipe](../ux-demo/?component=recipe-workspace-header) · [TSX source](../ux-demo/recipes/workspace-header.tsx)
 
-`PanelHeader` owns the page heading while one control cluster holds secondary,
+The page heading is a direct `Toolbar`/`ToolbarText` composition while one control cluster holds secondary,
 overflow, and primary actions. The app owns authorization and command policy;
 controls relocate without changing focus order.
 
@@ -64,34 +77,42 @@ 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.
-`PanelHeader`, `ListHeader`, `ListItem`, and `ValueTable` own their included
-anatomy. The application owns open state, selection, dismissal policy, and
-record actions. `PanelHeader` places the trailing controls the app passes
-directly into its 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.
-
-## Composer form
+The recipe renders `ListDetailDialog` (`@kerfjs/ui/list-detail-dialog`). On
+roomy devices the list and the detail are full-height columns, each a `Pane`
+with its own top `Toolbar`, so the divider runs the dialog's full height. The
+list column's toolbar carries its quiet default-size title; the detail
+column's toolbar carries the dialog's primary extra-large title and the close
+control, and its pinned footer carries the record actions. The surface draws
+no header of its own, and its label still names the modal. Its explicit 16px
+`viewportGutter` bounds the roomy modal to the dynamic viewport. On compact
+devices the same component fills the screen and becomes a `NavStack`
+drill-down whose back control the application pops; every view keeps the
+close control and the detail keeps its pinned actions. The application owns
+open state, selection, the pushed detail, dismissal policy, and record
+actions. Do not compose `DialogSurface` around a `SplitView` by hand for this
+layout: the surface header would span both columns and stop the divider below
+it. See [ListDetailDialog](./list-detail-dialog.md).
+
+## Composer Form
 
 [Open the recipe](../ux-demo/?component=recipe-composer-form) · [TSX source](../ux-demo/recipes/composer-form.tsx)
 
-`PanelHeader` supplies the task title and summary, with their ids referenced
-by the form. 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
+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. 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
 resets synchronize both those properties and the rendered value attributes;
 the Reset action also announces `Draft reset` through the catalog live region.
 
-## List workspace states
+## List Workspace States
 
 [Open the recipe](../ux-demo/?component=recipe-list-workspace-states) · [TSX source](../ux-demo/recipes/list-workspace-states.tsx)
 
@@ -100,58 +121,103 @@ populated, stale/background refresh, and error/retry states. The recipe owns
 feedback placement; the app owns fetching, cache age, retry policy, and domain
 rows.
 
-## Compact toolbar choices and actions
+## Compact Toolbar Choices and Actions
 
 [Open the recipe](../ux-demo/?component=recipe-compact-toolbar) · [TSX source](../ux-demo/recipes/compact-toolbar.tsx)
 
 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. The app owns values, actions, persistence,
-and responsive priority.
+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. 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
+## Navigation Stack
 
 [Open the recipe](../ux-demo/?component=recipe-navigation-stack) · [TSX source](../ux-demo/recipes/navigation-stack.tsx)
 
 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`.
+`Workbench`, and `TabNavigator`.
 
-## Loading inspector
+## Loading Inspector
 
 [Open the recipe](../ux-demo/?component=recipe-loading-inspector) · [TSX source](../ux-demo/recipes/loading-inspector.tsx)
 
 A record inspector whose per-record values load asynchronously. Every
-value-bearing component (`PanelHeader`, `ValueTable`/`ValueTableRow`, `Select`,
+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
+## Collapsible Sidebar
 
 [Open the recipe](../ux-demo/?component=recipe-collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx)
 
 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
+`wireSidebar` (`@kerfjs/ui/wire-sidebar`). Each panel takes a `toolbar` — a
+title plus the standard per-side toggle — so the hide control lives in the
+panel's own header, and `CollapsiblePanelRelocated` renders the matching show
+control only while the panel is collapsed, so exactly one control owns each
+action and a collapsed panel is still reachable. The rail's relocated toggle
+leads the always-visible main header; the drawer's sits in a
+`FloatingToolbar` passed as the drawer's own `restoreControl`, which the panel
+floats in its column's safe-area-aware bottom-end corner, next to where the
+drawer opens — do not hand-roll a conditional floating control beside the
+panel. `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`.
 
+## Media Detail
+
+[Open the recipe](../ux-demo/?component=recipe-media-detail) · [TSX source](../ux-demo/recipes/media-detail.tsx)
+
+An Apple-Music-style album page composed only from components. A `NavStack`
+with `chromePresentation="clear"` and `scrollEdge="material"` lays its bar
+over the album, fully transparent at rest; its back control and the album
+actions are glass control groups (`ToolbarControlGroup material="glass"`), so
+they stay legible over the artwork, and the chrome material fades in once the
+songs scroll beneath the bar. The stack takes a scoped `tint` from the
+artwork's bottom color with `scheme: 'dark'`, so the surface, text, quiet
+text, and the chrome material all re-derive from it at AA. The album view's
+Pane opens with a `BackdropImage` that runs `underChrome` up beneath the clear
+bar, lags the scroll (`parallax="subtle"`), blurs progressively as it scrolls
+away, and fades into the tinted surface (`fadeTo={uiColor('surface')}`) that
+continues under the song list. Every effect has the components' own
+fallbacks: static under reduced motion, the static-effects switch, or without
+scroll-driven animations; opaque under reduced transparency and increased
+contrast; system colors in forced colors. The app owns the artwork and the
+two colors it already knows about it (the tint and its scheme), the stack,
+playback, and the data; the recipe's `wire` installs `wireScrollDividers` for
+the scroll-edge state. See [`app-layouts.md`](app-layouts.md) for the layout
+and [`backdrop-image.md`](backdrop-image.md) for the image.
+
 ## Rules shared by every recipe
 
 - Import `@kerfjs/ui/layout.css`; keep every pane unpadded and use exactly one
@@ -159,9 +225,17 @@ 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-control-cluster`, …) and themed Web Awesome classes — a content item is
+  a `ContentItem`, not a hand-written `.kui-content-item`; it configures
+  components through props, `rootAttributes`, and tokens. When a recipe needs a
+  capability no component offers, record it as a component gap rather than
+  papering over it with CSS. `npm run check:recipes` enforces these rules on
+  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/slider.md

@@ -0,0 +1,64 @@
+# Slider
+
+`@kerfjs/ui/slider` picks a value on a range. It is a native
+`<input type="range">` drawn as a track, a brand fill up to the value, and a
+round thumb, identically in Chromium, Firefox, and WebKit.
+
+```tsx
+import { Slider } from "@kerfjs/ui/slider";
+import { wireSliders } from "@kerfjs/ui/wire-sliders";
+
+<Slider
+  id="volume"
+  label="Volume"
+  value={volume.value}
+  showValue
+  unit="%"
+  hint="Applies to every output device."
+  action="set-volume"
+/>;
+
+const stop = wireSliders(root);
+```
+
+## Props
+
+- `id` (required) identifies the input and derives the readout, hint, and
+  tick ids.
+- `min` (default 0), `max` (default 100), `step` (default 1), and `value`
+  (default the midpoint, snapped to `step`; clamped to the range).
+- `label` names it in a row above the track; `ariaLabel` names one without a
+  visible label.
+- `showValue` adds the current value at the end of the label row, followed by
+  `unit` (such as `%`). With a `unit`, the spoken value includes it too.
+- `ticks` labels stops under the track (`{ value, label? }`). The labels are
+  visual; the input still reports its value.
+- `hint` is supporting text below it and its accessible description.
+- `size="compact"` is a 3px track, a 16px thumb, and 14px text; `disabled`
+  dims it.
+- `orientation="vertical"` stands it up, minimum at the bottom, `length`
+  tall (default 160px), with the label row above and the fill running upward.
+  A vertical Slider takes no `ticks`. Arrow keys still step it.
+- `action` puts a `data-action` on the input. Listen for `input` (live) or
+  `change` (committed) and store the value the app re-renders with.
+
+## Live readout
+
+The fill and the readout come from the rendered value. Call
+`wireSliders(root)` once above your Sliders: one delegated `input` listener
+keeps the fill, the readout, and the spoken value text in step with a drag
+before the app re-renders. `syncSlider(input)` recomputes one by hand.
+
+## Geometry and accessibility
+
+A horizontal Slider fills the available width (a vertical one is as wide as
+its label row) with the shared block-content inset (a
+transparent 1px border and 8px padding), so its label sits on the same text
+column as `Text`. Keyboard and screen-reader behavior are the platform's:
+arrow keys, Page Up and Down, Home, and End step it. The readout is hidden
+from assistive technology because the input already reports its value.
+Forced colors draw a `Highlight` fill on a `GrayText` track.
+
+Use a numeric `TextField` when the exact number matters, a `Switch` for on or
+off, and a `SegmentedControl` for a few named options. Use this instead of
+`wa-slider`, which is Discouraged.