@kerfjs/ui 5.0.0-beta.104 → 5.0.0-beta.106

package/docs/ui-doctor.md

@@ -146,7 +146,7 @@ capitalization rule in [Writing interface copy](./writing.md#capitalization).
 Names of commands, controls, views, and fields use title style, following
 Apple's guidance. `KUI-D040` (warning) reports a string or template literal
 passed to a known title-style prop that leaves a word lowercase where title style
-capitalizes it. For example, `<wa-button>Save draft</wa-button>` should be
+capitalizes it. For example, `<Button>Save draft</Button>` should be
 "Save Draft", and `<ListHeader label="Needs attention" />` should be "Needs
 Attention". The action names the repaired label.
 
@@ -166,7 +166,8 @@ covers these string literals:
   declared in the same file;
 - `SegmentedControl`, `Select`, and `TabNavigator` choice and tab labels;
 - `NavStack` view titles and `backText`, and `SplitView` `backLabel`;
-- `FieldLabel` text and the static text of a `button` or `wa-button`;
+- `FieldLabel` text and the static text of a `Button`, `button`, or
+  `wa-button`;
 - the `name` of a panel toolbar's `toggle: { action, name }` object literal
   (Workbench panels, `CollapsiblePanel`), which names the toggle group and
   completes its "Show …" / "Hide …" label;
@@ -180,11 +181,14 @@ covers these string literals:
   configuration declared in the same file; and the `aria-label` of a
   `section`, `nav`, `aside`, `main`, `header`, `footer`, `form`, or `search`
   element or an element with a landmark `role`;
-- the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or
-  `wa-radio-group`, which is a field or group label;
+- field and group labels: the `label` and `ariaLabel` of `TextField`,
+  `Select`, and `RadioGroup`, and the `label` of a raw `wa-input`,
+  `wa-select`, `wa-textarea`, or `wa-radio-group` in an application using the
+  optional Web Awesome integration;
 - the accessible names of icon-only controls, which the rule also gives title
-  style: `IconButton` and `IconToggleButton` `label`, `PopupMenu` `label`,
-  `SplitButton` `optionsLabel`, `TokenSearchField` `clearLabel`, and the
+  style: an icon-only `Button`'s `ariaLabel`, `PopupMenu` `label`,
+  `SplitButton` `optionsLabel`, `SearchField` and `TextField`
+  `clearLabel`, and the
   `aria-label` of a `button` or `wa-button` whose only content is an icon. A
   button with visible text is judged by that text, never by its `aria-label`.
 
@@ -199,6 +203,7 @@ The check is deliberately one-directional, to keep false positives rare:
   is. A word joined to an interpolation (`` `${count}s` ``) is skipped.
 - It ignores other dynamic values and every sentence-style surface: descriptions,
   details, placeholders, tooltips, status text, and option text, including
+  `Checkbox` and `Switch` labels, `RadioGroup` choice labels, and
   `wa-checkbox`, `wa-switch`, and `wa-radio` labels. It does not read
   `LoadingSpinner` or `Skeleton` labels, which announce a status.
 - It skips tokens containing digits, code, paths, or URLs, and lowercase-led

package/docs/ux-demo.md

@@ -33,12 +33,12 @@ 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's Run Tests row composes a trailing `PopupMenu` (`trailingMenu`) with Edit and Delete commands, revealed on interaction, that also opens at the pointer when the row's primary button is right-clicked.
 - 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 `PopupMenu` route's context example opens one app-owned menu either at the row's right-click point or below its adjacent, keyboard-operable Demand Actions button. The Nested Decisions example shows the automatic phone-width submenu placement above or below its parent list, with native ArrowLeft return, Escape dismissal, and child selection.
-- 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 pinned leading-tab specimen uses native strip scrolling so momentum and the final tab's end position remain natural; `snapTabs` stays an opt-in for applications that want whole-tab settling. 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.
+- The `PopupMenu` route's context example opens one app-owned menu either at the row's right-click point or below its adjacent, keyboard-operable Demand Actions button. The Nested Decisions example shows the automatic phone-width submenu placement above or below its parent list, with ArrowLeft return, Escape dismissal, and child selection.
+- The `TabBarItem` and `TabBar` routes are focused component specimens: TabBarItem 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 pinned leading-tab specimen uses native strip scrolling so momentum and the final tab's end position remain natural; `snapTabs` stays an opt-in for applications that want whole-tab settling. 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.14 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.
-- The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 15 discouraged choices. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
+- The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 47 discouraged choices, every element a Kerf component replaces. A `Show Discouraged` switch at the top of the open section lists them; it is off by default, so the section leads with the elements an integration application may still use, and a direct `?component=` route to a discouraged entry still lists that entry. The 73 optional-integration components live in a separate `Web Awesome Integration` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
 - The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with supporting copy in its own aligned row; the current-view heading is also a toolbar. The shared Catalog sidebar includes a filter for entry and heading names that works across first-party and ecosystem sections, including collapsed sections. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The preview stage sits directly in the sunken main Pane, with its canvas padded by the medium spacing token. The stage fills the preview scroller for short specimens and grows with taller ones; every background choice follows that same shared behavior in this demo and in consumers. The checkerboard belongs to that stage, rather than a viewport-height wrapper or nested card, and one explicitly repeated SVG tile keeps the pattern continuous through below-fold content. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
 - The composer-form recipe demonstrates one coherent visible form surface with toolbar title/supporting-copy hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
 - The list-detail dialog recipe is laid out like a `Workbench` on roomy devices: a headerless `DialogSurface` modal whose `SplitView` holds a full-height list sidebar `Pane` with its own toolbar beside a full-height detail `Pane` that carries the primary xl title, the `data-dialog="close"` control, and the record actions in its footer. Compact devices get a full-screen sheet with its own labeled header, footer actions, and a list-to-detail drill-down. Browser geometry coverage protects those relationships at wide and narrow widths.
@@ -46,8 +46,8 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - The menu composition route demonstrates toolbar/content/footer anatomy, 24px major gaps, 8/1/8 child geometry, the full-width `ListHeader` count-or-badge/action split, logical-end 44px action targets with 18px visuals, and 44px row/header/toolbar targets. Its one chevron is a production 18px `DisclosureArrow` inside a controlled Tools header that actually reveals and hides content; ordinary Projects navigation has no false disclosure affordance. Browser assertions cover stable naming, expanded/content transitions, visual rotation, node identity, reduced motion, RTL alignment and containment, and wide, narrow, dark, and 200% layouts. The focused ListHeader route separately shows the shared neutral count pill for Attachments, Notes (including zero), and Duplicates plus a non-count legacy badge, full-width logical-end actions, and no disclosure without content.
 - 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 left-aligned 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, 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.
+- Focused demos ship no local stylesheets, inline styles, or styling-only class names. They compose Kerf components first and ordinary semantic HTML for the remainder; a non-discouraged Web Awesome element appears only where neither fits. 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 left-aligned 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 registrations needed by its popup specimen, and keeps an open PopupMenu's state across Kerf rerenders; the Toolbar route composes a collapsible SearchField 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; SearchField 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-migration.md

@@ -0,0 +1,80 @@
+# 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.
+
+| 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>`                                         | `Checkbox` rows in a `List`, 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,8 +1,32 @@
 # 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";
@@ -219,7 +243,7 @@ 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.12's free catalog has
+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.
 
@@ -244,6 +268,11 @@ 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 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
 `0px` and maps each popover's public `--arrow-size` property from
@@ -318,36 +347,30 @@ 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
 
@@ -368,11 +391,10 @@ smallest subtree that needs a different identity:
 }
 ```
 
-`TokenSearchField` with `presentation="form-field"` uses
-`--wa-form-control-border-radius` for its control corners and
-`--wa-form-control-required-content-color` and
-`--wa-form-control-required-content-offset` for its required marker. These
-tokens keep it aligned with a neighboring `wa-input` when a form theme changes.
+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

package/docs/workbench-dialog.md

@@ -0,0 +1,85 @@
+# 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`, 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`.
+- `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.

package/docs/workbench.md

@@ -95,8 +95,9 @@ an optional `label`. Common shell behavior is configured rather than restyled:
 - `collapseMotion: "slide" | "fade-slide" | "none"` keeps the track change
   instant while choosing composited content motion;
 - `contentOverflow: "clip" | "auto" | "visible"` chooses the resting overflow
-  policy. An open descendant `PopupMenu` or Web Awesome dropdown temporarily
-  releases rail/drawer clipping and raises its popup layer automatically;
+  policy. A `PopupMenu` opens in the browser top layer, which no clipping
+  reaches; an open raw Web Awesome dropdown temporarily releases rail/drawer
+  clipping and raises its popup layer automatically;
 - `presentation: "inline" | "overlay" | "hidden"` supports compact overlays
   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,
@@ -232,9 +233,12 @@ While a panel is closed, marked groups follow their open-panel zone order
 | Panel         | Where they go                                                                                                   |
 | ------------- | --------------------------------------------------------------------------------------------------------------- |
 | Left rail     | The leading edge of `mainToolbar`, before its `title`                                                           |
-| Right rail    | The trailing edge of `mainToolbar`, after its `trailing` groups, so the toggle is the toolbar's last group      |
+| Right rail    | The trailing edge of `mainToolbar`, after its `trailing` groups and before any `end` groups                     |
 | Bottom drawer | The trailing edge of `mainBottomToolbar`; without one, a `FloatingToolbar` in the work area's bottom-end corner |
 
+`mainToolbar.end` takes groups that stay outermost, after a closed right
+rail's toggle, such as a dialog's close control (`WorkbenchDialog` uses it).
+
 A rail with no `mainToolbar` floats its groups in its corner the same way, so
 a closed panel can always be reopened. An open overlay panel carries its own
 toggle, so it never depends on a control it covers. An app's own
@@ -612,9 +616,9 @@ collapse slides it out at the resized width. A collapsed,
 overlay, or hidden region is not resizeable. Together these policies replace
 app CSS for separator suppression, instant-track/composited-content collapse,
 popup overflow, mobile overlay/hidden replacement, resize-transition guards,
-and safe-area restore placement. A descendant `PopupMenu` or Web Awesome
-dropdown with `open` releases clipping for its lifecycle, so menu events need
-not rerender the region. The app still owns the other signals and decides when
+and safe-area restore placement. A descendant `PopupMenu` shows in the top
+layer, and a raw Web Awesome dropdown with `open` releases clipping for its
+lifecycle, so menu events need not rerender the region. The app still owns the other signals and decides when
 each policy applies.
 
 ## Public styling boundary

package/docs/writing.md

@@ -105,7 +105,7 @@ interpolated value keeps its own spelling. The covered props are:
 - `PopupMenu` `text` and item and heading labels, including submenus;
 - `SegmentedControl`, `Select`, and `TabNavigator` choice and tab labels;
 - `NavStack` view titles and `backText`, and `SplitView` `backLabel`;
-- `FieldLabel` text and the text of a `button` or `wa-button`;
+- `FieldLabel` text and the text of a `Button`, `button`, or `wa-button`;
 - the `name` of a panel toolbar's `toggle: { action, name }`;
 - region and landmark names: the `label` of `Pane`, `Workbench`, `Toolbar`,
   `ToolbarControlGroup`, `TabBar`, `NavStack`, `CollapsiblePanel`,
@@ -114,15 +114,17 @@ interpolated value keeps its own spelling. The covered props are:
   inside `Workbench`, `CollapsiblePanel`, and `NavStack` configuration, and
   the `aria-label` of a landmark element (`section`, `nav`, `aside`, `main`,
   `header`, `footer`, `form`, `search`) or landmark role;
-- the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or
-  `wa-radio-group`;
-- the accessible names of icon-only controls: `IconButton` and
-  `IconToggleButton` `label`, `PopupMenu` `label`, `SplitButton`
-  `optionsLabel`, `TokenSearchField` `clearLabel`, and the `aria-label` of a
+- field and group labels: the `label` (or `ariaLabel`) of `TextField`,
+  `Select`, and `RadioGroup`, and, in an application using the optional Web
+  Awesome integration, the `label` of a raw `wa-input`, `wa-select`,
+  `wa-textarea`, or `wa-radio-group`;
+- the accessible names of icon-only controls: an icon-only `Button`'s `ariaLabel`, `PopupMenu` `label`, `SplitButton`
+  `optionsLabel`, `SearchField` and `TextField` `clearLabel`, and the `aria-label` of a
   `button` or `wa-button` whose only content is an icon.
 
-The check never judges sentence-style surfaces (including `wa-checkbox`,
-`wa-switch`, and `wa-radio` option text and the `LoadingSpinner` and
+The check never judges sentence-style surfaces (including `Checkbox` and
+`Switch` labels, `RadioGroup` choice labels, `wa-checkbox`, `wa-switch`, and
+`wa-radio` option text and the `LoadingSpinner` and
 `Skeleton` status labels), interpolated or other dynamic values, or text
 ending with `.`, `!`, or `?`. It skips a word joined to an interpolation, tokens containing digits, code, or paths, and
 lowercase-led brands such as iOS. It does not report capitalized short words,

package/doctor/copy-capitalization-checks.mjs

@@ -14,7 +14,8 @@ import { isUiTraversalExcluded } from '../traversal-exclusions.mjs';
 // to known title-style props are read (a template literal's static words, never
 // its interpolated values), so prose, descriptions, placeholders, tooltips,
 // checkbox/switch option text, status lines, LoadingSpinner and Skeleton
-// labels, and dynamic data are never judged. The check reports lowercase words title style capitalizes; it
+// labels, Checkbox/Switch labels and RadioGroup choice labels, and dynamic
+// data are never judged. The check reports lowercase words title style capitalizes; it
 // does not report capitalized short words, because Apple capitalizes a
 // preposition of any length inside a phrasal verb ("Log In to the Server").
 
@@ -156,9 +157,9 @@ const titleStyleProps = new Map([
   ['StateBanner', { props: ['title'] }],
   ['SplitButton', { props: ['label', 'optionsLabel'] }],
   ['Combobox', { props: ['label'] }],
-  ['IconButton', { props: ['label'] }],
-  ['IconToggleButton', { props: ['label'] }],
-  ['TokenSearchField', { props: ['clearLabel'] }],
+  // An icon-only Button is named by ariaLabel; its visible text is read below.
+  ['Button', { props: ['ariaLabel'] }],
+  ['SearchField', { props: ['clearLabel'] }],
   // NavStack view titles and backText, plus the stack's region name and each
   // view's toolbar and pane region names.
   [
@@ -174,7 +175,14 @@ const titleStyleProps = new Map([
   ['SplitView', { props: ['backLabel'] }],
   ['PopupMenu', { props: ['text', 'label'], entries: { items: ['label'] } }],
   ['SegmentedControl', { entries: { choices: ['label'] } }],
-  ['Select', { entries: { choices: ['label'] } }],
+  [
+    'Select',
+    { props: ['label', 'ariaLabel'], entries: { choices: ['label'] } },
+  ],
+  // Field and group labels. A Checkbox or Switch label and a RadioGroup
+  // choice label are option text, which is sentence style and not read.
+  ['TextField', { props: ['label', 'ariaLabel', 'clearLabel'] }],
+  ['RadioGroup', { props: ['label', 'ariaLabel'] }],
   ['TabNavigator', { entries: { tabs: ['label'] } }],
   // Region and landmark names: the accessible name of a pane, toolbar,
   // control group, list, tab bar, or layout region names it, so it is title
@@ -235,9 +243,10 @@ const landmarkRoles = new Set([
   'form',
   'search',
 ]);
-// A raw Web Awesome field's or radio group's `label` is a field label. The
-// option text of `wa-checkbox`, `wa-switch`, and `wa-radio` is sentence style
-// and is not read.
+// A raw Web Awesome field's or radio group's `label` (in an application using
+// the optional integration) is a field label. The option text of
+// `wa-checkbox`, `wa-switch`, and `wa-radio` is sentence style and is not
+// read.
 const fieldLabelTags = new Set([
   'wa-input',
   'wa-select',
@@ -245,7 +254,7 @@ const fieldLabelTags = new Set([
   'wa-radio-group',
 ]);
 const titleToolbarTextSizes = new Set(['xlarge', 'xlarge-fixed', 'large']);
-const buttonTags = new Set(['button', 'wa-button']);
+const buttonTags = new Set(['button', 'wa-button', 'Button']);
 const titleSlots = new Set(['title', 'leading', 'header']);
 const statusToolbarTextSizes = new Set(['small', 'xsmall']);