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

package/docs/ui-analyzer.md

@@ -55,25 +55,26 @@ policy, or analysis inputs to the containing application.
 
 ## Diagnostics and exit behavior
 
-| Rule       | Kind   | Meaning                                                           |
-| ---------- | ------ | ----------------------------------------------------------------- |
-| `KUI-L001` | error  | A stylesheet reaches into a private or unknown `.kui-*` selector. |
-| `KUI-L002` | error  | A stylesheet references an unknown or private `--kui-*` token.    |
-| `KUI-L003` | error  | One element combines public classes that claim the same geometry. |
-| `KUI-L004` | review | Nested literal classes both add a content inset.                  |
-| `KUI-L005` | review | Consumer CSS forces a public component's dimensions.              |
-| `KUI-L006` | review | Literal spacing falls outside Kerf's approved scale.              |
-| `KUI-L007` | error  | A declared scroll owner is nested inside another scroll owner.    |
-| `KUI-L008` | review | A dynamic class expression cannot be classified soundly.          |
-| `KUI-L009` | error  | A stylesheet cannot be parsed.                                    |
-| `KUI-L010` | error  | A selector reaches a private Kerf descendant from a public root.  |
-| `KUI-L011` | error  | A `::part()` target is not cataloged as a public extension point. |
-| `KUI-L012` | error  | CSS assigns a Kerf token without a public configuration contract. |
-| `KUI-L013` | error  | A CSS-adjacent prop uses an unknown shorthand or raw literal.     |
-| `KUI-L014` | error  | A typed helper produces the wrong property grammar.               |
-| `KUI-L015` | error  | An expression-only helper is passed without a composer.           |
-| `KUI-L016` | error  | A removed declaration-list escape hatch is used.                  |
-| `KUI-L017` | review | A valid but exceptional off-scale shorthand needs justification.  |
+| Rule       | Kind   | Meaning                                                                               |
+| ---------- | ------ | ------------------------------------------------------------------------------------- |
+| `KUI-L001` | error  | A stylesheet reaches into a private or unknown `.kui-*` selector.                     |
+| `KUI-L002` | error  | A stylesheet references an unknown or private `--kui-*` token.                        |
+| `KUI-L003` | error  | One element combines public classes that claim the same geometry.                     |
+| `KUI-L004` | review | Nested literal classes both add a content inset.                                      |
+| `KUI-L005` | review | Consumer CSS forces a public component's dimensions.                                  |
+| `KUI-L006` | review | Literal spacing falls outside Kerf's approved scale.                                  |
+| `KUI-L007` | error  | A declared scroll owner is nested inside another scroll owner.                        |
+| `KUI-L008` | review | A dynamic class expression cannot be classified soundly.                              |
+| `KUI-L009` | error  | A stylesheet cannot be parsed.                                                        |
+| `KUI-L010` | error  | A selector reaches a private Kerf descendant from a public root.                      |
+| `KUI-L011` | error  | A `::part()` target is not cataloged as a public extension point.                     |
+| `KUI-L012` | error  | CSS assigns a Kerf token without a public configuration contract.                     |
+| `KUI-L013` | error  | A CSS-adjacent prop uses an unknown shorthand or raw literal.                         |
+| `KUI-L014` | error  | A typed helper produces the wrong property grammar.                                   |
+| `KUI-L015` | error  | An expression-only helper is passed without a composer.                               |
+| `KUI-L016` | error  | A removed declaration-list escape hatch is used.                                      |
+| `KUI-L017` | review | A valid but exceptional off-scale shorthand needs justification.                      |
+| `KUI-L018` | review | A loud fill override lacks a governing `on-loud`, or the literal pair is below 4.5:1. |
 
 Errors are provable contract violations and make the command exit 1. Review
 findings are deliberately heuristic and do not fail by default; pass
@@ -102,6 +103,80 @@ uses that same metadata for direct component calls and JSX, including nested
 paths such as `choices[].color`; consumer catalogs receive identical checks.
 Dynamic values remain a type-system responsibility rather than being guessed.
 
+## Loud fill / on-loud pairing (`KUI-L018`)
+
+The shipped Web Awesome theme pairs every `--wa-color-{tone}-fill-loud` with a
+`--wa-color-{tone}-on-loud` foreground that clears WCAG AA (4.5:1), for the
+`neutral`, `brand`, `success`, `warning`, `danger`, and `pop` tones. A
+stylesheet that overrides a loud fill without also setting that tone's
+`on-loud` keeps the theme's foreground on an unknown fill, so the guarantee no
+longer holds. `KUI-L018` reports such a fill and names each scope that lacks a
+pair, and it reports a pair that is present but measurably fails.
+
+**Which `on-loud` governs a fill.** Each individual selector of the fill
+(after resolving CSS nesting and splitting selector lists) inside its chain of
+at-rules is one scope. An `on-loud` of the same tone governs it when declared:
+
+- in the same scope, in the same or a separate rule, in either order; or
+- in an ancestor scope: a document-root selector (`:root`, `html`, `:host`,
+  `*`), or the leading part of a descendant or child chain (`.shell` governs
+  `.shell .panel` and `.frame > .tile`, but not `.shell-alt .panel` or
+  `.shell.dense`); and
+- under no at-rule, or the same at-rule chain (an unconditional `on-loud`
+  applies inside `@media`, but one under `@media` or `@supports` is not proven
+  to apply to an unconditional fill).
+
+That `on-loud` may live in the same stylesheet or in another one the same
+entry loads: a source module that imports both stylesheets, or a stylesheet
+that reaches both through `@import`. A stylesheet no entry loads with the fill
+does not count. When several candidates apply, the same scope wins (this
+stylesheet first), then the nearest ancestor.
+
+**Contrast, when it can be proven.** When the fill and its governing `on-loud`
+are both literal opaque colors (hex, `rgb()`/`rgba()`, `hsl()`/`hsla()`,
+`white`/`black`, or a `light-dark()` of two of them), the analyzer computes the
+WCAG contrast ratio in each color scheme and reports a pair below 4.5:1, with
+the ratio and scheme in its evidence. An unpaired literal fill is accepted when
+it clears 4.5:1 in both schemes against the theme's default `on-loud` for its
+tone (`light-dark(#fff, #111113)` for `brand` and `danger`, `#1d1d1f` for
+`success` and `warning`); `neutral` follows a surface token and `pop` has no
+Web Awesome default, so their unpaired fills are always reported. Values it
+cannot prove (`var()`, `color-mix()`, translucent colors, keywords) are not
+measured: a present pair is accepted, and an unpaired fill is reported.
+
+```css
+/* KUI-L018: brand fill moves, its foreground does not. */
+.billing {
+  --wa-color-brand-fill-loud: #7540a8;
+}
+
+/* Paired: both in the same scope. */
+.billing {
+  --wa-color-brand-fill-loud: #7540a8;
+  --wa-color-brand-on-loud: #ffffff;
+}
+
+/* Paired through an ancestor scope (6.87:1). */
+:root {
+  --wa-color-brand-on-loud: #ffffff;
+}
+.billing {
+  --wa-color-brand-fill-loud: #7540a8;
+}
+
+/* KUI-L018: present, but white on this fill measures 2.14:1. */
+.billing {
+  --wa-color-brand-fill-loud: #7fb3ff;
+  --wa-color-brand-on-loud: #ffffff;
+}
+```
+
+It is a review finding rather than an error because the analyzer cannot see
+every cascade: an `on-loud` set inline, by script, or by a stylesheet it does
+not analyze may still govern the fill. Set the `on-loud` explicitly beside the
+fill, which also documents the pair; use `--fail-on-review` to gate it in CI.
+See [the Web Awesome theme customization notes](./webawesome-theme.md#customization).
+
 The JSON report schema is exported as
 `@kerfjs/ui/analyzer/report.schema.json`.
 

package/docs/ui-doctor.md

@@ -24,6 +24,12 @@ exceptional but valid spacing choice in the review queue. The ESLint and
 analyzer stages share these ids, so the normalized report can be consumed as
 one repair loop without tool-specific translations.
 
+The analyzer stage also reads consumer stylesheets for theme overrides:
+`KUI-L018` is a review finding for a `--wa-color-{tone}-fill-loud` override
+that lacks a governing `--wa-color-{tone}-on-loud` (in the same or an ancestor
+scope, in any stylesheet the same entry loads), or whose literal pair measures
+below 4.5:1 (see [the analyzer rule](./ui-analyzer.md#loud-fill--on-loud-pairing-kui-l018)).
+
 The browser evaluator is different: it runs the application and is disabled by default. It only runs when configuration supplies `browser.url` or the command receives `--browser-url`. Start and authorize the target application separately.
 
 An unavailable or failed stage does not prevent independent stages from reporting. Its final exit is still a configuration failure, so a partial run cannot appear clean.

package/docs/ux-demo.md

@@ -18,7 +18,7 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 
 - It imports public component subpaths, exercising their browser-selected reachable CSS rather than a catalog-only style path.
 - The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
-- The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, pending, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding, closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
+- The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, pending, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding (a new tab opens `pending` with a spinner and stays selectable while its panel shows a `Skeleton` heading until a simulated load completes), closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
 - Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, and feedback scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component. The former aggregate Web Awesome theme specimen is intentionally omitted because its component families are covered by those focused routes.
 - `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Functional groups follow their authored importance order; components precede compositions inside each group, equal-importance entries use alphabetical order, and the Recipes group comes last. Composition names stay concise and project a visible `Composition` sidebar tag. Non-supported Web Awesome recommendations project to a visible `Discouraged` tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
 - Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
@@ -31,7 +31,7 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - The `DisclosureArrow` route renders the production 18px root-scaled default without a catalog-only size override. Its two native buttons independently control the default right-to-down chevron and a recognizable right-facing replacement arrow with left-to-up custom directions; both use shortest-path rotation and their names stay stable while `aria-expanded` communicates state. Browser coverage verifies the custom clockwise path, pointer and native keyboard activation, focus, narrow and 200%-zoom stacking with contained labels, consumer sizing, and the independent `.5` Web Awesome glyph scale retained by Kerf `Select`.
 - A detail with relationships renders one content-fitted `Components` footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Its popup owns the standard surface inset so headings and even long component names stay clear of the menu border. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
 - Focused demos ship no local stylesheets, inline styles, or styling-only class names. They compose Kerf components first, Web Awesome surfaces where Kerf has no equivalent, and ordinary semantic HTML for the remainder. The catalog-owned `CatalogExample.viewport` contract supplies the few specimen constraints needed to demonstrate layout behavior. Recipes follow the same rule: they ship no stylesheets, inline styles, or styling-only classes, and the catalog frames each one in the `CatalogExample` viewport its exported `presentation` declares (full-width application arrangements span the canvas measure; narrower recipes sit in the centered example column). Demo-only CSS is limited to the document-shell `style.css`, which carries no recipe rules. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
-- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. Individual Web Awesome action, form, layout, navigation, feedback, media, and helper routes provide focused theme specimens without a redundant aggregate route; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges plus a scoped override; the Application tabs composition uses a Web Awesome card with semantic header/footer slots and Kerf `Text` while demonstrating overflow, edge autoscroll, and controlled pointer/keyboard reordering.
+- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. Individual Web Awesome action, form, layout, navigation, feedback, media, and helper routes provide focused theme specimens without a redundant aggregate route; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges, a scoped override, and a placeholder with and without a badge, the badged placeholder in every tone so captures cover the solid badge skeleton; the Application tabs composition uses a Web Awesome card with semantic header/footer slots and Kerf `Text` while demonstrating overflow, edge autoscroll, and controlled pointer/keyboard reordering.
 - The ToolbarControlGroup route also demonstrates the public compact/tight,
   mixed-content, filled-selection, nested-dropdown, and avatar/scrim contracts
   added for consumers that previously restyled group descendants. The compact

package/docs/webawesome-theme.md

@@ -143,8 +143,10 @@ short status or count, not a content item. A badge with `appearance="filled"` or
 `appearance="filled-outlined"` uses its variant's quiet fill with normal text by
 default so every shipped semantic variant meets WCAG AA for that small text;
 filled-outlined keeps its normal variant border. Accent badges keep their loud
-fills, with brand, success, and danger using a dark foreground that clears AA in
-both themes (neutral and warning retain their already-safe variant foregrounds).
+fills and their variant's `on-loud` foreground, which the theme sets to clear AA
+on that fill in both themes: white on the light brand (`#0075db`) and danger
+(`#eb0005`) fills, dark text on the success and warning fills and on the pale
+dark-mode brand and danger fills.
 Override
 `--kui-wa-badge-filled-background` and `--kui-wa-badge-filled-foreground` on a
 badge or containing scope when a product needs a different contrast-safe pair,
@@ -290,15 +292,29 @@ smallest subtree that needs a different identity:
 ```css
 :root {
   --wa-color-brand-fill-loud: #7540a8;
+  --wa-color-brand-on-loud: #ffffff;
   --wa-color-focus: #7540a8;
   --wa-form-control-border-radius: 0.5rem;
 }
 
 .billing-workspace {
   --wa-color-success-fill-loud: #10a86b;
+  --wa-color-success-on-loud: #1d1d1f;
 }
 ```
 
+The shipped theme pairs every `--wa-color-{variant}-fill-loud` with an
+`--wa-color-{variant}-on-loud` that clears WCAG AA (4.5:1) in both color
+schemes. When you override a loud fill, set its `on-loud` alongside it, in the
+same selector and at-rule scope, to a foreground that clears 4.5:1 on the new
+fill (white text on a bright fill usually does not: `#10a86b` above reaches
+only 3.1:1 with white, 5.5:1 with `#1d1d1f`). `kerf-ui-analyze` and
+`kerf-ui-doctor` report a loud fill override without a governing `on-loud`, or
+a literal pair that measures below 4.5:1, as review finding
+[`KUI-L018`](./ui-analyzer.md#loud-fill--on-loud-pairing-kui-l018); it cannot
+measure a `var()` or `color-mix()` value, so choosing a readable one is still
+yours.
+
 Use `.wa-light`, `.wa-dark`, and `.wa-invert` for explicit appearance scopes.
 Component-specific custom properties and documented `::part()` selectors from
 Web Awesome remain available when a semantic theme token is not sufficiently

package/docs/workbench.md

@@ -22,7 +22,22 @@ it can also be embedded. See [Document baseline](document-baseline.md).
 
 `Workbench` is declarative and the collapse is **pure CSS** — no wire. The app
 owns each panel's `collapsed` flag (usually a signal) and toggles it; the panel
-animates itself.
+animates itself. Panels are fixed-size by default; a panel can opt in to drag
+and keyboard resizing (see [Resizable panels](#resizable-panels)), and
+`wireWorkbench` can make overlay panels transient (see
+[Transient overlays](#transient-overlays)).
+
+A collapsed panel renders `inert` and `aria-hidden="true"` on the rail or
+drawer itself, and `inert` on its content, straight from `collapsed`, so
+neither Tab nor assistive technology reaches controls that have slid out of
+view, none of them can scroll back into view, and no empty labeled landmark
+stays behind. The slide-out still animates,
+and the panel's `restoreControl` lives outside the inert content, so it stays
+reachable. Expanding the panel makes its content reachable again in the same
+render. When the panel closes with focus inside it, `wireWorkbench` (given the
+panel's `collapsed` signal) moves focus back out (see
+[Transient overlays](#transient-overlays)); without it, that focus move is the
+app's.
 
 ```tsx
 const navCollapsed = signal(false);
@@ -61,15 +76,288 @@ an optional `label`. Common shell behavior is configured rather than restyled:
 - `contentOverflow: "clip" | "auto" | "visible"` lets a drawer temporarily
   expose an open popup without a descendant override;
 - `presentation: "inline" | "overlay" | "hidden"` supports compact overlays
-  or a responsive replacement. Overlay panels clamp both their track and fixed-size
-  animated content to the configured viewport-relative maximum;
+  or a responsive replacement. An overlay rail spans the Workbench height at
+  its side and an overlay drawer spans the work-area column at the bottom,
+  each exactly at its configured size (its separator border included, as in
+  flow) up to the viewport-relative overlay maximum; the content fills the
+  panel inside its border, so it is clamped with it;
+- `responsiveOverlayAt: "narrow" | "compact"` presents a rail or the bottom
+  drawer as an overlay below a Workbench container breakpoint — 704px or less
+  for `narrow`, 448px or less for `compact`, the breakpoints of
+  `ResizableRegion`'s `responsiveFillAt` — and inline above it. The CSS
+  decides, so the app needs no `deviceClass` check for presentation; a
+  collapsed overlay drops its surface and shadow so nothing covers the work
+  area, and the work area keeps the safe-area inset of the edge the overlay
+  covers. When overlays meet, the order is fixed rather than by which opened
+  last: both rails stack above the drawer, as inline rails span the
+  Workbench's full height beside the drawer's column, and the right rail
+  stacks above the left. Rails take `--kui-workbench-overlay-z` (41) and the
+  drawer one less. Restore controls take `--kui-workbench-restore-z`, which
+  defaults to two less than the overlay z-index (39), so they sit beneath
+  every overlay: an open overlay covers another panel's restore control as
+  it covers the rest of the work area, and a collapsed overlay, which drops
+  its pointer events, leaves the control beneath it usable;
 - `restoreControl` places an application-owned restore affordance in a
-  safe-area-aware viewport corner (`restorePosition` chooses the corner).
+  corner of the Workbench itself while the panel is collapsed
+  (`restorePosition` chooses the corner), inset by
+  `--kui-workbench-restore-inset` (16px) plus the unsafe area of each edge the
+  corner reaches. A rail's control sits in the Workbench's corner; the
+  drawer's sits in the corner of the work-area column it restores into, so it
+  never lands on an expanded rail. A collapsed rail's control floats the
+  same inset above the top edge of an expanded inline bottom drawer, which
+  spans the column reaching that corner once the rail collapses, so it never
+  covers the drawer's content; it returns to the corner when the drawer
+  collapses (the drawer publishes its edge as a CSS anchor scoped to its own
+  Workbench; without anchor positioning the control keeps the corner). An
+  overlay drawer publishes no edge: an open one covers the control, as every
+  open overlay does. Because it is anchored to the Workbench
+  rather than the viewport, an embedded Workbench never floats it over page
+  chrome outside it, and it scrolls with the Workbench. Compose it from the
+  package controls — a `single` `ToolbarControlGroup` around one icon button
+  carrying `collapsiblePanelToggleIcon(side, true)` — rather than a bare
+  button. To give it `FloatingToolbar`'s toolbar role and floating look, wrap
+  that group in a `FloatingToolbar` whose `position` matches the corner: the
+  corner owns the inset (it sets `--kui-floating-toolbar-inset` to 0), so the
+  toolbar floats from the corner instead of doubling it.
+
+- `resizable: true | { min, max }` opts the panel in to drag and keyboard
+  resizing, driven by `wireWorkbench` (off by default).
 
 The same policy props are available on `ResizableRegion` and
 `CollapsiblePanel`, so a resizable application shell does not need to reach
 into `.kui-resizable-region__content`.
 
+## Resizable panels
+
+Resizing is **opt-in per panel**. Give a panel `resizable` — `true` for the
+default limits (rails 180–480px, drawer 120–480px) or `{ min, max }` — and
+render its `size` from an app-owned signal. The panel then owns a separator on
+its inner edge (the left rail's end, the right rail's start, the drawer's top)
+with the same focusable `role="separator"` contract as a `ResizableRegion`
+handle. `wireWorkbench` drives it:
+
+```tsx
+import { wireWorkbench } from "@kerfjs/ui/wire-workbench";
+
+const navSize = signal(280);
+const consoleSize = signal(200);
+
+<Workbench
+  id="studio"
+  label="Studio"
+  main={<Editor />}
+  mainMinSize={320} // the default: the editor never drops below 320px wide
+  mainMinHeight={120} // the default: the drawer leaves it 120px of height
+  leftRail={{
+    content: <Navigator />,
+    label: "Navigator",
+    collapsed: navCollapsed.value,
+    size: navSize.value,
+    resizable: { min: 200, max: 420 },
+    responsiveOverlayAt: "narrow", // an overlay when the Workbench is 704px or narrower
+  }}
+  bottomDrawer={{
+    content: <Console />,
+    label: "Console",
+    size: consoleSize.value,
+    resizable: true,
+  }}
+/>;
+
+// once, after mount:
+const stop = wireWorkbench(root, {
+  id: "studio",
+  panels: {
+    leftRail: {
+      size: navSize,
+      storageKey: "studio.nav-width",
+      collapsed: navCollapsed, // a transient overlay: takes focus, closes on Escape / outside press
+    },
+    bottomDrawer: { size: consoleSize, storageKey: "studio.console-height" },
+  },
+});
+```
+
+- **Pointer:** dragging the separator resizes the panel live (the wire marks
+  it `data-resizing` and suppresses content motion) and commits the final
+  size to the signal on release.
+- **Keyboard:** focus the separator; arrow keys resize by `step` (16px),
+  Shift+arrow by `largeStep` (64px), Home/End jump to `min`/`max`. The
+  separator's `aria-valuenow`/`aria-valuemin`/`aria-valuemax` report the size
+  and limits.
+- **Limits:** every size — dragged, typed, restored from storage, or passed
+  by the app — is clamped to `min`/`max` when rendered.
+- **Work-area minimum:** beside its inline rails, fixed or resizable, the work
+  area keeps at least `mainMinSize` px of width (a `Workbench` prop, default
+  320; `0` turns it off), and above an inline bottom drawer at least
+  `mainMinHeight` px of height (default 120; `0` turns it off). A dragged or
+  keyed rail stops growing where the work area would drop below its width,
+  and the drawer where it would drop below its height, so wide rails or a tall
+  drawer cannot crowd out the editor; `aria-valuemax` reports that reachable
+  maximum. When the Workbench itself narrows, the rails shrink in proportion
+  to their sizes, and when it gets shorter the drawer shrinks (their content
+  follows the shown size) while the work area holds its minimum; a squeezed
+  panel can still be made smaller, never larger, and never below its own
+  `min`. Two fixed 280px rails in a 720px Workbench show 200px each rather
+  than leaving the editor 160px. Each minimum applies only to a Workbench with a
+  panel on its axis, and never exceeds the Workbench itself.
+- **Squeezed below `min`:** when the Workbench is too narrow for a rail's
+  `min` beside the work-area minimum, the rail shows less than its `min` (a
+  172px Navigator whose `min` is 180). Its separator then reports that shown
+  width in `aria-valuenow`, and `aria-valuemin`/`aria-valuemax` pin to the
+  same value: the WAI-ARIA window splitter's value is the separator's actual
+  position, and the range must contain it, so a screen reader hears the width
+  on screen rather than a configured limit the layout cannot honor — and a
+  range that does not move, because the separator cannot move a rail the
+  container holds. A pinned separator commits nothing: arrow keys, Home/End,
+  and drags leave the rail's remembered size (and its storage) alone, so a
+  rail remembered at 280px returns at 280px, with the configured range, once
+  there is room.
+- **Small Workbenches:** inline panels have no shrink floor of their own, by
+  design; the work area's minimums win, so in a very small Workbench a rail or
+  the drawer can become a sliver. Do not add your own `min-width` /
+  `min-height` to hold a panel open. Give the panel
+  `responsiveOverlayAt: "narrow"` (704px of Workbench width or less) or
+  `"compact"` (448px or less) instead: below that breakpoint it presents as a
+  full-size overlay over the work area rather than squeezing beside it (see
+  the catalog's resizable and responsive-drawer Workbench examples).
+- **Collapse:** `collapsed` never changes a size. A collapsed panel keeps its
+  size (its content slides out at that width), its separator leaves the tab
+  order, and expanding it returns it at the size it had.
+- **Persistence:** with a `storageKey`, the size is loaded from `storage`
+  (default `localStorage`) at wire-up and saved on every change, like
+  `wireSidebar`'s collapsed state.
+- **Overlays never resize:** an overlay or hidden panel — including a rail
+  whose `responsiveOverlayAt` breakpoint currently applies — hides its
+  separator and is never resizable, and it leaves the work-area minimum to the
+  rails still in flow. With `responsiveOverlayAt` no device check is needed;
+  otherwise pass `deviceClass` and resizing is suspended while `compact` is
+  true, where rails present as overlay drawers or are replaced.
+- `wireWorkbench` drives only the panels it is given, matched by the
+  Workbench `id`, so it never double-drives a `ResizableRegion` (or another
+  Workbench) under the same root. `onResize({ panel, size, source })` reports
+  each committed resize.
+
+## Transient overlays
+
+An overlay panel covers the work area, so it should open only when the user
+asks for it and close as easily as it opened. Give `wireWorkbench` a panel's
+app-owned `collapsed` signal (`size` is optional, so a panel need not be
+resizable) and it treats the panel as a transient overlay whenever it
+presents as one, mirroring `wireSidebar`'s compact overlay:
+
+- **Collapsed on entering the breakpoint:** when a panel's
+  `responsiveOverlayAt` breakpoint begins to apply — at wire-up, when the
+  Workbench first renders, or when it narrows across the breakpoint — the
+  wiring remembers the panel's inline `collapsed` state and collapses it, so
+  nothing covers the work area until the user opens it. When the breakpoint
+  stops applying (and on disposal) the remembered inline state comes back.
+  These presentation changes skip the collapse motion.
+- **Focus moves in, and Tab stays in:** a panel that opens while it presents
+  as an overlay takes focus on its first focusable control (typically the
+  close control in its header), because it covers the work area and the
+  control that opened it. While it is open, Tab and Shift+Tab cycle through
+  its controls and never reach the covered work area; Escape, its own close
+  control, or an outside press leaves it. This is the ARIA dialog pattern
+  `wireSidebar`'s compact overlay follows. A panel opening inline never moves
+  focus.
+- **Escape** closes the open overlay panel that holds focus, else the most
+  recently opened one. An Escape another handler already handled
+  (`defaultPrevented`) is left alone.
+- **Outside press:** a pointer press that starts and ends outside an open
+  overlay panel closes it. The app's own toggle still works: its click closes
+  the panel before the wiring looks, and the press that opens a panel never
+  closes it.
+- **Focus:** when a panel closes with focus inside it — whatever closed it,
+  including the app's own control inside the panel — focus returns to the
+  control that had it when the panel opened (typically its toggle; one inside
+  another panel that has closed since is skipped), else to
+  the first focusable control in the panel's `restoreControl`, else to a
+  focusable control outside the panel whose `aria-controls` names the panel
+  (or an element inside it). The last is what a panel already open at
+  wire-up relies on, since nothing opened it: give the app's toggle
+  `aria-controls` naming the panel. A pointer press inside the panel that
+  drops focus to the page counts as focus inside: Safari never focuses a
+  clicked button, so pressing the panel's own Hide control blurs the focused
+  control before the click closes it, and focus still returns. Focus the user
+  has moved to another element since is left alone. Each panel's `id` derives from the
+  Workbench's — `<id>-left-rail`, `<id>-right-rail`, `<id>-bottom-drawer`:
+
+  ```tsx
+  <button
+    data-action="toggle-navigator"
+    aria-controls="editor-left-rail"
+    aria-expanded={String(!navCollapsed.value)}
+    aria-label={navCollapsed.value ? "Show navigator" : "Hide navigator"}
+  >
+    <LucideIcon {...collapsiblePanelToggleIcon("left", navCollapsed.value)} />
+  </button>
+  ```
+
+An open overlay can cover the control that opened it: a narrow Workbench's
+right-rail overlay spans the full height at the end edge, over the trailing
+end of the work area's toolbar, where its toggle usually sits. Escape and an
+outside press still close it, but neither is a visible, pointer-reachable
+control. So give every panel that may present as an overlay its own close
+control, as a `CollapsiblePanel` puts its collapse toggle in its own header:
+render the panel content as a `Pane` whose header `Toolbar` holds the title
+and a `single`, borderless `ToolbarControlGroup` around one icon button
+carrying `collapsiblePanelToggleIcon(side, false)`. The work area's toggle
+stays the always-visible way to show the panel. The catalog's resizable
+example does this for both rails.
+
+The drawer works the same way. The catalog's responsive overlay drawer
+example is the whole pattern for a bottom drawer:
+
+```tsx
+const outputCollapsed = signal(false); // open inline by default
+
+<Workbench
+  id="editor"
+  label="Editor"
+  main={<Editor />} // its toolbar toggles `outputCollapsed`
+  bottomDrawer={{
+    label: "Output",
+    content: <OutputPane />, // a Pane whose header holds its close control
+    collapsed: outputCollapsed.value,
+    size: 180,
+    responsiveOverlayAt: "narrow",
+  }}
+/>;
+
+wireWorkbench(root, {
+  id: "editor",
+  panels: { bottomDrawer: { collapsed: outputCollapsed } },
+});
+```
+
+Above 704px of Workbench width the drawer takes its own track below the
+editor. At 704px or less it overlays the bottom of the full-height editor,
+starts hidden, and closes from its own header, on Escape, or on a press
+outside it; widening the Workbench again brings it back inline in the state
+it had before.
+
+Escape and outside-press dismissal apply to static `presentation: "overlay"`
+panels too; entering and leaving the collapsed state around a breakpoint is
+only for `responsiveOverlayAt`, because a static presentation is the app's
+choice. Inline panels are never touched. Pass `dismissOverlays: false` to
+leave every `collapsed` write, and all focus handling, to the app.
+
+Overlays are exclusive by default, like `wireSidebar`'s compact overlays:
+opening a panel while it presents as an overlay closes every other open
+overlay panel, the bottom drawer included. At a narrow width two rails are
+wider than the Workbench, so without this the right rail would cover the
+navigator's own close control. Panels presenting inline are never closed by
+it, so a wide Workbench keeps both rails open. Pass `exclusiveOverlays: false`
+to let overlays stay open together; they then stack in the fixed order above,
+and Tab stays in the one that holds focus (else the most recently opened
+one).
+
+Where the browser supports `overflow-clip-margin`, the 20px hit target
+straddles the panel's separator line like a `ResizableRegion` handle;
+elsewhere it sits just inside the panel's inner edge, because the panel clips
+its sliding content.
+
 ## Resizable application-shell migration
 
 An application such as Hot Sheet can replace its shell descendant overrides
@@ -89,7 +377,13 @@ with state-derived props:
   collapseMotion="fade-slide"
   contentOverflow={createMenuOpen.value ? "visible" : "clip"}
   presentation={mobile.value ? "overlay" : "inline"}
-  restoreControl={<button data-action="show-drawer">Show terminals</button>}
+  restoreControl={
+    <ToolbarControlGroup label="Terminals" single>
+      <button data-action="show-drawer" aria-label="Show terminals">
+        <LucideIcon {...collapsiblePanelToggleIcon("bottom", true)} />
+      </button>
+    </ToolbarControlGroup>
+  }
 >
   <TerminalDrawer />
 </ResizableRegion>
@@ -113,8 +407,9 @@ set `--kui-workbench-rail-width` and `--kui-workbench-drawer-height` on a
 Workbench instance. The supported composition classes are `.kui-workbench`,
 `.kui-workbench__rail`, `.kui-workbench__rail--left`,
 `.kui-workbench__rail--right`, `.kui-workbench__center`,
-`.kui-workbench__main`, `.kui-workbench__drawer`, and
-`.kui-workbench__panel-content`, and `.kui-workbench__restore`; these exact hooks are cataloged for tools that
+`.kui-workbench__main`, `.kui-workbench__drawer`,
+`.kui-workbench__panel-content`, `.kui-workbench__handle`,
+`.kui-workbench__handle-icon`, and `.kui-workbench__restore`; these exact hooks are cataloged for tools that
 must classify public application selectors. Prefer the component props and two
 size tokens before selecting internal anatomy, and do not target its data
 attributes or descendant tags as styling contracts.

package/llms.txt

@@ -80,8 +80,10 @@ the folder modules, and CSS only imports their owner stylesheets.
    [`kerf-ui-doctor`](./docs/ui-doctor.md). Its portable JSON report merges
    profile/catalog, TypeScript, Kerf ESLint, and static analyzer diagnostics;
    CSS-adjacent component props are checked from catalog `cssValueProps`, so
-   prefer its canonical shorthand or typed helper over raw CSS strings;
-   repair source-located errors until exit 0. Use full mode for release gates;
+   prefer its canonical shorthand or typed helper over raw CSS strings; a
+   `--wa-color-{tone}-fill-loud` override without a governing `on-loud` (same
+   or ancestor scope, possibly in a co-loaded stylesheet), or whose literal
+   pair measures below 4.5:1, is review finding `KUI-L018` (set both); repair source-located errors until exit 0. Use full mode for release gates;
    generated `dist`/`coverage`, dependency, cache, evidence, and nested-worktree
    directories are excluded consistently from every static stage.
    [`kerf-ui-analyze`](./docs/ui-analyzer.md) remains available when only static
@@ -199,7 +201,8 @@ the folder modules, and CSS only imports their owner stylesheets.
   optional icon in a `ToolbarControlGroup`, an extra-large `ToolbarText` directly
   in the leading zone, and actions in a trailing group. Supporting copy is
   app-owned content below. Do not create a private heading wrapper or restyle the
-  toolbar.
+  toolbar. A narrow peripheral rail or drawer, where extra-large would truncate
+  at its minimum size, names itself with the default `ToolbarText` size.
 - **Use `Text` for ordinary semantic headings, paragraphs, and inline secondary
   text outside toolbar title zones.** Omit `variant` for the default `p`, pass
   `h1`–`h6` based on the document outline, or use `variant="span"` inside a row,
@@ -262,9 +265,13 @@ the folder modules, and CSS only imports their owner stylesheets.
   still loading, set `placeholder` on the component (`Select`, `ListHeader`,
   `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`,
   `AppTab`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
-  slots as subtle **unanimated** skeleton blocks and interactivity disabled, so a
-  parent composes a faithful loading view (e.g. an inspector) without hand-rebuilding
-  markup. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
+  slots as subtle **unanimated** skeleton blocks and interactivity disabled. Only
+  unknown values change: a placeholder is never dimmed or styled as disabled (a
+  control you disabled keeps its live disabled tone), so a parent composes a
+  faithful loading view (e.g. an inspector) without hand-rebuilding markup.
+  Component-drawn chrome stays live: a `ListItem` or `ListActionRow` keeps its
+  `busy` spinner while its `status` (and a `ListItem`'s `trailing`) content
+  become skeletons. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
   (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
   `LoadingSpinner` for known busy activity instead.
 - **Keep ListItem content inside the row.** The rounded `ListItem` root clips
@@ -318,6 +325,7 @@ shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelTogg
 - [component-contract.md](./docs/component-contract.md): what a component owns vs. what the app owns.
 - [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
 - [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
+- [workbench.md](./docs/workbench.md): the `Workbench` multi-panel shell, its collapse policies, and opt-in `resizable` panels driven by `wireWorkbench` (`@kerfjs/ui/wire-workbench`: drag, keyboard, min/max, persistence, compact suspension), the `mainMinSize` / `mainMinHeight` work-area minimums (default 320px wide beside any inline rail, 120px tall above the drawer) that resizable panels stop at and inline panels shrink around, and a panel's `responsiveOverlayAt` (`narrow` / `compact`, rails and the bottom drawer) that presents it as an overlay below a Workbench container breakpoint without a device-class check; a panel given its `collapsed` signal is a transient overlay (collapsed on entering the breakpoint, takes focus and keeps Tab inside while open, closed by Escape or an outside press, focus returned; `dismissOverlays`), and overlays are exclusive by default (opening one closes the others; `exclusiveOverlays: false` opts out).
 - [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
 - [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
 - [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.52",
+  "version": "5.0.0-beta.54",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -230,6 +230,10 @@
       "types": "./dist/wire-tab-scaffold.d.ts",
       "import": "./dist/wire-tab-scaffold.js"
     },
+    "./wire-workbench": {
+      "types": "./dist/wire-workbench.d.ts",
+      "import": "./dist/wire-workbench.js"
+    },
     "./loading-spinner": {
       "types": "./dist/loading-spinner.d.ts",
       "browser": "./dist/browser/loading-spinner.js",