@kerfjs/ui 5.0.0-beta.100 → 5.0.0-beta.101

package/docs/layout.md

@@ -106,6 +106,83 @@ The color uses `--kui-sunken-panel-background`, falling back to
 in a nested layout so a translucent override paints once. The public color
 override may be set at a Pane or layout boundary.
 
+### Background colors
+
+Set `background` when a pane needs a surface color of its own, such as a
+media detail page painted in its artwork's color. It takes a typed color from
+`@kerfjs/ui/css-values`: `uiColor('surface-raised')` for a theme token,
+`fillColor('#1f2a44')` for an app-chosen literal, or `colorVar('--app-hue')`
+for an app-owned custom property. The color paints the whole pane, header and
+footer included, and replaces the appearance's fill: a sunken pane with a
+background drops its lowered color and grain. Omitted, the pane keeps its
+default.
+
+```tsx
+import { fillColor } from "@kerfjs/ui/css-values";
+
+<Pane background={fillColor("#1f2a44")} header={<AlbumToolbar />}>
+  <AlbumTracks />
+</Pane>;
+```
+
+`PaneConfig.background` forwards like `appearance`, so a Workbench `mainPane`
+or panel `pane`, a CollapsiblePanel `pane`, or a `NavStackView` `pane` takes
+it. `NavStack` and `TabNavigator` take their own `background` for the stack
+or navigator surface and their docked bars, and a `TabNavigatorTab` takes one
+for its scene. Overlay chrome keeps the translucent chrome material over any
+of them.
+
+The app owns contrast: keep text at AA over the color you choose. A dark
+color needs dark-tone controls or a scoped tint for its content. In forced
+colors every background paints `Canvas`.
+
+### Tinted surfaces
+
+Set `tint` when a whole region should take on a color, the way a media detail
+page takes on its artwork's color: `tint={{ color, scheme }}`. `color` is a
+`@kerfjs/ui/css-values` color, usually one the app already knows about its
+artwork, and `scheme` says whether that color reads as a `'light'` or a
+`'dark'` surface. Kerf does no color detection; the app declares the scheme.
+
+```tsx
+import { fillColor } from "@kerfjs/ui/css-values";
+
+<Pane tint={{ color: fillColor(album.bottomColor), scheme: "dark" }} header={<AlbumToolbar />}>
+  <AlbumTracks />
+</Pane>;
+```
+
+The pane paints its tinted surface, and everything inside it re-derives from
+the color: the surface and raised surface, normal and quiet text, link and
+brand text, and everything built on them (quiet fills, the lowered surface,
+the chrome material behind overlay headers, popup rows). Each token's
+lightness is clamped into a band that keeps text at WCAG AA over any color: a
+light tint's surface stays at or above 90% OKLCH lightness under dark text,
+and a dark tint's surface at or below 30% under light text. Chroma is capped,
+so text stays near-neutral and the surface reads as a tint of the color. A
+seed sweep across hue and lightness holds every text token at 4.5:1 or better
+over the surface, raised surface, and quiet fills, with and without the Web
+Awesome theme (`tests/browser/tone-contrast.spec.ts`).
+
+The scope also takes the declared `color-scheme` and the Web Awesome
+`wa-light` / `wa-dark` class, so Web Awesome components inside it re-derive
+their own fills. Without relative color syntax, and under
+`prefers-contrast: more`, the scope keeps the plain palette in its declared
+scheme. `tint` and `background` combine: `background` paints the pane, and
+`tint` still re-derives the tokens for its content.
+
+Add `accent` (usually the artwork's most vivid color) to re-derive the brand
+ramp too: `tint={{ color, scheme, accent }}`. Loud fills (primary buttons, the
+current popup row, checked controls) and their text, brand text and links,
+text on brand fills, and the focus ring all take the accent's hue. Lightness
+is clamped so each pair keeps AA for any accent: in a light scope the fill
+stays at or below 50% OKLCH lightness under white text and brand text at most
+45%; in a dark scope the fill stays between 72% and 85% under near-black text
+and brand text at least 80%.
+
+`PaneConfig.tint` forwards like `background`. `NavStack`, `TabNavigator`, and
+each `TabNavigatorTab` take `tint` for the stack, the navigator, or one scene.
+
 Pass any combination of logical sides to `separators`: `block-start`,
 `block-end`, `inline-start`, and `inline-end`. Every line is off by default and
 each enabled side uses `--kui-pane-separator-width` (1px) and
@@ -205,8 +282,10 @@ The header paints the shared chrome material, `--kui-chrome-material` (the
 surface at 80% opacity) behind `--kui-chrome-material-filter` (a blur and
 saturation backdrop filter), so content passing beneath it reads as softened
 color, not as competing text. The material becomes the opaque surface under
-`prefers-reduced-transparency: reduce` or `prefers-contrast: more`, and where
-the browser lacks `backdrop-filter`. In forced colors the header paints
+`prefers-reduced-transparency: reduce` or `prefers-contrast: more`, where
+the browser lacks `backdrop-filter`, on a slow-updating display
+(`update: slow`), and when the app sets `data-kui-effects="static"` on the
+root element (see [Chrome material](accessibility.md#chrome-material)). In forced colors the header paints
 `Canvas` with a `CanvasText` bottom edge.
 
 `wireScrollDividers` measures each overlay header (its border-box height,
@@ -268,6 +347,54 @@ inline gutter instead of nesting them inside another padded content item. A
 conditional `StateBanner` remains visibly distinct because it communicates
 semantic status.
 
+### Clear header
+
+`headerPresentation="clear"` is an overlay header with no fill: the same
+measuring, placement, and scroll clearance as `overlay`, but fully
+transparent, for a header laid over imagery such as a `BackdropImage` hero.
+The header is not what keeps its controls legible over the image: put them
+in glass control groups (`ToolbarControlGroup material="glass"`), or give the
+content a scrim. A clear header draws no scroll divider. Set `underChrome` on a
+`BackdropImage` that opens the content to run its artwork up beneath the
+header.
+
+A clear header stays clear while content scrolls beneath it. To fade a
+backing in gradually instead, the scroll-edge effect of iOS, set
+`scrollEdge="material"` (the translucent chrome material) or
+`scrollEdge="surface"` (the opaque surface). The backing tracks the scroll:
+it is fully clear at rest and fully in once content has scrolled
+`scrollEdgeDistance` pixels beneath the header (default 60), and out again as
+you return to the top. Only its opacity changes; the blur itself never
+animates. `wireScrollDividers` publishes the progress
+(`--kui-scroll-edge-progress`, 0 to 1) from the scroll it already tracks, so
+it works in every engine with no extra wiring; unwired, the header stays
+clear.
+
+```tsx
+<Pane
+  label="Album"
+  headerPresentation="clear"
+  scrollEdge="material"
+  header={<Toolbar label="Album" leading={<BackGroup />} trailing={<AlbumActions />} />}
+>
+  <BackdropImage src={art} alt="" fadeTo={uiColor("surface")} underChrome>
+    <Tracks />
+  </BackdropImage>
+</Pane>
+```
+
+Clear chrome turns opaque where transparency would hurt: under
+`prefers-reduced-transparency: reduce` or `prefers-contrast: more` it paints
+the opaque material, and in forced colors it paints `Canvas` with a
+`CanvasText` edge. Under the static-effects switch or on a slow-updating
+display, the scroll edge snaps on while content lies beneath the bar instead
+of tracking the scroll.
+`NavStack` (`chromePresentation`, `bottomToolbarPresentation`) and
+`TabNavigator` (`barPresentation`) take the same `clear` value and
+`scrollEdge` and `scrollEdgeDistance` props; a bottom bar fades its backing
+out over the last `scrollEdgeDistance` pixels, clearing once the content
+reaches its end.
+
 ## Content items
 
 Render an ordinary surface-like `.kui-content` child with `ContentItem` from
@@ -498,9 +625,12 @@ do not create line spacing.
 `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. Set `tone="dark"` on a loud or photo-backed
-toolbar surface to use `--kui-color-neutral-on-loud` at every size, matching
-dark control groups. Default tone keeps existing identity and heading colors. A subsection title is
+content and controls around it. Set `tone="dark"` on a loud-filled toolbar
+surface (the inverse `--kui-color-neutral-fill-loud`) to use
+`--kui-color-neutral-on-loud` at every size, matching dark control groups; it
+inverts with the color scheme. Over a dark photo or scrim keep the default
+tone inside a `BackdropImage` overlay, which takes the dark scheme under its
+`scrim`. Default tone keeps existing identity and heading colors. 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

package/docs/manual-test-plan.md

@@ -0,0 +1,29 @@
+# Manual test plan
+
+Checks that automation cannot make truthfully. Run the catalog with
+`npm run dev:lan` and open the printed URL on the device (see
+[`ux-demo.md`](ux-demo.md)). Record the device, OS, and browser versions and the
+result on the tracking ticket.
+
+## DialogSurface bottom sheet: virtual keyboard and safe areas
+
+Route: `?component=surface-scaffold`, example "Resizable Bottom Sheet". Run on
+an iPhone (Safari) and an Android phone (Chrome).
+
+1. Open the sheet and focus the Message field. The keyboard pushes the sheet's
+   content above it, and the panel runs behind the keyboard with no gap.
+2. Rotate the phone, and pinch-zoom while the keyboard is open. The content
+   stays clear of the keyboard; while zoomed, the measured overlap is 0 and the
+   page relies on `dvh`.
+3. Dismiss the keyboard. The bottom padding returns to the home-indicator safe
+   area, and the sheet's square bottom edge meets the screen edge.
+4. Drag the grabber, with and without the keyboard open. The sheet resizes
+   between its minimum height and the screen less the top safe area.
+
+Playwright cannot raise a virtual keyboard; the overlap formula is unit-tested
+(`tests/unit/dialog-bottom-sheet.test.ts`) and a simulated keyboard is covered
+in `tests/browser/dialog-bottom-sheet.spec.ts`.
+
+## Automated coverage summary
+
+Nothing has moved from this plan into automation yet.

package/docs/nav-stack.md

@@ -150,7 +150,11 @@ focusable descendant, and finally the view container itself. Use
 `data-nav-focus` for a heading or primary control when DOM order is not the best
 initial reading position; it may use `tabindex="-1"` for programmatic focus.
 When a remembered control was removed during the controlled rerender, the same
-fallback order applies. Disposing the helper stops future transitions and
+fallback order applies. While focus rests on the view container itself (it
+had nothing focusable, such as an inert loading placeholder), a later
+re-render that morphs away the temporary `tabindex` keeps it there, and once
+content with a focus target arrives under the same key, focus moves to it;
+focus the person moved elsewhere is never reclaimed. Disposing the helper stops future transitions and
 cleans up any temporary fallback `tabindex` it added.
 
 ## Separators and scroll dividers
@@ -187,6 +191,23 @@ top Toolbar's own `dividerSides`.
 <NavStack id="settings" label="Settings" views={views.value} chromeDividers="always" />
 ```
 
+## Background colors
+
+`background` paints the stack, its docked chrome and bottom toolbar, and every
+view in an app-chosen color from `@kerfjs/ui/css-values` instead of the
+surface. One view's own color goes in its `pane: { background }`, which paints
+over the stack's. Overlay chrome keeps the chrome material. The app keeps text
+at AA over the color; forced colors paint `Canvas`. See
+[Background colors](layout.md#background-colors).
+
+```tsx
+<NavStack id="music" label="Music" views={views.value} background={uiColor("surface-raised")} />
+```
+
+`tint={{ color, scheme }}` re-derives the stack's surface and text tokens from
+an app color instead, so its chrome, views, and content all take on the color
+with text kept at AA. See [Tinted surfaces](layout.md#tinted-surfaces).
+
 ## Overlay chrome
 
 `chromePresentation="overlay"` lays the top chrome over the active view's top
@@ -296,6 +317,21 @@ edge.
 `SplitView`'s `compactStack.bottomToolbarPresentation` and a Workbench
 navigation panel's `navStack.bottomToolbarPresentation` forward it too.
 
+### Clear chrome
+
+`chromePresentation="clear"` and `bottomToolbarPresentation="clear"` lay the
+bars over the active view like `overlay`, with the same measuring and edge
+insets, but fully transparent, for chrome over imagery. Keep their controls
+in glass control groups (`ToolbarControlGroup material="glass"`); the stack's
+own back control is one automatically under clear chrome. They stay
+clear while content scrolls beneath them; with `scrollEdge="material"` (or
+`"surface"`) a backing fades in gradually, opacity only, over
+`scrollEdgeDistance` pixels of scroll (default 60): behind the top chrome as
+the view's content scrolls beneath it, and behind the bottom toolbar until
+the content nears its end. Clear bars draw no scroll
+divider, turn opaque under reduced transparency or increased contrast, and
+paint `Canvas` in forced colors. See [Clear header](layout.md#clear-header).
+
 ## Safe areas
 
 The stack paints through a device's unsafe areas. Its chrome pads for the top

package/docs/recipes.md

@@ -200,6 +200,30 @@ ephemeral interaction. For a full three-pane shell use `Workbench` instead — s
 [`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

package/docs/surface-scaffold.md

@@ -8,10 +8,17 @@ inside `PopupSurface` also keeps keyboard item navigation made during its show
 animation when Web Awesome completes its initial focus handoff.
 
 Wrap one `wa-dialog` with `DialogSurface`. Choose `size` (`small`, `medium`, or
-`large`), `presentation` (`modal`, `side-sheet`, or `fullscreen`), and independent
+`large`), `presentation` (`modal`, `side-sheet`, `fullscreen`, or
+`bottom-sheet`; see [Bottom sheets](#bottom-sheets)), and independent
 `bodyInset` / `footerInset` (`none`, `compact`, or `comfortable`). The defaults
 match Kerf's medium modal, 8px body, and 16px footer rhythm.
 
+The panel corner is concentric with a pill `ToolbarControlGroup` (22px) resting
+at the body inset: 30px for `compact` (and `none`) and 38px for `comfortable`,
+so header and body controls nest into the curve. A side sheet uses the same
+radius on its leading corners, and a bare `wa-dialog` or `PopoverDialogSurface`
+takes the 30px default.
+
 The modal size presets have preferred widths of 400px, 560px, and 800px,
 respectively, before the viewport width cap. Set `preferredWidth` to a branded
 `CssLength` when the desktop shell needs another width. It takes precedence over
@@ -46,7 +53,8 @@ clamped to the dynamic viewport height minus twice the gutter (16px per edge
 when the gutter is omitted). Negative gutters/caps clamp to zero. Omitting
 both options preserves Web Awesome's existing width and phone height caps.
 These options apply only to `presentation="modal"`; side sheets and fullscreen
-surfaces keep their own geometry.
+surfaces keep their own geometry, and a bottom sheet reads `height` and
+`maxHeight` as described in [Bottom sheets](#bottom-sheets).
 
 ```tsx
 import '@kerfjs/ui/surface-scaffold/register';
@@ -74,6 +82,144 @@ An application can configure device-class breakpoints when its phone policy
 differs from the default. Prefer a typed cap such as `maxHeight={remify(640)}`
 when the modal should stop growing before the viewport bound.
 
+### Bottom sheets
+
+`presentation="bottom-sheet"` attaches the dialog to the bottom edge of the
+screen instead of centering it, the way a phone presents a compose or quick
+edit sheet. The default `modal` presentation is unchanged.
+
+- **Geometry.** The panel rests on the viewport's block-end edge. Its top
+  corners keep the dialog radius and its bottom corners are square. It is
+  full width on a phone and the `size` / `preferredWidth` width, centered, on
+  a wider screen.
+- **Safe area and keyboard.** The panel runs to the edge, behind the home
+  indicator and any virtual keyboard, while a block-end padding keeps its
+  content above them. The padding is the largest of
+  `--kui-safe-area-block-end`, the keyboard overlap the register measures from
+  `visualViewport` (layout height minus the visual viewport's height and top
+  offset, ignored while pinch-zoomed), and the VirtualKeyboard API's
+  `env(keyboard-inset-height)`. A page whose viewport meta sets
+  `interactive-widget=resizes-content` shrinks the layout viewport instead, so
+  the measured overlap is zero and the sheet simply follows the dynamic
+  viewport. Kerf never sets `navigator.virtualKeyboard.overlaysContent`; an
+  application that opts into it gets the `env()` value for free.
+- **Height.** `height`, `minHeight`, and `maxHeight` measure the visible
+  content height above that clearance. `height` is the opening height
+  (omit it to size to content), and `maxHeight` caps it. The panel never
+  exceeds the dynamic viewport minus the top safe area and one
+  `viewportGutter` (16px by default), so a tall keyboard shrinks the content
+  rather than pushing the sheet off the top.
+- **Resizing.** `resizable` adds a grabber at the top edge: a focusable
+  horizontal `separator` named "Resize sheet" with `aria-valuemin`,
+  `aria-valuenow`, and `aria-valuemax` in visible px. Drag it, or use the
+  arrow keys (16px), Page Up/Down (64px), Home (`minHeight`, default 160px),
+  and End (the cap). The register injects the grabber into the dialog's
+  shadow panel, so it never disturbs `bodyLayout` children or a Kerf morph.
+  Each opening starts again at `height`.
+- **Motion.** The sheet slides up from the bottom edge when it opens and back
+  down when it is dismissed. `enterMotion="standard"` or
+  `exitMotion="standard"` keeps Web Awesome's scale-and-fade for that
+  transition. The slide falls back to Web Awesome's motion under
+  `prefers-reduced-motion: reduce` and the document's static effects mode
+  (`:root[data-kui-effects="static"]`). A prevented close still pulses.
+
+```tsx
+import '@kerfjs/ui/surface-scaffold/register';
+import { remify } from '@kerfjs/ui/css-values';
+import { DialogSurface } from '@kerfjs/ui/surface-scaffold';
+
+<DialogSurface presentation="bottom-sheet" height={remify(360)} minHeight={remify(200)} resizable bodyInset="none">
+  <wa-dialog label="New Message" light-dismiss>
+    {/* Application-owned fields */}
+  </wa-dialog>
+</DialogSurface>;
+```
+
+The resize grabber, keyboard clearance, and slide need the `/register`
+entry. Without it the sheet keeps its bottom-edge geometry and safe-area
+padding, shows no grabber, and opens with Web Awesome's own animation.
+`preferredWidth`, `bodyLayout`, the floating header and footer, and the
+insets compose with a bottom sheet as they do with a modal.
+
+### Core dialogs as bottom sheets
+
+The core `kerfjs/overlay` surfaces (`overlay()` and the `confirm`, `prompt`,
+`form`, and `choice` promise dialogs) take `presentation: 'bottom-sheet'`, but
+the core ships no CSS. Import `@kerfjs/ui/overlay-sheet.css` once to give
+them this package's bottom-sheet geometry:
+
+- the bottom edge, full width up to 560px and centered beyond;
+- square bottom corners under the dialog radius;
+- the 8px surface inset, padded at the block end by the larger of the safe
+  area and the `--kerf-keyboard-inset` the core publishes;
+- a cap below the top safe area;
+- a slide up as it opens.
+
+Pass `exitClass: 'kui-overlay-sheet-exit'` (with an `exitDuration` cap such as
+`400`) to slide it back down as it closes. The stylesheet covers the plain
+host and `native: true`, honors reduced motion and the static-effects switch,
+and paints `Canvas` in forced colors.
+
+The core renders bare default markup, so compose the content from components
+through the dialog's `render` slot and spread the wiring slots onto native
+buttons:
+
+```tsx
+import "@kerfjs/ui/overlay-sheet.css";
+
+confirm("Discard this draft?", {
+  presentation: "bottom-sheet",
+  exitClass: "kui-overlay-sheet-exit",
+  exitDuration: 400,
+  render: ({ message, ok, cancel }) => (
+    <List gap="xs">
+      <Toolbar label="Discard Draft" leading={<ToolbarText text="Discard Draft" size="xlarge" headingLevel={2} />} />
+      <ListInsetText>{message}</ListInsetText>
+      <Row hAlign="right" controlInsets="rl">
+        <ToolbarControlGroup label="Discard Draft Actions" content="text">
+          <button type="button" {...cancel}>Keep Editing</button>
+          <button type="button" {...ok}>Discard</button>
+        </ToolbarControlGroup>
+      </Row>
+    </List>
+  ),
+});
+```
+
+The wired controls can be native buttons, as here, or Web Awesome buttons.
+With kerfjs 5.0 or later, the core holds focus on the sheet until a Web
+Awesome OK button has rendered, then moves focus to it. On kerfjs 4.x, use
+native buttons for the wired controls: the core's first focus reaches a Web
+Awesome button before it has rendered and aborts the open.
+
+A core sheet can also be resizable, like a `resizable` `DialogSurface` sheet.
+Add the `kui-overlay-sheet-resizable` class next to the default wrapper class,
+and call `wireOverlaySheets()` from `@kerfjs/ui/wire-overlay-sheets` once for
+each container sheets open in (`document.body`, the core's default):
+
+```tsx
+import "@kerfjs/ui/overlay-sheet.css";
+import { wireOverlaySheets } from "@kerfjs/ui/wire-overlay-sheets";
+
+const stopSheets = wireOverlaySheets();
+
+overlay(<UpNext />, {
+  className: "kerf-overlay kui-overlay-sheet-resizable",
+  presentation: "bottom-sheet",
+});
+```
+
+Each such sheet gets the same grabber at its top edge: a `role="separator"`
+that resizes the visible height by drag, the arrow keys (16px), Page Up/Down
+(64px), Home (the minimum), and End (the cap), and reports that height as its
+ARIA values. The minimum is `--kui-overlay-sheet-min-height` (160px). The
+sheet opens at its content height every time. The grabber sticks to the top
+edge while the content scrolls, and stays the sheet's first child (and first
+tab stop) across re-renders of the overlay's content. Compose the sheet's
+content root as a block or column, since the grabber is its first child. The
+wiring watches only the container's direct children, which is where the core
+appends each overlay; call the disposer to remove every grabber.
+
 ### Filling the dialog
 
 `maxHeight` caps a modal that sizes to its content. A layout that fills the
@@ -267,4 +413,4 @@ preserve `data-morph-skip-children` when its upgraded light-DOM items must retai
 identity across Kerf rerenders. Import `@kerfjs/ui/popup-menu/register` once for
 the focus handoff fix when wrapping a raw `wa-dropdown`.
 
-Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog`, measures each surface's footer for a floating footer's body clearance, draws a floating header's divider while content is scrolled beneath it, and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
+Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog`, measures each surface's footer for a floating footer's body clearance, draws a floating header's divider while content is scrolled beneath it, wires a bottom sheet's resize grabber, keyboard clearance, and slide, and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.

package/docs/tab-navigator.md

@@ -169,6 +169,30 @@ so it never moves the bar or a tab.
 the wiring reports content below. It does not suppress the sunken-surface
 separator; use `separator="hidden"` for that.
 
+## Background colors
+
+`background` paints the navigator and its docked bar in an app-chosen color
+from `@kerfjs/ui/css-values` (`uiColor(...)`, `fillColor(...)`, or
+`colorVar(...)`) instead of the surface. A tab's own `background` paints its
+scene and replaces that scene's `appearance`. The overlay bar keeps the
+chrome material over either. Keep the bar's labels and the scene's text at AA
+over the colors you choose; forced colors paint `Canvas`. See
+[Background colors](layout.md#background-colors).
+
+```tsx
+<TabNavigator
+  id="library"
+  label="Library"
+  active={active.value}
+  background={uiColor("surface-raised")}
+  tabs={[{ id: "now", label: "Now Playing", content: <NowPlaying />, background: fillColor("#2b1d3a") }]}
+/>
+```
+
+`tint={{ color, scheme }}` on the navigator, or on one tab for its scene,
+re-derives the surface and text tokens from an app color, keeping text at AA.
+See [Tinted surfaces](layout.md#tinted-surfaces).
+
 ## Translucent bar
 
 `barPresentation="overlay"` lays the tab bar over the active scene's bottom
@@ -206,6 +230,18 @@ shows only while more content lies below. Like the NavStack overlay bars, the
 tab bar ends where a classic (space-taking) scrollbar's track begins, so the
 active scene's thumb and buttons stay visible and usable.
 
+### Clear bar
+
+`barPresentation="clear"` lays the bar over the active scene like `overlay`
+but fully transparent, for a bar over imagery. It stays
+clear while content scrolls beneath it; with `scrollEdge="material"` (or
+`"surface"`) a backing fades in (opacity only) while the scene continues
+beneath the bar and fades out over the last `scrollEdgeDistance` pixels
+(default 60) before its end. A clear bar draws
+no scroll divider, turns opaque under reduced transparency or increased
+contrast, and paints `Canvas` in forced colors. See
+[Clear header](layout.md#clear-header).
+
 ## Tab badges
 
 Give a tab a `badge` (a count or short string such as `3`, `"99+"`, or

package/docs/ux-demo.md

@@ -1,6 +1,16 @@
 # UX catalog contract
 
-Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server reloads component source edits without a restart: component entries still load through their `dist/browser` wrappers, so each component's reachable CSS is exercised as consumers receive it, but the JavaScript those wrappers re-export (and every other `@kerfjs/ui` subpath) resolves to `src/`, and CSS resolves to `src/` as well. A component that gains a new CSS dependency needs a restart, because the wrapper listing its stylesheets is regenerated only by the build. Production demo builds, previews, and the browser tests use `dist/`. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
+Run `npm run dev` from `ui/` (or `npm run dev:lan` from the repo root or `ui/`). The catalog is a development and review surface, not a second implementation. The development server reloads component source edits without a restart: component entries still load through their `dist/browser` wrappers, so each component's reachable CSS is exercised as consumers receive it, but the JavaScript those wrappers re-export (and every other `@kerfjs/ui` subpath) resolves to `src/`, and CSS resolves to `src/` as well. A component that gains a new CSS dependency needs a restart, because the wrapper listing its stylesheets is regenerated only by the build. Production demo builds, previews, and the browser tests use `dist/`. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
+
+`npm run dev:lan` serves the same development catalog on every network
+interface, for checks only a real device can make: a phone's virtual keyboard
+and safe areas, touch dragging, and device rendering. It prints the catalog's
+LAN and Tailscale URLs (opening the bottom-sheet route) and accepts Tailscale
+MagicDNS (`*.ts.net`) and mDNS (`*.local`) host names; plain `npm run dev` stays
+on `127.0.0.1`. The catalog page sets `viewport-fit=cover`, so on a notched
+phone `env(safe-area-inset-*)` reports the real insets and the layouts' safe-area
+model is visible. See [`manual-test-plan.md`](manual-test-plan.md) for the
+device checks.
 
 Every Playwright entry point builds current source before the preview server
 starts. `npm run test:e2e -- tests/browser/row.spec.ts` and a direct focused

package/llms.txt

@@ -24,6 +24,28 @@ depth; avoid a wrapper or extra background that paints the same visual surface
 twice. Check contrast in both color schemes over the actual backdrop. See
 [contextual transparency](./docs/webawesome-theme.md#contextual-transparency).
 
+For chrome laid over imagery, use the `clear` presentation (Pane
+`headerPresentation`, NavStack `chromePresentation` /
+`bottomToolbarPresentation`, TabNavigator `barPresentation`) with glass
+control groups, and `scrollEdge="material"` (or `"surface"`) to fade a
+backing in gradually over `scrollEdgeDistance` (default 60px) as content
+scrolls beneath (a first `BackdropImage` with `underChrome` runs its artwork beneath the header); see [Clear header](./docs/layout.md#clear-header).
+
+For a `kerfjs/overlay` dialog with `presentation: 'bottom-sheet'`, import
+`@kerfjs/ui/overlay-sheet.css` once (and pass `exitClass: 'kui-overlay-sheet-exit'`
+for the slide out; add the `kui-overlay-sheet-resizable` class and call
+`wireOverlaySheets()` for a resize grabber); see [Core dialogs as bottom sheets](./docs/surface-scaffold.md#core-dialogs-as-bottom-sheets).
+
+For an app-chosen surface color, set the typed `background` prop (a
+`@kerfjs/ui/css-values` color) on `Pane` (also `PaneConfig`), `NavStack`,
+`TabNavigator`, or a `TabNavigatorTab` instead of styling the component. It
+replaces the default or sunken fill; overlay chrome keeps its material; forced
+colors paint `Canvas`. Keep content at AA over the color. See
+[Background colors](./docs/layout.md#background-colors).
+For a region that takes on a color with text kept at AA automatically, set
+`tint={{ color, scheme }}` (the app declares the scheme; no color detection; an optional `accent` re-derives the brand ramp at AA);
+see [Tinted surfaces](./docs/layout.md#tinted-surfaces).
+
 For arbitrary interactive help or popup content, use `openAnchoredSurface` or
 `openAnchoredSurfaceAt` from `@kerfjs/ui/anchored-surface`; see
 [AnchoredSurface](./docs/anchored-surface.md). The app owns content and actions.
@@ -40,8 +62,10 @@ the folder modules, and CSS only imports their owner stylesheets.
 
 ### Shared semantic tones
 
-Use `ToolbarText tone="dark"` on a loud or photo-backed toolbar surface to
-match dark control groups. It applies to read-only headings and actionable
+Use `ToolbarText tone="dark"` on a loud-filled toolbar surface (the inverse
+`--kui-color-neutral-fill-loud`) to match dark control groups; it inverts with
+the color scheme. Over a dark photo or scrim keep the default tone inside a
+`BackdropImage` overlay, which takes the dark scheme under its `scrim`. It applies to read-only headings and actionable
 titles at every size; default tone retains existing identity and heading colors.
 
 `SemanticTone` is the shared color-role type for `Badge`, `Chip`, `StateBanner`,
@@ -476,6 +500,7 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   Text supports `controlMargins` with canonical physical Sides for an exterior 8px control gutter; it preserves border/padding and avoids an isolated Row wrapper. Avoid stacking it with parent insets. Inline spans retain native inline margin behavior.
 
   `ToolbarControlGroup.tileTone` selects `neutral`, `brand`, `success`, `warning`, or `danger` quiet fill, matching quiet border, and on-quiet foreground for a non-interactive icon tile. Compose a contained `single` group whose only child is a direct decorative LucideIcon (`aria-hidden="true"`). Omission preserves the normal group palette. The prop does not recolor interactive, mixed, multi-control, or borderless groups; keep real actions in controls with their existing focus/hover/pressed treatments.
+  `ToolbarControlGroup` `material="glass"` paints a group that floats over imagery or a clear (transparent) toolbar on the translucent chrome material (`--kui-chrome-material` with the blur/saturate `--kui-chrome-material-filter`), with a specular edge in place of the gray border and a soft shadow. Its controls take `--kui-color-text`, so they stay at AA over any content; a raised or outline selection paints an opaque surface pill. The fill turns opaque under reduced transparency, increased contrast, static effects (`update: slow` or `:root[data-kui-effects="static"]`), or without backdrop-filter support, and paints Canvas/CanvasText in forced colors. A `tone="dark"` glass group keeps its loud fill and gains the blur and edge; a borderless group has no surface and ignores the material. Keep the solid default on an opaque toolbar, and never add your own `backdrop-filter` or translucent background to a group.
   `ListItem`, `ListItemLink`, and `ListActionRow` take `iconTile` to present their leading `icon` in a filled 32px rounded tile holding an 18px glyph, for settings or command rows that identify each entry by color. Pass a tone (`neutral`, `brand`, `success`, `warning`, or `danger`) for the same quiet fill, matching quiet border, and on-quiet foreground as `ToolbarControlGroup.tileTone`, or `{ color, foreground? }` for an application color: `color` is a `CssColor` (`uiColor()`, `colorVar()`, or `fillColor('#e5484d')`) and `foreground` a `CssForegroundColor`; without one, the glyph is black or white, whichever contrasts with the fill. The tile sits 6px clear of a standard 44px row (a compact row is at least 42px tall), moves the label to the tile's edge, and keeps its colors when the row is hovered or selected. Never wrap the icon in your own tile or resize the row's icon slot.
   Toolbar zones accept `KerfUiContent` directly. Use `ToolbarText` for identity and `ToolbarControlGroup` for related controls that need its shared chrome; a bare control keeps its own styling and accessibility responsibilities.
   Expanded search groups accept `expandedOverflow="visible"` to anchor app-owned suggestion/date/help surfaces below their relative root; collapsed/default groups retain existing clipping. Apps own surface placement/dismissal and use `data-token-search-keep-open` or `collapsible.keepOpenOn` for focus.
@@ -528,7 +553,8 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   For a header that floats over its scrolling content, set
   `headerPresentation="overlay"` on the `Pane` (or in `PaneConfig`). It paints
   the translucent chrome material (`--kui-chrome-material`, opaque under
-  reduced transparency, increased contrast, and forced colors). The same
+  reduced transparency, increased contrast, forced colors, a slow-updating
+  display, and the app-set `data-kui-effects="static"` root switch). The same
   `wireScrollDividers` call measures the header and publishes its height as
   block-start scroll clearance, which the content clears automatically. Keep
   overlay-header text in the normal text color.
@@ -755,6 +781,18 @@ created, input }`. Never use a hand-styled `<input list>` + `<datalist>`.
   inverse chrome, place the chips in a dark appearance scope (`.wa-dark`)
   instead of restyling them.
 
+- **Open a scrolling view with `BackdropImage`.** Place it first in a Pane or
+  NavStack view's scrolling content: `parallax` (`subtle` or a 0 to 1 factor)
+  lags the image on a compositor-only scroll timeline, `blur` (`radius`,
+  `blurredSrc`, `dim`) cross-fades in a once-blurred copy as it scrolls away
+  (only opacity animates, never the filter), `fadeTo` (a `CssColor`)
+  dissolves it into a color that keeps painting under its `children`, and
+  `overlay` content sits over its block end with an optional `scrim`. Pass
+  `alt=""` for a decorative image. It is static under reduced motion,
+  `data-kui-effects="static"`, or without scroll-driven animations, and ends on
+  a hard edge (overlay on a solid `fadeTo` band) under reduced transparency. Never hand-roll scroll listeners or
+  `background-attachment: fixed`.
+
 - **Use `Composer` for a chat or prompt composer.** `@kerfjs/ui/composer`
   renders a raised frame (standard border, large radius, `shadow-l`) whose
   border turns brand while focus is within, a borderless textarea that grows
@@ -844,7 +882,7 @@ details.
 
 Select menus use native viewport shifting with 10px gutters: default menus grow to content (up to 20rem), while `fitMenu` matches trigger width and long labels wrap. Keep popup sizing and position repairs out of consumer CSS.
 
-Key sibling `DialogSurface`s that render conditionally with `rootAttributes={{ "data-key": "…" }}` so a re-render morphs each dialog into itself; never wrap one in a keyed app `div`. Modal `DialogSurface` bounds use typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`); explicit caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Application render state chooses responsive values, and preview layout remains application-owned. `height` sets a definite bounded modal size and `bodyLayout="fill"` lets one child fill the body; `bodyLayout="fill-last"` keeps leading rows at their height above one filling last child, and `footerPresentation="floating"` (with a typed `footerOffset`) floats a chat composer over the body while the body reserves its measured height; give the transcript `scrollClearance="block-end"` (a `scrollable` `List` or a `Pane`) to let it scroll beneath the composer, with the last message still resting above it, through the published `--kui-scroll-clearance-block-end` context (overlaying chrome publishes `--kui-scroll-clearance-block-start` / `-end`; one scroller per covered edge opts in; a composed Pane opts in through `PaneConfig.scrollClearance` on a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`). `headerPresentation="floating"` lays the title bar over the body on the translucent `--kui-chrome-material-raised` (opaque under reduced transparency, increased contrast, and forced colors); the register measures it and the body reserves it, and a `fill` body's only child with `scrollClearance="both"` scrolls beneath both the title bar and a floating composer through the published `--kui-scroll-clearance-block-start`. `PopoverDialogSurface` is the non-modal, light-dismiss counterpart on the native Popover API, with the same size props and an `embedded` in-flow presentation; `describedBy` sets its `aria-describedby` (usually a title `ToolbarText`'s `descriptionId`).
+Key sibling `DialogSurface`s that render conditionally with `rootAttributes={{ "data-key": "…" }}` so a re-render morphs each dialog into itself; never wrap one in a keyed app `div`. Modal `DialogSurface` bounds use typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`); explicit caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Application render state chooses responsive values, and preview layout remains application-owned. `height` sets a definite bounded modal size and `bodyLayout="fill"` lets one child fill the body; `bodyLayout="fill-last"` keeps leading rows at their height above one filling last child, and `footerPresentation="floating"` (with a typed `footerOffset`) floats a chat composer over the body while the body reserves its measured height; give the transcript `scrollClearance="block-end"` (a `scrollable` `List` or a `Pane`) to let it scroll beneath the composer, with the last message still resting above it, through the published `--kui-scroll-clearance-block-end` context (overlaying chrome publishes `--kui-scroll-clearance-block-start` / `-end`; one scroller per covered edge opts in; a composed Pane opts in through `PaneConfig.scrollClearance` on a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`). `headerPresentation="floating"` lays the title bar over the body on the translucent `--kui-chrome-material-raised` (opaque under reduced transparency, increased contrast, and forced colors); the register measures it and the body reserves it, and a `fill` body's only child with `scrollClearance="both"` scrolls beneath both the title bar and a floating composer through the published `--kui-scroll-clearance-block-start`. `presentation="bottom-sheet"` attaches the dialog to the bottom edge with square bottom corners, safe-area and virtual-keyboard clearance behind the panel, and a slide in/out (`enterMotion` / `exitMotion`); `resizable` adds a top grabber separator bounded by `minHeight` and `maxHeight`. `PopoverDialogSurface` is the non-modal, light-dismiss counterpart on the native Popover API, with the same size props and an `embedded` in-flow presentation; `describedBy` sets its `aria-describedby` (usually a title `ToolbarText`'s `descriptionId`).
 
 Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog` and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.