@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/docs/ui-evaluator.md

@@ -61,6 +61,23 @@ shared container and `data-kui-align-edge` on two or more elements whose logical
 start edges must align. Use `data-kui-scroll-scope` only for an application-owned
 scope that is not a `.kui-pane`.
 
+Target size (`KUI-B050`) measures the area the pointer can actually reach, not
+just the border box. When a control's box is under 44 × 44, the evaluator
+hit-tests outward from its center with `elementFromPoint`, so a transparent hit
+layer (a positioned `::before`/`::after` that receives pointer events, as on the
+`ListHeader` action) counts toward the target, while a pseudo-element with
+`pointer-events: none`, a clipping ancestor, or an overlapping neighbor does
+not. Where the probe reaches the viewport edge it mirrors the opposite side's
+reach; a control whose center is off-screen or covered keeps its border box.
+The diagnostic evidence reports the measured `width`/`height` and the border
+`box`.
+
+Compact density is a documented exception. Inside `[data-density="compact"]` —
+the compact `List`/`ListHeader` family, whose rows are 36px tall — a target
+still needs the full 44px width but only the 36px row height, because a taller
+hit layer would reach into the neighboring row. The evidence's `required` field
+names the floor that applied (`44×44`, or `44×36` in compact density).
+
 Accessible names follow ARIA/native naming inputs, including labels, referenced
 content with `aria-hidden` descendants removed, and native input values.
 Geometry checks use each catalog entry's explicit `boundaries.rootClass`; the

package/docs/ux-demo.md

@@ -1,32 +1,63 @@
 # UX catalog contract
 
-Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
+Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server reloads component source edits without a restart: component entries still load through their `dist/browser` wrappers, so each component's reachable CSS is exercised as consumers receive it, but the JavaScript those wrappers re-export (and every other `@kerfjs/ui` subpath) resolves to `src/`, and CSS resolves to `src/` as well. A component that gains a new CSS dependency needs a restart, because the wrapper listing its stylesheets is regenerated only by the build. Production demo builds, previews, and the browser tests use `dist/`. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
 
-Seven lazy production-composition routes live under the `Recipes` category.
+Every Playwright entry point builds current source before the preview server
+starts. `npm run test:e2e -- tests/browser/row.spec.ts` and a direct focused
+`npx playwright test tests/browser/row.spec.ts` both run catalog generation and
+demo-conformance preflights, build the package and production catalog, then
+launch Chromium, Firefox, and WebKit. The build emits
+`source-freshness.json`; browser coverage compares it with an independent hash
+of the current `src/` and `ux-demo/` inputs, so a stale `dist-demo` cannot pass
+after a route or component edit. `npm run demo:serve` remains a preview-only
+command for an already-built catalog. The demo-conformance preflight also
+rejects a component route that wraps its `CatalogExampleStack` in a card or
+other container (`catalog-demo/wrapped-example-stack`): single-component demos
+sit directly on the catalog grid, and only composition and recipe routes frame
+their content.
+
+Ten lazy production-composition routes live under the `Recipes` category.
 Each `?component=recipe-*` route uses public package primitives, real wiring,
 deterministic state, and semantic layout owners from the [recipe guide](./recipes.md).
 
 - 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 `AppTab` route demonstrates a runtime-filtered domain metadata slot and a decorative replacement close icon without changing TabBar selection, close, reorder, or focus ownership. 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, feedback, and theme scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component.
-- `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. Non-supported Web Awesome recommendations project to a visible `Discouraged` sidebar 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 `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.
+- `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 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 the subtitle in its own aligned row like `PanelHeader`; the current-view heading is also a toolbar. 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 checkerboard belongs to the complete scrollable preview region rather than a nested card. 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 `PanelHeader` title/summary 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 places its header directly on the dialog edge while preserving the header's internal inset, gives the selected project title the complete outer-plus-inner content gutter, lets the value table fill the available detail column between the shared outer margins, and keeps record actions on one outer gutter without an extra content-item inset. Browser geometry coverage protects those relationships at wide and narrow widths.
+- 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.
 - Catalog-only brand marks, preview dimensions, checkerboard tiles, and the compound display-settings control retain local geometry because they are specimen chrome or intrinsic control anatomy rather than reusable application spacing roles.
 - 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 grouped footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
-- Demo-only CSS supplies only the catalog shell and stages; component appearance stays in package CSS. 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. The Web Awesome theme route remains the broad system view, while individual action, form, layout, navigation, feedback, media, and helper routes provide focused specimens; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; PanelHeader demonstrates its plain top-toolbar identity, extra-large title, optional subtitle row, and bordered brand-filled icon group; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges plus a scoped override; TabBar demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
-- Recipe ownership notes are hidden by default. A page-toolbar toggle reveals them as floating warning-toned notes with a folded corner, keeping instructional copy visually distinct and removable from the specimen flow.
-- Settings exercise light/dark, increased contrast, and reduced motion without changing component code. The theme action starts from the operating system's effective color scheme, always names the appearance it will switch to, and installs an explicit light or dark override when activated; contrast and reduced motion expose their independent preferences through `aria-pressed`.
+- 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.
+- 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
+  mixed specimen keeps its connected separator plus the standard 8px dropdown
+  trigger inset, label, and caret inside both pill and rounded group shapes.
+  Avatar images are chrome rather than nested `img`
+  elements: a lone avatar paints the group, while a multi-button avatar group
+  paints only the pressed selection, with contain fitting in both cases. Its
+  collapsible-search specimen follows the selected group shape with a
+  concentric inner radius in both collapsed and expanded states.
+- Recipe ownership notes are hidden by default. A page-toolbar toggle reveals each recipe's note as its `CatalogExample` note above the framed specimen, so instructional copy never covers the composition.
+- Settings exercise light/dark, increased contrast, and reduced motion without changing component code. The theme action starts from the operating system's effective color scheme, always names the appearance it will switch to, and installs an explicit light or dark override when activated; contrast and reduced motion expose their independent preferences through `aria-pressed`. The display-control group wraps whole independent controls at narrow widths so all stay reachable. The adjacent Background menu chooses an 8px-square checkerboard (default), 8px vertical stripes, a layout guide with single-pixel rules at 15px, 23px, and 32px, surface, or sunken for the preview stage. The demo saves all four display choices in browser storage and restores them across entries and reloads. A saved light or dark choice remains explicit when the operating-system appearance changes; without one, the theme follows the system. Invalid or unavailable storage falls back to defaults while the controls remain usable.
 - The footer action log is an `aria-live` region, making interactions visible to both people and browser tests.
 - The focused Toast route calls Web Awesome's documented programmatic stack API and notes that Hot Sheet 2 still uses its own app-level toast implementation; the catalog demonstrates ecosystem support without implying current product adoption.
 - Browser coverage walks every Kerf, composition, and Web Awesome route, checks every listed Web Awesome custom element is registered in its focused specimen, exercises the ecosystem disclosure and both relationship directions, validates offline source/guidance hrefs and accessible wide/narrow/200%-zoom wrapping, and covers tab selection/reordering/overflow, semantic palettes and scoped overrides, light/dark rendering, toolbar popup and responsive find behavior, single/multiline search alignment, menu alignment, banner urgency, keyboard resizing, live custom-element values, and representative wide/narrow captures.
-- The production build keeps the catalog shell and Kerf routes in the entry chunk, then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route, the broad Web Awesome theme route, or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
+- The production build splits the code loaded at startup into three eagerly preloaded chunks behind a tiny entry, so none nears the largest-chunk limit in `demo-bundle-budget.json`: `vendor` (the Web Awesome select and popup-menu registrations with their Lit and Floating UI runtime), `kerf` (the built `@kerfjs/ui` modules and the kerf core, plus every startup stylesheet), and `catalog` (the catalog shell and per-component demo modules). A chunk carries the CSS its modules import, so all startup CSS modules share the `kerf` chunk: the stylesheet stays one file with the cascade order a single-chunk build emits, and the chunk graph stays acyclic (`catalog` imports `kerf`, never the reverse). Only modules statically reachable from the entry qualify, so lazy-only dependencies stay in their lazy chunks. It then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
+
+The focused ListHeader route shows `xs`, `sm`, `m`, `l`, and `xl` labels at one
+semantic heading level. Its default `sm` style still matches `FieldLabel`.
+It also shows simultaneous badge and status indicators, with a conditional
+badge expression that may return `undefined`.
 
-Before handoff, inspect the actual captures for readability, context, alignment, clipping, spacing, responsiveness, focus, and obvious defects. Fix and recapture rather than treating the screenshot as proof by itself.
+Before handoff, inspect the actual captures for readability, context, alignment, clipping, spacing, responsiveness, focus, and obvious defects. Fix and recapture rather than treating the screenshot as proof by itself. Firefox and WebKit screenshots leave out `backdrop-filter`, so translucent chrome looks unblurred in them. Check the blur on a `recordVideo` frame instead (see [Accessibility › Chrome material](accessibility.md#chrome-material)).

package/docs/webawesome-theme.md

@@ -54,12 +54,33 @@ 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
-a single-line control lands at the standard ~40px height and the value sits 9px
-in from the field edge. Each field's top label is inset by that same border +
+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, 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
@@ -68,6 +89,13 @@ 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, 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,
@@ -97,14 +125,101 @@ tiers:
   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.
+  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. 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
+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.12'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.
 
@@ -127,8 +242,7 @@ 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.
 
 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
@@ -153,10 +267,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
 
@@ -165,8 +278,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
@@ -243,15 +357,35 @@ smallest subtree that needs a different identity:
 ```css
 :root {
   --wa-color-brand-fill-loud: #7540a8;
+  --wa-color-brand-on-loud: #ffffff;
   --wa-color-focus: #7540a8;
   --wa-form-control-border-radius: 0.5rem;
 }
 
 .billing-workspace {
   --wa-color-success-fill-loud: #10a86b;
+  --wa-color-success-on-loud: #1d1d1f;
 }
 ```
 
+`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.
+
+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