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

package/docs/webawesome-migration.md

@@ -0,0 +1,82 @@
+# Moving an application off Web Awesome
+
+Kerf UI no longer needs Web Awesome. Every Kerf component renders native
+elements and reads only `--kui-*` tokens, so an application built only from
+Kerf components installs nothing else. Web Awesome remains an optional
+[integration](./component-selection.md#web-awesome-integration) for an
+application that wants one of its specialized elements.
+
+This guide moves an existing application from the Web Awesome elements Kerf
+now replaces to the Kerf components, then, if nothing else needs it, removes
+Web Awesome entirely.
+
+## 1. Replace each element
+
+Work one element type at a time. Each Kerf component takes typed props, emits
+standard DOM events, and keeps its state in native form controls, so a
+delegated `input` / `change` / `click` handler usually keeps working once the
+selector changes.
+
+For a positive action such as Price Check, migrate `<wa-button variant="success">` to `<Button tone="success">`. The semantic success palette also applies to `secondary` and `plain` emphasis; use the component prop rather than an application color override.
+
+| Web Awesome markup                                            | Kerf replacement                                                                                                                                                            | Notes                                                                                                                                                                                             |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<wa-button variant="brand">Save</wa-button>`                 | `<Button tone="brand" action="save">Save</Button>` (`@kerfjs/ui/button`)                                                                                                    | `tone` replaces `variant`; `emphasis` replaces `appearance`. Use `href` for a link button, `icon` with `ariaLabel` and no label for an icon-only one, and `pressed` for a toggle.                 |
+| `<wa-input label="Name" hint="…" with-clear>`                 | `<TextField label="Name" hint="…" clearable />` (`@kerfjs/ui/text-field`)                                                                                                   | Call `wireTextFields(root)` from `@kerfjs/ui/wire-text-fields` once for the clear button and a live `showCount`. Pass `error` for an invalid field.                                               |
+| `<wa-textarea rows="4" resize="auto">`                        | `<TextField multiline rows={4} maxRows={10} />`                                                                                                                             | `maxRows` grows the field with its content up to that height.                                                                                                                                     |
+| `<wa-checkbox>Email me</wa-checkbox>`                         | `<Checkbox label="Email me" action="toggle-email" />` (`@kerfjs/ui/checkbox`)                                                                                               | For a mixed parent, pass `indeterminate` and call `wireCheckboxes(root)` from `@kerfjs/ui/wire-checkboxes` once.                                                                                  |
+| `<wa-checkbox-group label="Notifications">`                   | `<CheckboxGroup label="Notifications" name="channels" value={channels.value} choices={[…]} />` (`@kerfjs/ui/checkbox-group`), or `ChoiceChips` with `multiple="toggle"`     |                                                                                                                                                                                                   |
+| `<wa-radio-group label="Density"><wa-radio value="compact">…` | `<RadioGroup label="Density" name="density" value={density.value} choices={[{ value: 'compact', label: 'Compact' }]} />`                                                    | `@kerfjs/ui/radio-group`. Use `orientation="horizontal"` for a row. Use `SegmentedControl` for a view switch and `ChoiceChips` for wrapping pills.                                                |
+| `<wa-switch>Live updates</wa-switch>`                         | `<Switch label="Live updates" checked={live.value} action="toggle-live" />` (`@kerfjs/ui/switch`)                                                                           | Only for a setting that applies immediately; use `Checkbox` for a submitted option.                                                                                                               |
+| `<wa-select>` with `<wa-option>` children                     | `<Select label="Status" name="status" value={status.value} choices={[…]} />` (`@kerfjs/ui/select`)                                                                          | Import `@kerfjs/ui/select/register` once. It emits standard `input` and `change` events.                                                                                                          |
+| `<wa-dropdown>` with `<wa-dropdown-item>` commands            | `<PopupMenu label="More Actions" icon={…} items={[{ label: 'Archive', action: 'archive' }]} />` (`@kerfjs/ui/popup-menu`)                                                   | Import `@kerfjs/ui/popup-menu/register` once. A dropdown that picks a value becomes a `Select`.                                                                                                   |
+| `<wa-dialog label="Edit">` and toggling `open`                | `<DialogSurface id="edit" label="Edit" footer={…}>…</DialogSurface>` with `openDialog(dialog)` / `closeDialog(dialog)`                                                      | From `@kerfjs/ui/surface-scaffold`. The surface is a native `<dialog>`; listen for its native `close` event instead of `wa-after-hide`. Never toggle the `open` attribute.                        |
+| `<wa-drawer>`                                                 | `<DialogSurface presentation="side-sheet" …>` (or `"bottom-sheet"`), or `CollapsiblePanel` for a collapsible rail                                                           |                                                                                                                                                                                                   |
+| `<wa-tab-group>`, `<wa-tab>`, `<wa-tab-panel>`                | `TabBar` with `wireTabBars` (`@kerfjs/ui/tab-bar`), or `SegmentedControl` for compact local views                                                                           | The application owns its panels.                                                                                                                                                                  |
+| `<wa-tag with-remove>`                                        | `<Chip removeAction="remove-tag">Design</Chip>` (`@kerfjs/ui/chip`)                                                                                                         |                                                                                                                                                                                                   |
+| `<wa-badge>`, `<wa-spinner>`, `<wa-skeleton>`                 | `Badge`, `LoadingSpinner`, `Skeleton`                                                                                                                                       |                                                                                                                                                                                                   |
+| `<wa-icon name="…">`                                          | `<LucideIcon icon={Star} name="star" />` (`@kerfjs/ui/lucide-icon`)                                                                                                         |                                                                                                                                                                                                   |
+| `<wa-split-panel>`                                            | `ResizableRegion` with `wireResizableRegions`                                                                                                                               |                                                                                                                                                                                                   |
+| `<wa-card>`                                                   | `<ContentItem appearance="surface" frame="framed">` (`@kerfjs/ui/content-item`), or `SunkenPanel` for a lowered region                                                      |                                                                                                                                                                                                   |
+| `<wa-page>`                                                   | `Workbench`, `SplitView`, `NavStack`, or `TabNavigator`                                                                                                                     |                                                                                                                                                                                                   |
+| `<wa-details>`, `<wa-accordion>`, `<wa-accordion-item>`       | `<Disclosure title="…">` (`@kerfjs/ui/disclosure`)                                                                                                                          | Give Disclosures the same `name` for an accordion. The open state is native: set `element.open = false` to close one from code.                                                                   |
+| `<wa-slider>`                                                 | `<Slider id="…" label="…" value={…} />` (`@kerfjs/ui/slider`)                                                                                                               | Add `showValue`/`unit` for a readout and `ticks` for stops; call `wireSliders(root)` once.                                                                                                        |
+| `<wa-tag-input>`                                              | `<TagField id="…" label="…" tags={…} name="…" />` (`@kerfjs/ui/tag-field`)                                                                                                  | Call `wireTagFields(root, { onChange })` once and re-render with the reported tags.                                                                                                               |
+| `<wa-color-picker>`                                           | `<ColorField id="…" label="…" value={…} />` (`@kerfjs/ui/color-field`)                                                                                                      |
+| `<wa-include src="…">`                                        | `resource()` from `kerfjs/async`, rendering the result as Kerf content                                                                                                      | Never inject fetched markup; it bypasses kerf's `SafeHtml` escaping.                                                                                                                              |
+| `<wa-scroller>`                                               | A `Pane` (scroll edges via `wireScrollDividers`) or `ColumnTrack` for a horizontal track                                                                                    |                                                                                                                                                                                                   |
+| `<wa-button-group>`                                           | `ToolbarControlGroup` or `SplitButton` for actions, `SegmentedControl` for a choice                                                                                         |                                                                                                                                                                                                   |
+| `<wa-progress-bar value="40">`, `<wa-progress-ring>`          | `<ProgressBar label="…" value={0.4} />` (`@kerfjs/ui/progress-bar`) or `<ProgressRing label="…" value={0.4} />` (`@kerfjs/ui/progress-ring`)                                | Omit `value` for indeterminate progress; `valueText` replaces the spoken percentage.                                                                                                              |
+| `<wa-popover>`, `<wa-popup>`                                  | `openAnchoredSurface(anchor, render, { label })` (`@kerfjs/ui/anchored-surface`); `positionAnchored()` or `autoReposition()` from `kerfjs/overlay` to place another element | `openAnchoredSurfaceAt` anchors to the pointer.                                                                                                                                                   |
+| `<wa-tooltip>`                                                | `tooltip()` from `kerfjs/overlay` with `@kerfjs/ui/overlay-tooltip.css` imported                                                                                            | Icon-only toolbar and popup controls already get Kerf help tags. Pass `exitClass: 'kui-tooltip-exit'` with `exitDuration: 100`.                                                                   |
+| `<wa-callout>`                                                | `<StateBanner tone="warning" …>` (`@kerfjs/ui/state-banner`)                                                                                                                |                                                                                                                                                                                                   |
+| `<wa-toast>`, `<wa-toast-item>`                               | `toast()` from `kerfjs/overlay` with `@kerfjs/ui/overlay-toast.css` imported                                                                                                | Pass `variant` for a tone, a `StateBanner` as the content for a title and detail, and `exitClass: 'kui-toast-exit'` with `exitDuration: 200`. A persistent status stays a `StateBanner` in place. |
+
+Event and selector changes to look for:
+
+- Replace listeners for Web Awesome events (`wa-change`, `wa-input`,
+  `wa-show`, `wa-after-hide`) with the standard events the native controls
+  emit (`change`, `input`, `toggle`, `close`).
+- Replace selectors that name a `wa-*` tag with the component's `data-action`
+  or a stable application attribute passed through `rootAttributes`.
+- Delete application CSS that styled `wa-*` parts with `::part()`; configure the
+  Kerf component through its props instead.
+
+`npx kerf-ui-doctor` and the `eslint-plugin-kerfjs` `recommended-ui` rules flag
+remaining `Discouraged` elements.
+
+## 2. Remove Web Awesome
+
+Once no `wa-*` element remains in the application:
+
+1. Delete every `@awesome.me/webawesome/dist/components/…` registration import.
+2. Delete the `@kerfjs/ui/webawesome.css` import and any
+   `import type {} from "@kerfjs/ui/webawesome"` line.
+3. Remove `@awesome.me/webawesome` from `package.json`.
+4. Keep `@kerfjs/ui/foundation.css` (or your theme entry). Its tokens fall back
+   to the same values the Web Awesome theme gave them, so the application
+   renders identically.
+
+If the application keeps a few specialized elements (Tree, Carousel, Rating,
+and so on), keep steps 1–3 only for those elements; the integration's theme
+bridge keeps them visually consistent with Kerf.

package/docs/webawesome-theme.md

@@ -1,13 +1,37 @@
 # Web Awesome theme contract
 
-`@kerfjs/ui/webawesome.css` is the optional bridge between Web Awesome 3.12's
+`@kerfjs/ui/webawesome.css` is the optional bridge between Web Awesome 3's
 free components and the Kerf/Hot Sheet 2 design system.
 
+**Optional by design.** No Kerf component needs Web Awesome or this bridge.
+`@awesome.me/webawesome` is an optional peer, and `@kerfjs/ui/webawesome.css`
+(with the type-only `@kerfjs/ui/webawesome`) is the only entry that touches
+it. `foundation.css` has no `wa-*` selectors; its tokens may read a Web
+Awesome theme variable (`--kui-font-m: var(--wa-font-size-m, 16px)`), so an
+app's Web Awesome theme also restyles Kerf, but every such read falls back to
+the value this theme gives it. A Kerf-only application therefore renders
+exactly like the catalog. Kerf component stylesheets read only `--kui-*`
+tokens; the few rules that place a raw `wa-*` child inside a Kerf container
+match nothing when Web Awesome is absent. The consumer-bundle tests and the
+`webawesome-optional` browser spec enforce all of this.
+
+**Supported versions.** `@kerfjs/ui` supports every Web Awesome 3.x release
+from 3.14 (its optional peer range is `^3.14.0`). No Kerf component patches
+Web Awesome's internals any more: `PopupMenu`, `Select`, and `DialogSurface`
+draw their own native controls, so an upgrade within 3.x reaches only this
+theme and the Web Awesome elements an application renders itself. The
+package's own tests run against 3.14.0 (the lockfile), and CI's
+`ui-webawesome-latest` job runs the ui unit and Chromium browser suites
+against the newest 3.x (`npm run test:webawesome-latest`). That job reports,
+rather than fails on, elements a newer Web Awesome adds that the catalog has
+not reviewed yet, and a demo bundle over the budget recorded for the lockfile;
+a cataloged element that disappears upstream still fails.
+
 ```ts
-import type {} from '@kerfjs/ui/webawesome';
-import '@kerfjs/ui/webawesome.css';
-import '@awesome.me/webawesome/dist/components/button/button.js';
-import '@awesome.me/webawesome/dist/components/input/input.js';
+import type {} from "@kerfjs/ui/webawesome";
+import "@kerfjs/ui/webawesome.css";
+import "@awesome.me/webawesome/dist/components/button/button.js";
+import "@awesome.me/webawesome/dist/components/input/input.js";
 ```
 
 The type-only package import augments `kerfjs/jsx-runtime` with the 70
@@ -54,6 +78,218 @@ pointer targets. Override `--kui-wa-carousel-icon-size`,
 `--kui-wa-carousel-dot-hit-size` on a carousel or containing scope when a
 product needs different geometry.
 
+Code text uses Kerf's named monospace stack, `--kui-font-mono`
+(`ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono",
+monospace`), and the theme points `--wa-font-family-code` at it. Web Awesome's
+own `ui-monospace, monospace` renders the generic face (Courier on macOS) in
+Chromium, which does not recognize `ui-monospace`; because the generic
+`monospace` ends any stack, Kerf's token owns the stack rather than appending
+fallbacks after Web Awesome's. Override `--kui-font-mono` to change code text in
+both Kerf and Web Awesome components.
+
+Form fields carry the same content-item inset as the Kerf primitives: a 1px
+border with 8px inside it (`--wa-form-control-border-width`,
+`--wa-form-control-padding-block`, and `--wa-form-control-padding-inline` are set
+to the `--kui-layout-item-border-width` / `--kui-layout-item-padding` values), so
+the value sits 9px in from the field edge. Native buttons and fields, plus Web
+Awesome buttons and fields, use the 12px `--kui-layout-rounded-radius` through
+`--wa-form-control-border-radius`; explicit pill and circular shapes retain
+their own radius. Default-size single-line controls
+share Kerf's 44px control height — the height of a Kerf `Select`, a toolbar
+group, and a list row — so a `wa-input` or `wa-button` sits flush beside a Kerf
+`Select`. The theme sets `--wa-form-control-height` to `2.75em` (44px at the
+16px default) on Button, Color Picker, Input, Known Date, Number Input, Radio
+Group, Select, Tag Input (its box's minimum height), Textarea (its minimum
+height), and Time Input, so `size="large"` scales proportionally while `size="small"` keeps Web Awesome's compact secondary
+height. The token is scoped to those controls rather than the root because Web
+Awesome also derives tag, copy-button, and toast geometry from it. Buttons
+inside a `ToolbarControlGroup` keep the group's 40px (32px compact) control
+height. Each field's top label is inset by that same border +
+padding (9px) so it lines up with the value inside the field, and is styled
+exactly like a `ListHeader` label — uppercase, `--kui-font-xs`, weight 650, quiet
+foreground. This applies to every free field that exposes a top label
+(`::part(form-control-label)` plus the Slider's `::part(label)`). OTP Input
+exposes `label` instead of `form-control-label`; the theme gives it the same
+uppercase 12px/650 treatment. Inline control labels (Checkbox, Switch) keep
+their natural sentence case.
+
+On coarse touch devices, the editable part of small and extra-small Web Awesome
+Input, Number Input, Tag Input, Time Input, Textarea, and Select has a 16px
+minimum text size. Small field chrome keeps its compact height and desktop
+typography stays small. This prevents Safari from magnifying the page just to
+focus text; it does not constrain a user's own pinch zoom. App-owned native fields need the same
+editable-text audit.
+
+Known Date's field captions and bordered text-like field hints use the same 9px
+inline inset, keeping secondary text aligned with the value rather than the
+field's outer border. This covers Input, Known Date, Number Input, OTP Input,
+Select, Tag Input, Textarea, and Time Input hints.
+OTP Input's label and hint both use the 9px field-text inset. Its code cells
+render whole in a shrink-to-fit host (a start-aligned grid or flex item):
+upstream caps the segments' focus-ring-padded box at the host's width, which
+there is the cells' width minus that padding and so clipped the last cell's
+inline-end edge, and the theme caps it at the host's width plus the padding its
+negative margins reserve. A host narrower than the code still scrolls its
+segments; the `contained` appearance keeps upstream's cap.
+
+Checkbox Group, Radio Group, and Color Picker follow Kerf's `Checkbox`,
+`RadioGroup`, and `ColorField`: the control region stays flush, so each box,
+circle, or swatch trigger sits on the host's inline-start edge, while the label
+and hint use the same 9px text column as field labels. Stacked checkboxes and
+radios therefore share one control column with Kerf's own toggle controls;
+place the group where you would place a Kerf `Checkbox` or `RadioGroup` rather
+than adding margin to its parts. Stacked
+default-appearance Radios sit 8px apart (`0.25em` block margins instead of Web
+Awesome's `0.375em`, the first and last radio still flush), so a Radio Group
+keeps the same 28px pitch as a Kerf `RadioGroup` and a Checkbox Group's 8px
+gap; horizontal and button radios keep Web Awesome's spacing.
+
+Bordered fields (Input, Known Date, Number Input, OTP Input, Select, Tag
+Input, Textarea, and Time Input) and Switch likewise draw their border or
+track on the host's inline-start edge, exactly where Kerf's `TextField`, `Select`, and `Switch`
+draw theirs, with the label and hint on the same 9px text column. Place a Web
+Awesome field where you would place the Kerf field it stands in for, so a mixed
+form shares one border column and one text column; the UX catalog gives these
+specimens the same `inline-control` alignment as the Kerf field demos. Tag
+Input is Discouraged in favor of Kerf's `TagField`, but an application that
+still renders it gets the same label, hint, height, and border placement as the
+other bordered fields.
+
+Slider's complete interactive region receives the
+shared 8px logical inline outer inset through `::part(slider)`, keeping its
+track, markers, references, and hint together without moving the label. Placed
+where a Kerf `Slider` goes, its label and track land on the Kerf Slider's text
+column.
+
+Known Date and Slider size to their container rather than to their content, so
+give them a width (a form column, or the container's full width) instead of a
+shrink-to-fit parent, where Known Date collapses to nothing and Slider to a
+stub. The UX catalog gives Known Date a compact field column and Slider the
+Kerf Slider demo's medium width.
+
+Non-field chrome follows explicit, overridable control, surface, and container
+tiers:
+
+- `--kui-wa-control-inset` defaults to the 8px content-item padding. It applies
+  to tabs, tree-item trailing content, tags, and dropdown items. Tree selection
+  also uses Kerf's 8px inline outer margin, so its background reads as an inset
+  list item instead of an edge-to-edge stripe. Buttons already consume the same
+  `--wa-form-control-padding-inline` 8px value at every size, so no extra part
+  override is needed.
+- `--kui-wa-surface-margin` and `--kui-wa-surface-inset` default to 8px.
+  Accordion, Card, Details, Callout, and Include use the margin around their
+  complete surface and the inset within it. Accordion applies the outer margin
+  once to the group rather than separating connected items; Card's header,
+  body, and footer all receive the full inset.
+- Plain Details use the 8px `--kui-wa-surface-inset` on the trigger and keep the
+  body flush; plain Accordion items use that 8px inset on both trigger and body.
+  Outlined and sunken Details use the 16px `--kui-wa-container-inset` on the
+  trigger and the 8px surface inset on the body, while framed Accordion items
+  use the 16px container inset for both regions.
+- `appearance="sunken"` is a Kerf theme extension for Accordion, Card, and
+  Details. It removes raised chrome, paints the shared sunken surface
+  (`--kui-sunken-surface`: the lowered semantic color with the same fine grain
+  texture as every Kerf sunken surface), and uses the shared rounded-rectangle
+  radius. The texture is generated by the first Kerf sunken component that
+  renders; a page with only Web Awesome sunken surfaces calls
+  `ensureSunkenTexture()` once. Override
+  `--kui-wa-sunken-background` or `--kui-wa-sunken-radius` on an instance or
+  containing scope when that surface needs different tokens.
+- `--kui-wa-container-inset` defaults to the 16px homogeneous-group step. Tab
+  Panel retains this roomier tier for unframed panel content. Dialog body uses
+  the 8px surface inset, while its footer uses the 16px container inset so
+  content stays compact and the action group has a clearer boundary. These two
+  parts do not inherit the dialog's shared `--spacing` value.
+
+## Contextual transparency
+
+The lowered surface, neutral quiet/normal fills, and neutral borders are
+translucent shared theme colors. The foundation mirrors them when Web Awesome
+is absent. Nested SunkenPanel, Pane, and Web Awesome sunken surfaces therefore
+composite on their actual backdrop without application-owned depth wrappers
+or component-token overrides.
+
+The lowered tint is `--wa-color-surface-lowered` in the Web Awesome theme and
+`--kui-color-surface-lowered` in the Kerf foundation fallback;
+`--wa-color-neutral-fill-quiet` and `--kui-color-neutral-fill-quiet` share it.
+`SunkenPanel`, sunken Pane, Workbench, and TabNavigator surfaces read it by
+default through the optional `--kui-sunken-panel-background` override. Web
+Awesome Accordion, Card, and Details with `appearance="sunken"` read it
+through the optional `--kui-wa-sunken-background` override. These names do
+not denote separate opaque colors or distinct depth levels. A deliberate
+nested surface adds another translucent layer and can make hierarchy clearer;
+avoid painting a second background on a wrapper that represents the same
+surface. Inspect the composed result over the real backdrop in light and dark
+modes.
+
+The lowered light tint is `rgb(0 0 98.076923 / 0.05098)` (approximately
+`#f2f2f7` over white); dark is `rgb(228.157895 228.157895 255 / 0.07451)`
+(approximately `#111113` over black). Repeated layers darken in light mode
+and brighten in dark mode. The same value is used at every depth; there is no
+arbitrary third-level cap. Neutral normal fills and borders use alpha values
+chosen to retain their former single-layer appearance over the default surface.
+Their painted result adapts to other backgrounds. Neutral on-quiet text uses
+`#626267` / `#c2c2c6` to retain AA contrast across the tested layered catalog
+surfaces.
+
+Default/raised surfaces remain opaque canvas and overlay anchors. The optional
+document baseline paints an opaque default surface on `html` and one lowered
+layer on `body`. Normal/quiet foregrounds, focus indicators, and loud neutral
+fills remain opaque for legible controls. Colored semantic fill/border tokens
+also remain opaque pending their separate contrast evaluation. Transparency
+is not a guarantee of contrast on an arbitrary photograph or infinitely nested
+surface; applications must verify their actual composition and keep text and
+interactive controls on suitable surfaces.
+
+The catalog demonstrates three directly nested panels, a sunken Pane containing
+a panel, and a Web Awesome card containing details, using public components and
+no demo stylesheet. Browser tests cover repeated layers, actual compositing,
+text contrast, light/dark switching, narrow/wide layouts, and forced colors.
+
+The built-in close control of a `wa-dialog` or `wa-drawer` matches a borderless
+single `ToolbarControlGroup` button, the close a toolbar-composed dialog uses
+(see the list-detail dialog recipe): a 40px circle with no border and the
+neutral hover fill, in place of Web Awesome's 35px rounded square. The theme
+sizes it through the directly exported `close-button__base` part, so the
+default header and a toolbar-composed header present one close affordance.
+
+Add `class="hide-actions"` to a `wa-dialog` when the dialog supplies its own
+dismissal affordance and should omit Web Awesome's header action region. The
+theme sets `display: none` on the directly exported `header-actions` part; it
+does not attempt to chain `::part()` through the internal `dialog` and `header`
+parts, which CSS shadow parts do not support.
+
+Badge remains intentionally compact at Web Awesome's intrinsic `0.375em` block /
+`0.625em` inline padding (4.5px / 7.5px at its default 12px text size): it is a
+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 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,
+or `--kui-wa-badge-accent-foreground` for a reviewed accent foreground.
+Breadcrumb has no bordered or filled container, and Scroller delegates item chrome
+to its slotted children, so both retain their upstream geometry. Web Awesome
+3.14's free catalog has
+`wa-dropdown-item`, but no `wa-menu-item`; the theme therefore styles the
+supported dropdown item rather than carrying a dead selector.
+
+Override a tier for a product scope after importing the theme:
+
+```css
+.roomy-editor {
+  --kui-wa-control-inset: 0.75rem;
+  --kui-wa-surface-margin: 0.75rem;
+  --kui-wa-surface-inset: 0.75rem;
+  --kui-wa-container-inset: 1.5rem;
+}
+```
+
 Accordion, Details, Breadcrumb, and Kerf Select share
 `--kui-disclosure-icon-scale` (default `.5`) so disclosure and traversal
 chevrons keep the same visual weight. The Accordion and Details components
@@ -62,8 +298,12 @@ their open state uses the independent `rotate` property.
 
 That scale applies to each Web Awesome component's intrinsic glyph and is
 independent of Kerf `DisclosureArrow`, whose default box is 18px relative to
-the root font size and whose consumer override is
-`--kui-disclosure-arrow-size`.
+the root font size and whose consumer override is its typed `size` prop.
+
+A loading step that is also the active `wa-stepper` step draws its spinner in
+the marker's on-accent foreground. Upstream colors that spinner with the same
+accent that fills an active marker, which would leave a blank disc; the theme
+corrects it through the public `spinner` part.
 
 Tooltip and Popover use arrowless floating surfaces by default, matching Hot
 Sheet 2. The theme sets Web Awesome's public `--wa-tooltip-arrow-size` token to
@@ -73,12 +313,12 @@ subtree, or for one instance after the theme import:
 
 ```css
 :root {
-  --wa-tooltip-arrow-size: .375rem;
-  --kui-wa-popover-arrow-size: .375rem;
+  --wa-tooltip-arrow-size: 0.375rem;
+  --kui-wa-popover-arrow-size: 0.375rem;
 }
 
 .pointed-popover {
-  --arrow-size: .5rem;
+  --arrow-size: 0.5rem;
 }
 ```
 
@@ -88,10 +328,9 @@ component should declare the no-arrow choice independent of theme context.
 The UX catalog includes a focused, addressable specimen for every component in
 this list. Because these are themed ecosystem components rather than
 first-class `@kerfjs/ui` exports, the sidebar keeps them under a collapsible
-`Web Awesome` heading with category subgroups. The aggregate theme route
-remains a broad visual-regression surface, while modal, drawer, toast, media,
-and helper routes make their own behavior inspectable without opening every
-state at once.
+`Web Awesome` heading with category subgroups. There is no aggregate theme
+route: the focused modal, drawer, toast, media, and helper routes make each
+component's behavior inspectable without opening every state at once.
 
 ## Badge and tag guidance
 
@@ -100,8 +339,9 @@ generic Kerf wrappers around them. Their variants and appearances already read
 the semantic palette above, and importing their component modules remains
 independent and tree-shakeable.
 
-- Use `wa-badge pill` for compact status, count, or activity labels. Hot Sheet
-  2's pill-shaped ticket status treatment is the reference shape.
+- Use `wa-badge pill appearance="filled"` for compact status, count, or activity
+  labels. Hot Sheet 2's quiet, contrast-safe pill-shaped ticket status treatment
+  is the reference shape.
 - Use the default, non-pill `wa-tag` for categories, filters, and removable
   selections. Its medium-radius rounded rectangle keeps tags distinct from
   status badges. Handle the bubbling `wa-remove` event in the feature that owns
@@ -139,54 +379,73 @@ static content and labels that constraint next to the rendered output.
 
 ## Component selection guidance
 
-The catalog lists every free Web Awesome component so support can be inspected;
-listing does not make each component the preferred Kerf application pattern.
-The [need-first decision matrix](./component-selection.md#web-awesome-overlap-policy)
-is the exhaustive Kerf/Web Awesome overlap index; the rules below explain the
-highest-risk choices.
-
-- Consider `wa-popup` for low-level anchored positioning when its flip, shift,
-  or placement behavior avoids custom positioning code. Prefer the higher-level
-  Tooltip or Popover when their interaction semantics already fit.
-- For ordinary app value selection, use Kerf `Select` instead of directly
-  composing Web Awesome Dropdown, Dropdown Item, Select, or Option. Kerf Select
-  owns the compact spacing and disclosure-arrow treatment while registering
-  only its reachable Web Awesome dependencies. Use an action-menu pattern only
-  when the choices truly perform commands rather than select a value.
-- Avoid Web Awesome Button Group as a general visual pattern. Use controlled
-  `SegmentedControl` for a small exclusive choice set, including lightweight
-  view selection inside an inspector. Reserve Button Group for an exceptional
-  grouped-action requirement that is not a selection.
-- Prefer `TabBar` for reorderable or horizontally overflowing application tabs,
-  and `SegmentedControl` for compact local views, instead of Web Awesome Tab,
-  Tab Group, and Tab Panel.
+The catalog lists every free Web Awesome component so an integration
+application can inspect support; listing does not make any of them the
+preferred Kerf pattern. Kerf components and native elements come first. The
+[integration table](./component-selection.md#web-awesome-integration) names the
+Kerf choice for every overlapping element, and the
+[migration guide](./webawesome-migration.md) shows how to move an existing
+application off them.
+
+- Elements a Kerf component replaces are tagged `Discouraged` in the catalog:
+  Button, Dropdown, Dropdown Item, Button Group, Input, Textarea, Tag,
+  Checkbox, Checkbox Group, Radio, Radio Group, Switch, Select, Option,
+  Dialog, Drawer, Card, Page, Callout, Popover, Popup, Tab, Tab Group, Tab
+  Panel, Badge, Spinner, Skeleton, Toast, Toast Item, Tooltip, Details, Accordion,
+  Accordion Item, Progress Bar, Progress Ring, Slider, Tag Input, Color Picker,
+  Split Panel, Icon, Scroller, Include, and Zoomable Frame.
+  Never render them in application markup. Popover and Popup give way to
+  `AnchoredSurface` and `kerfjs/overlay`'s `positionAnchored()`; Tooltip,
+  Toast, and Toast Item give way to `kerfjs/overlay`'s `tooltip()` and
+  `toast()` with their Kerf stylesheets.
 - Use Web Awesome Tree, Tree Item, Animated Image, and Comparison only for a
   specific product requirement that needs their specialized behavior.
-- Avoid Web Awesome Zoomable Frame and Icon. Use application-owned media
-  presentation and Kerf `LucideIcon`, respectively.
-- Prefer Kerf `ResizableRegion` over Web Awesome Split Panel for Hot Sheet-style
-  application panes. It provides the persistent 1px separator, hover/focus
-  grip, accessible keyboard and pointer resizing, controlled size, collapse
-  support, and application-owned persistence. Use Split Panel only when its
-  distinct Web Awesome API is itself required.
+- Use the remaining supported elements (Carousel, Rating, and
+  the rest of the coverage list) when their native semantic contract matches
+  the product need and the application has adopted the integration.
 
 ## Customization
 
-Load application overrides after the package theme, or scope them to the
-smallest subtree that needs a different identity:
+To change the brand, set Kerf's opt-in `--kui-color-brand` on `:root`: the
+theme derives `--wa-color-brand-fill-loud`, `--wa-color-brand-on-quiet`, and
+`--wa-color-focus` from it (with the matching Kerf tokens) at AA-safe
+lightness, so brand text and the focus ring follow the new hue. See
+[Brand color](./component-selection.md#brand-color).
+
+For anything else, load application overrides after the package theme, or
+scope them to the 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: .5rem;
+  --wa-form-control-border-radius: 0.5rem;
 }
 
 .billing-workspace {
   --wa-color-success-fill-loud: #10a86b;
+  --wa-color-success-on-loud: #1d1d1f;
 }
 ```
 
+Kerf components read only `--kui-*` tokens. `SearchField` with
+`presentation="form-field"` follows `--kui-layout-rounded-radius` for its
+corners, as `TextField`, `Select`, and `Button` do, so the fields in a form
+change together.
+
+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-dialog.md

@@ -0,0 +1,88 @@
+# Workbench dialog
+
+`@kerfjs/ui/workbench-dialog` is the modal form of a `Workbench`: a work area
+with side rails (layers, an inspector) inside a dialog. It is one of three
+dialog types:
+
+| Type                                                                | Use it for                                               |
+| ------------------------------------------------------------------- | -------------------------------------------------------- |
+| `DialogSurface` ([surface-scaffold.md](surface-scaffold.md))        | One pane: a title, a body, and footer buttons.           |
+| `ListDetailDialog` ([list-detail-dialog.md](list-detail-dialog.md)) | Pick a record from a list and show its detail beside it. |
+| `WorkbenchDialog` (this page)                                       | An editing task with side panels.                        |
+
+```tsx
+import { deviceClass } from "@kerfjs/ui/device-class";
+import { openDialog, WorkbenchDialog } from "@kerfjs/ui/workbench-dialog";
+import { wireWorkbench } from "@kerfjs/ui/wire-workbench";
+
+const device = deviceClass();
+const layersHidden = signal(false);
+
+<WorkbenchDialog
+  id="edit-slide"
+  label="Edit Slide"
+  title="Edit Slide"
+  compact={device.value.compact}
+  main={<SlideCanvas />}
+  mainBottomToolbar={{ label: "Slide Actions", trailing: <SaveButtons /> }}
+  leftRail={{
+    label: "Layers",
+    collapsed: layersHidden.value,
+    toolbar: {
+      label: "Layers",
+      title: <ToolbarText text="Layers" />,
+      toggle: { action: "toggle-layers", name: "Layers" },
+    },
+    content: <LayerList />,
+  }}
+/>;
+
+wireWorkbench(root, {
+  id: "edit-slide-workbench",
+  panels: { leftRail: { collapsed: layersHidden } },
+});
+openDialog(document.getElementById("edit-slide"));
+```
+
+## Layout
+
+The dialog draws no surface header and no body inset. Its body is a
+`Workbench` (`<id>-workbench`):
+
+- **The work area's toolbar** carries the dialog's primary title (an xl
+  level-2 heading, id `<id>-title`) with an optional `description` (id
+  `<id>-description`, the dialog's accessible description), any
+  `leading` groups, the `actions`, and the close control. Close stays the
+  outermost trailing control, after a hidden right rail's toggle.
+- **The rails** (`leftRail`, `rightRail`) keep their own toolbars, with
+  default-size titles, and run the dialog's full height. A hidden rail's
+  toggle relocates into the work area's toolbar.
+- **The bottom** of the work area takes `mainFooter` and a
+  `mainBottomToolbar` for the dialog's buttons; `bottomDrawer` adds a drawer
+  under the work area.
+
+## Compact devices
+
+Pass `compact` from `deviceClass().value.compact`. The dialog fills the
+screen, and each rail presents as an overlay over the work area instead of
+narrowing it. Start the rails collapsed on compact devices; their toolbar
+toggles show them. With `wireWorkbench` and each rail's `collapsed` signal,
+an open rail takes focus, keeps Tab inside it, and closes on Escape or a press
+outside it. Escape closes an open rail before the dialog sees it; a second
+Escape closes the dialog.
+
+## Props
+
+- `id`, `label` (required): identity and the dialog's accessible name.
+- `title` (required), `description`, `leading`, `actions`.
+- `describedBy`: the id of other content, such as summary copy in `main`,
+  that describes the dialog in place of `description`.
+- `main` (required), `mainFooter`, `mainBottomToolbar`.
+- `leftRail`, `rightRail`, `bottomDrawer`: `WorkbenchPanel`s.
+- `compact`, `closeLabel` (default `Close`), `lightDismiss`.
+- Roomy sizing: `size` (default `large`), `preferredWidth`, `height` (default
+  560px), `maxHeight`, `viewportGutter`, and `mainMinSize`.
+- `rootAttributes`, `className`, `slot`.
+
+Open and close it like any dialog surface with `openDialog()` and
+`closeDialog()`, which this module re-exports.