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

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,48 @@ 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
+A list-detail dialog is laid out like a `Workbench` with a left sidebar: on
+roomy devices the list is a full-height sidebar and the detail is a full-height
+main column, each a `Pane` with its own top `Toolbar`. The sidebar's toolbar
+carries its quiet default-size title (and it may add a bottom toolbar for
+sidebar-only actions); the main column's toolbar carries the dialog's primary
+extra-large title and the close control, and its footer carries the record
+actions. The Web Awesome dialog therefore renders `without-header` there —
+its label still names the modal — and the close button uses
+`data-dialog="close"`. Web Awesome keeps modal focus and Escape, and the thin
+recipe adapter restores the invoking control after the hide event.
+`DialogSurface` chooses the large modal with no body inset, because the panes
+own their geometry. Its explicit 16px `viewportGutter` and `maxHeight="viewport"`
+bound the roomy modal to the dynamic viewport; the compact fullscreen
+presentation retains its existing geometry. Application render state chooses
+the presentation and can likewise choose gutter/cap values for a compact modal.
+On compact devices the dialog becomes a full-screen sheet
+with its own labeled header and footer actions, 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 put the primary title in a header spanning both
+columns, rebuild the dialog, or reach into private shadow parts.
+
+## 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 +127,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 +231,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/split-view.md

@@ -6,13 +6,31 @@ on compact ones. One of the opt-in app layouts (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 
 ```ts
-import { SplitView } from '@kerfjs/ui/split-view';
-import { deviceClass } from '@kerfjs/ui/device-class';
-import '@kerfjs/ui/split-view.css';
-// plus nav-stack.css when the compact path is reachable, and
-// wireResizableRegions / wireNavStack for the interactive behavior.
+import { SplitView } from "@kerfjs/ui/split-view";
+import { deviceClass } from "@kerfjs/ui/device-class";
+// plus wireResizableRegions / wireNavStack for the interactive behavior.
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads SplitView's stylesheet and those of the components it renders internally
+(its compact `NavStack`, `ResizableRegion`, and the toolbar
+components). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/split-view.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
+## Safe areas
+
+The list pane grows by the inline-start unsafe inset and pads for the edges it
+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).
+
+For a lowered list or detail background, render a `Pane` in that region with
+`appearance="sunken"`. SplitView arranges regions but does not own their
+vertical scroll; its compact NavStack form can use the view's or nested Pane's
+appearance. See [Lowered work surfaces](layout.md#lowered-work-surfaces).
+
 ## Responsive by device class
 
 `SplitView` is declarative; the app derives `compact` from the device class and
@@ -37,13 +55,84 @@ const selected = signal<string | null>(null);
 
 - **Roomy** (`compact: false`): both panes show. With `resizable`, the list sits
   in a `ResizableRegion` (wire it with `wireResizableRegions`); without it the
-  list takes a fixed `--kui-split-view-list-width` (default 320px) and the detail
-  fills the rest.
+  list takes a fixed width and the detail fills the rest. Set it with
+  `listWidth`: a number of CSS pixels (default 320), or `{ size, maxFraction }`
+  to cap the preferred size at that share of the SplitView's own width, so a
+  narrow container (a dialog, a small window) always leaves the detail in view —
+  `listWidth={{ size: 432, maxFraction: 0.5 }}` is 432px until the split is
+  narrower than 864px, then half of it. `listWidth` is for the fixed split; a
+  resizable list is sized by `resizable` (combining them throws). The
+  `--kui-split-view-list-width` token remains for theme-level defaults; the
+  prop wins over it.
 - **Compact** (`compact: true`): the split collapses to a `NavStack`. The list is
   the root; when `detailActive` is true the detail is pushed over it with an
   automatic back control (wire it with `wireNavStack`, whose `onBack` clears the
   app's selection). This is the portrait-tablet / handset presentation; as a
   dialog the compact form is a full-screen or large partial-cover modal.
 
+## Filling its container
+
+A SplitView fills its container's block size: give the container a definite
+height (a fixed or viewport-bounded `height`, a flex item that grows, a grid
+row) and the split stretches to it, with each `Pane` owning its own scrolling.
+That holds in a block box, a fixed-size native popover or dialog, a flex column
+below a header, and a grid; no app-side `display: grid` /
+`grid-template-rows: minmax(0, 1fr)` wrapper is needed. A container sized only
+by `max-height` has no height to fill, so the split takes its content height;
+give such a container a `height` instead.
+
+## Configuring the list region and the compact stack
+
+`resizable` forwards the list's `ResizableRegion` configuration alongside
+`size`, `min`, and `max`: `separator` (`"hidden"` keeps the resize hit target
+but paints no line), `handleIcon`, `contentOverflow`, and collapse —
+`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`, and
+`restorePosition`. A collapsed list snaps to zero width, renders `inert` and
+`aria-hidden`, and the detail fills the split; the app owns the `collapsed`
+flag and renders the restore control (usually a `FloatingToolbar`). Omitted
+options keep the region's defaults.
+
+```tsx
+resizable={{
+  size: listWidth.value,
+  min: 220,
+  max: 480,
+  collapsed: listCollapsed.value,
+  restoreControl: <ShowThreadsToolbar />,
+}}
+```
+
+`compactStack` configures the compact `NavStack`: `toolbarConfig`, `backIcon`,
+`backText`, `hideToolbar`, the persistent `bottomToolbar`, and `chromeDividers`
+forward to the stack, and `list` / `detail` give each view its own structured
+top `toolbar` (`leading`, `center`, `trailing`) and `bottomToolbar`:
+
+```tsx
+compactStack={{
+  backText: "Threads",
+  toolbarConfig: { headingLevel: 1 },
+  list: { toolbar: { trailing: <ComposeGroup /> } },
+  detail: {
+    toolbar: { trailing: <ReplyGroup /> },
+    bottomToolbar: { label: "Message Actions", leading: <MessageActions /> },
+  },
+}}
+```
+
+The catalog's **Interactive Compact Drill-Down** example exercises this exact
+controlled flow: a list action sets the selected message, `detailActive` pushes
+its detail, and the wired Back action clears the selection to reveal the
+preserved list. It also forwards `compactStack`: a level-2 heading title over
+a bottom divider, a Compose group on the list view, and a Reply group plus a
+bottom toolbar on the detail. Use the same structure in application demos so
+compact examples show the interaction rather than rendering a disconnected
+detail state.
+
+The catalog's **Resizable, Collapsible List** example forwards `resizable`: a
+hidden separator that still resizes the list (its committed width comes back
+through `wireResizableRegions`' `onCommit` into the app's size signal), a Hide
+control in the list's own toolbar, and a `FloatingToolbar` restore control in
+the split's bottom-start corner.
+
 Compose the interactive wiring from the existing helpers — `SplitView` adds no
 wire of its own.

package/docs/sunken-panel.md

@@ -0,0 +1,106 @@
+# SunkenPanel
+
+`SunkenPanel` is a visually lowered application surface with one compact inset
+and a vertical content stack. Use it for a main work area or nested panel whose
+background should sit behind ordinary content, such as the primary stage in an
+issue tracker or component catalog.
+
+```tsx
+import { SunkenPanel } from '@kerfjs/ui/sunken-panel';
+
+<SunkenPanel ariaLabel="Release Workspace">
+  <ReleaseSummary />
+  <ReleaseChecks />
+</SunkenPanel>;
+```
+
+The default `shape="rounded"` uses the shared rounded-rectangle radius. Choose
+`shape="square"` for a flush or edge-to-edge area that needs `border-radius: 0`:
+
+```tsx
+<SunkenPanel shape="square">
+  <Workspace />
+</SunkenPanel>
+```
+
+## Filling a work area
+
+Set `fill` when the panel is the direct layout root of a parent with a definite
+height. Inside a flex column, use `flex` so it takes the remaining space and
+can shrink with its parent. Like `Grid`, `flex` accepts `true` (equivalent to
+`1 1 auto`), a CSS flex keyword, or a typed `CssFlex` value. The panel keeps
+`min-height: 0`, allowing its parent to own scrolling.
+
+```tsx
+<List fill>
+  <Toolbar label="Work Area" />
+  <SunkenPanel flex>
+    <WorkArea />
+  </SunkenPanel>
+</List>
+```
+
+Inside a `Pane`, the Pane's content remains the scroll owner. Place a
+`SunkenPanel fill` in a definite-height Pane content region when the surface
+itself needs to cover empty space, or use `flex` when a flex parent allocates
+the remaining space. The panel does not add another scroller.
+
+## Ownership
+
+The root owns its lowered background, 8px padding, and 8px vertical gap.
+Children own their borders and internal geometry. The application owns child
+order, responsive placement, and scrolling; `SunkenPanel` deliberately does not
+create another scroll container.
+
+Use `ariaLabel` only when the surface is a distinct region people need to find
+by name. With a label, the root receives `role="region"`; without one it remains
+a non-landmark grouping.
+
+Set `tabIndex={0}` to include the whole panel in the Tab order, or
+`tabIndex={-1}` for a programmatic focus target. Keyboard focus draws the
+standard focus ring. `outlined` keeps the same ring visible independently of
+focus, for example while the panel is a drop target. Give a focusable work area
+an `ariaLabel` when it is a distinct named region.
+
+Do not use `SunkenPanel` merely to add padding, as a substitute for pane
+header/content/footer anatomy, or around a child that already owns the same
+outer surface.
+
+For a lowered scrolling work area with Pane chrome, use
+[`Pane appearance="sunken"`](layout.md#lowered-work-surfaces). It paints the
+scroll viewport and empty space without adding a second scroller.
+
+## Public styling boundary
+
+Override the public properties at the composition boundary:
+
+- `--kui-sunken-panel-background`
+- `--kui-sunken-panel-foreground`
+- `--kui-sunken-panel-padding`
+- `--kui-sunken-panel-gap`
+- `--kui-sunken-panel-radius`
+
+The default background uses the shared translucent lowered-surface token.
+Nested panels composite naturally at every depth: darker in light mode and
+lighter in dark mode, without wrappers, depth classes, or per-instance token
+assignments. Pane and Web Awesome sunken surfaces use the same palette.
+See [Contextual transparency](./webawesome-theme.md#contextual-transparency).
+Keep ordinary composition on these defaults; public properties are theming
+escape hatches, not a reason to restyle each demo or nesting level.
+
+Every sunken surface — SunkenPanel, `Pane appearance="sunken"`, sunken
+Workbench regions and TabNavigator scenes, and Web Awesome
+`appearance="sunken"` — paints `--kui-sunken-surface`: a fine, monochrome
+grain (a seeded 100px tile at 4% maximum opacity) over the lowered color. The
+tile is drawn once per page, at runtime, by the first sunken surface that
+renders (nothing ships as an asset; server rendering paints the flat color
+until the browser renders one). Translucent children such as a `ValueTable`
+let the grain show through rather than adding their own. Set
+`--kui-sunken-texture: none` at `:root` for a flat lowered surface, or to
+another image; call `ensureSunkenTexture()` (exported from
+`@kerfjs/ui/sunken-panel`) on a page whose only sunken surfaces are Web Awesome
+elements.
+
+The public root class is `.kui-sunken-panel`. Prefer the properties above over
+styling descendants. The `square` shape deliberately overrides the radius
+property with zero; use `rounded` when customizing the radius token.