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

package/docs/component-selection.md

@@ -151,14 +151,14 @@ an upstream component or recipe request.
 | One-pane navigation — `NavStack`                                                                                        | A compact flow pushes into details while keeping earlier views mounted, or a single-pane screen needs the same stable layout contract.                                                                                  | Do not use it when list and detail should remain visible together; use `SplitView`. Do not use it alone for co-equal top-level destinations; use one stack per `TabScaffold` tab.                                                                                                                                                          | Keep the ordered view array controlled, put view-specific bottom chrome on each view (or use the component fallback), import its CSS explicitly, and call `wireNavStack` for back delegation, content-slide/chrome-cross-fade transitions, and focus move/restore. Mark a preferred initial target with `data-nav-focus` when DOM order is insufficient.                                                                                                                                                                                                                                                                                                                                                               | View keys/content/titles, push and pop actions, preferred initial focus targets, and per-view or persistent bottom toolbar content.                      | `@kerfjs/ui/nav-stack`                                                                    | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
 | Responsive list-detail — `SplitView`                                                                                    | A primary list and related detail belong together on roomy devices but become a one-pane drill-down on compact devices.                                                                                                 | Do not use it for a single linear flow or a multi-panel editor shell.                                                                                                                                                                                                                                                                      | Provide controlled selection/detail state and device class; opt into resize wiring only when the separator is user adjustable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Selection, detail content, compact back action, device policy, and optional persisted width.                                                             | `@kerfjs/ui/split-view`                                                                   | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
 | Compact top-level destinations — `TabScaffold`                                                                          | A handset or portrait-tablet app has two to five co-equal destinations whose scenes and nested navigation must remain mounted across switches.                                                                          | Do not use it for document tabs, reorderable work items, or a desktop navigation rail.                                                                                                                                                                                                                                                     | Keep the active id controlled, import its CSS explicitly, and call `wireTabScaffold`; commonly place one `NavStack` in each tab scene.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Destination definitions, active id, routing, persistence, and roomy-device replacement.                                                                  | `@kerfjs/ui/tab-scaffold`                                                                 | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
-| Desktop multi-panel workspace — `Workbench`                                                                             | A desktop-class tool needs a central work area plus independently collapsible navigator, inspector, or console regions.                                                                                                 | Do not shrink the full shell onto compact devices or use it for one standalone panel.                                                                                                                                                                                                                                                      | Render only the required rails/drawer, keep collapse state controlled, and replace peripheral regions with stacks or overlays below desktop sizes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Panel presence/content, collapsed states, sizes, persistence, responsive replacement, and controls.                                                      | `@kerfjs/ui/workbench`                                                                    | [Workbench](./workbench.md)                                                         |
+| Desktop multi-panel workspace — `Workbench`                                                                             | A desktop-class tool needs a central work area plus independently collapsible navigator, inspector, or console regions.                                                                                                 | Do not shrink the full shell onto compact devices or use it for one standalone panel.                                                                                                                                                                                                                                                      | Render only the required rails/drawer, keep collapse state controlled, and replace peripheral regions with stacks or overlays below desktop sizes. Opt a panel into drag/keyboard resizing with `resizable` and call `wireWorkbench` with its size signal.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Panel presence/content, collapsed states, sizes, persistence, responsive replacement, and controls.                                                      | `@kerfjs/ui/workbench`                                                                    | [Workbench](./workbench.md)                                                         |
 | Standalone rail or drawer — `CollapsiblePanel`                                                                          | One left/right rail or bottom drawer needs controlled collapse without adopting the complete `Workbench` shell.                                                                                                         | Do not use it for several coordinated workspace panels or retain an empty icon-only rail while collapsed.                                                                                                                                                                                                                                  | Pair it with `CollapsiblePanelToggle`; call `wireSidebar` for focus transfer, Escape/backdrop dismissal, compact overlay trapping, and persistence integration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Panel content/size, collapsed state, toggle placement, persistence, and compact policy.                                                                  | `@kerfjs/ui/collapsible-panel`                                                            | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
 | Lowered content surface — `SunkenPanel`                                                                                 | A main work area or nested content group needs one visually lowered surface with a compact inset and vertical stack.                                                                                                    | Do not use it merely to add padding, as a replacement for `Pane` anatomy, or around children that already own the same outer surface.                                                                                                                                                                                                      | Compose the application-owned content as children, choose the default `rounded` shape or `square` for a flush edge-to-edge area, and pass `ariaLabel` only when the surface is a distinct named region.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Region semantics, accessible name, shape, scroll ownership, child ordering, and content.                                                                 | `@kerfjs/ui/sunken-panel`                                                                 | [SunkenPanel](./sunken-panel.md)                                                    |
 | Menu composition                                                                                                        | Navigation sections need full-size rows and the same content-item geometry as every other pane.                                                                                                                         | Do not add sidebar-specific wrapper padding, shrink targets to icon size, nest an interactive trailing control in `ListItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract.                                                                                            | Compose `ListHeader`, `ListItem`, and `ListActionRow` in `.kui-content`; use `ListHeader` toggle mode with real controlled content, and use `.kui-content-item` for other surfaces plus a pane footer for toolbar actions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Information architecture, disclosure content and state, responsive drawer/shell behavior, and token overrides.                                           | `@kerfjs/ui/layout.css`                                                                   | [Pane geometry](../README.md#pane-and-content-geometry)                             |
 | Resizable application pane — `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer`                            | A controlled split pane needs the Kerf separator, collapse state, pointer plus keyboard resizing, or a product-specific decorative grip.                                                                                | Do not use it for static equal columns; use `Grid`. Use application CSS grid for static asymmetric or intrinsic tracks. Prefer it over Web Awesome `wa-split-panel` unless that component's distinct API is required. Keep `handleIcon` noninteractive.                                                                                    | Call `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` once and retain its disposer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Size signal, min/max policy, collapse policy, persistence, and optional decorative handle icon.                                                          | `@kerfjs/ui/resizable-region`                                                             | [ResizableRegion contract](./accessibility.md#resizableregion)                      |
 | One application tab — `AppTab`                                                                                          | A controlled app tab needs selection, close, drag, leading/trailing anatomy, compact/segmented/icon-only presentation, label truncation, safe domain metadata, or a product-specific close glyph.                       | Do not render it alone or use it for a small settings choice; compose in `TabBar`, or use `SegmentedControl`. Keep `closeIcon` noninteractive.                                                                                                                                                                                             | Compose in `TabBar`; let `wireTabBars` manage interaction. Put only domain `data-*` values in `rootAttributes`; use typed appearance props instead of descendant CSS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Tab identity, order, selection, close policy, content, domain metadata values, and outer placement.                                                      | `@kerfjs/ui/app-tab`                                                                      | [Tabs contract](./accessibility.md#tabs)                                            |
 | Application tab strip — `TabBar`, `wireTabBars`, `reorderTabs`                                                          | Tabs switch page regions and may overflow, close, reorder, fill a segmented inspector strip, sit beside a trailing action, or keep that adjacent action distinct from a far-edge end action.                            | Do not use it for a compact local view toggle; use `SegmentedControl`. Do not use it for a long choice list; use `Select`. Prefer it over Web Awesome `wa-tab-group`, `wa-tab`, and `wa-tab-panel` for Kerf app tabs.                                                                                                                      | Call `wireTabBars` once, retain the disposer, and apply `onReorder` synchronously; `reorderTabs` is the default array helper. Combine `trailingPlacement="adjacent"` with `end` for split actions; TabBar owns the shrinking/scrolling tab geometry and keeps both actions visible. Choose typed presentation/allocation props while the parent owns outer placement.                                                                                                                                                                                                                                                                                                                                                  | Ordered tabs, selection, panels, routing, closing, persistence, action content, and outer placement.                                                     | `@kerfjs/ui/tab-bar` plus `@kerfjs/ui/wire-tab-bars`                                      | [Tabs contract](./accessibility.md#tabs)                                            |
-| Panel, dialog, or page heading — `Toolbar` + `ToolbarText`                                                              | A panel, dialog, or page needs an extra-large title, optional icon, grouped trailing actions, and optional supporting copy.                                                                                             | Do not add a private heading wrapper or bespoke layout. The toolbar supplies structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior.                                                                                                                                                       | Connect title/supporting-copy ids to the host, group controls, and delegate actions. **For a page or view title set `headingLevel` (usually `1`)** on `ToolbarText`; omit it for a dialog title referenced by `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Open state, focus lifecycle, dismissal, controls, ids, copy, and heading level.                                                                          | `@kerfjs/ui/toolbar` + `@kerfjs/ui/toolbar-text`                                          | [Toolbar headings](./accessibility.md#toolbar-headings)                             |
+| Panel, dialog, or page heading — `Toolbar` + `ToolbarText`                                                              | A panel, dialog, or page needs an extra-large title, optional icon, grouped trailing actions, and optional supporting copy.                                                                                             | Do not add a private heading wrapper or bespoke layout. The toolbar supplies structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior. In a narrow peripheral rail or drawer, where xlarge would truncate at the panel's minimum size, use the default `ToolbarText` size as pane identity.  | Connect title/supporting-copy ids to the host, group controls, and delegate actions. **For a page or view title set `headingLevel` (usually `1`)** on `ToolbarText`; omit it for a dialog title referenced by `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Open state, focus lifecycle, dismissal, controls, ids, copy, and heading level.                                                                          | `@kerfjs/ui/toolbar` + `@kerfjs/ui/toolbar-text`                                          | [Toolbar headings](./accessibility.md#toolbar-headings)                             |
 | Dialog or popup geometry — `DialogSurface`, `PopupSurface`                                                              | Recurring Web Awesome dialogs need standard sizes/presentations/body/footer insets, or dropdown menus need list-compatible inset ownership.                                                                             | Do not use these wrappers as generic layout or to replace native dialog/dropdown behavior. Avoid consumer `::part()` overrides and do not stack a dialog body inset around list-owned child geometry.                                                                                                                                      | Wrap one `wa-dialog` or `wa-dropdown`; choose the typed geometry while retaining native labeling, open state, focus, dismissal, and menu semantics. Compose a dialog body as a `List` by default, use `bodyInset="none"` when its children own list geometry, and wrap bare prose in `ListInsetText`.                                                                                                                                                                                                                                                                                                                                                                                                                  | State, focus lifecycle, dismissal, labels, content, and outer placement.                                                                                 | `@kerfjs/ui/surface-scaffold`                                                             | [Surface scaffolds](./surface-scaffold.md)                                          |
 | Key/value facts — `ValueTable`, `ValueTableRow`                                                                         | Read-only labels and values form a semantic definition list, optionally with a leading icon.                                                                                                                            | Do not use it for editable form fields or a row/column data grid; use native form or table semantics.                                                                                                                                                                                                                                      | Compose typed `ValueTableRow` entries; pass `icon` when a 24px leading icon adds useful context.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Values, formatting, icon meaning, and empty/loading policy.                                                                                              | `@kerfjs/ui/value-table`                                                                  | [Component ownership](./component-contract.md#ownership-boundaries)                 |
 | Indeterminate activity — `LoadingSpinner`                                                                               | A Kerf surface needs compact, labeled or decorative indeterminate progress.                                                                                                                                             | Do not use it for known progress; use Web Awesome `wa-progress-bar` or `wa-progress-ring`. Direct Web Awesome UI may use `wa-spinner`; do not mix spinner systems within one surface.                                                                                                                                                      | None; pass a label when the spinner conveys status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Loading lifecycle and adjacent status copy.                                                                                                              | `@kerfjs/ui/loading-spinner`                                                              | [Accessibility](./accessibility.md#shared-rules)                                    |
@@ -186,12 +186,18 @@ an upstream component or recipe request.
 - A `ResizableRegion` overlay automatically clamps both its track and fixed-size
   animated content to the responsive overlay maximum. Set the policy and maximum
   on the component instead of adding application descendant width/height fixes.
+  It paints `--kui-color-surface` itself (an inline region stays transparent),
+  so do not add a background to make an overlay opaque.
 - Configure application panels through the shared `separator`, `collapseMotion`,
   `contentOverflow`, `presentation`, `restoreControl`, and `restorePosition`
   props on `ResizableRegion`, `Workbench` panels, and `CollapsiblePanel`. These
   cover separator suppression, one-reflow collapse with composited motion,
   bottom-drawer popups, compact overlays or replacements, and safe-area restore
-  placement without descendant `.kui-*` overrides. `wireSidebar` also accepts a
+  placement without descendant `.kui-*` overrides. A `Workbench` rail's
+  or bottom drawer's `responsiveOverlayAt` (like `ResizableRegion`'s
+  `responsiveFillAt`) switches it to an overlay below a container breakpoint
+  without a device-class check.
+  `wireSidebar` also accepts a
   hidden compact replacement and keeps compact overlays exclusive by default.
 - `TokenSearchField` is a structured editor. A native input or `wa-input` is the right answer for ordinary text.
 
@@ -207,8 +213,12 @@ toolbar geometry, hover/pressed treatment, and grouping. `SegmentedControl`,
 **inside** a `ToolbarControlGroup`, not loose in the zone. For a page, panel, or
 dialog heading, put an extra-large `ToolbarText` directly in the leading zone,
 optionally preceded by a grouped icon, and group trailing actions. Keep supporting
-copy below as app-owned content. A bottom divider is enabled by default. Set
-`dividerSides=""` for none, or
+copy below as app-owned content. Size the title to its track: a narrow
+peripheral rail or drawer (a navigator, inspector, or console beside a work
+area that carries the extra-large title, often with its own close control in
+the header) labels itself with the default size, because extra-large truncates
+there — "Inspector" becomes "Ins…" in a 160px rail. A bottom divider is
+enabled by default. Set `dividerSides=""` for none, or
 use the canonical physical-edge combinations (`t`, `r`, `b`, `l`, in that
 order—for example `tr` or `trbl`) when the toolbar owns other separator edges.
 
@@ -216,7 +226,7 @@ Common toolbar patterns:
 
 | Want                          | Put in the zone                                                                        | Notes                                                                                                             |
 | ----------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| Identity or title text        | `<ToolbarText text="…" size="large" />` (or `xlarge` for a page/panel title)           | Wrap in a `single` borderless group only when it must align with adjacent control pills                           |
+| Identity or title text        | `<ToolbarText text="…" size="large" />` (or `xlarge` for a page/panel title that fits) | Wrap in a `single` borderless group only when it must align with adjacent control pills                           |
 | One or more icon/text buttons | `<ToolbarControlGroup>{buttons}</ToolbarControlGroup>`                                 | Use `buttonAppearance="push"` for toggle buttons with `aria-pressed`; `single` for a lone control                 |
 | An exclusive view switch      | `<ToolbarControlGroup><SegmentedControl … /></ToolbarControlGroup>`                    | Not `TabBar`, which switches tabpanels                                                                            |
 | A value list                  | `<ToolbarControlGroup><Select … /></ToolbarControlGroup>`                              | Register `@kerfjs/ui/select/register` once; use `focusRingOwner="group"` so focus follows the group's geometry    |

package/docs/document-baseline.md

@@ -25,6 +25,10 @@ height shell. Ordinary document-flow pages can import the baseline without the
 class. Do not put `.kui-app-root` on several sibling containers: each requests
 the full available document height.
 
+`kui-app-root` is the public class of the component catalog's
+`document-baseline` entry, so `kerf-ui-doctor` and the
+`kerfjs/ui-public-boundaries` ESLint rule accept it (no KUI-L101 finding).
+
 The stylesheet is intentionally absent from `@kerfjs/ui/styles.css` and every
 component browser import because its global selectors would otherwise change
 consumer documents implicitly. Import it once and load application overrides

package/docs/layout.md

@@ -153,7 +153,11 @@ document content, not toolbar identity: use `Text` with the `h2`–`h6` variant
 the outline calls for (inside a `List` with `controlInsets`, its text lines up
 with content items). Use `ListHeader` when the section is a list or menu group
 that needs a count, badge, action, or disclosure, and keep extra-large
-`ToolbarText` for the panel, dialog, or page title.
+`ToolbarText` for the panel, dialog, or page title. A narrow peripheral rail or
+drawer is the exception that proves the rule: beside a work area that already
+carries the extra-large title, its header names the pane with the default size,
+because extra-large would truncate there ("Inspector" becomes "Ins…" in a 160px
+rail) and pane identity should stay quiet.
 
 Presentation is independent of the native element: use `tone="quiet"` for
 supporting copy, `tone="danger"` for error or validation copy, `size="compact"`

package/docs/recipes.md

@@ -166,9 +166,11 @@ standalone `CollapsiblePanel`s (`@kerfjs/ui/collapsible-panel`) driven by
 standard per-side glyph: a collapse toggle lives inside each panel, and the
 panel's expand toggle shows only while it is collapsed, so exactly one control
 owns each action and a collapsed panel is still reachable. The rail's expand
-toggle sits in the always-visible main header; the drawer's floats in a
-`FloatingToolbar` at the bottom edge the drawer opens from, next to where the
-action happens. `wireSidebar` owns the toggle delegation, moves focus into a
+toggle sits in the always-visible main header; the drawer's is a
+`FloatingToolbar` passed as the drawer's own `restoreControl`, which the panel
+floats in its column's safe-area-aware bottom-end corner, next to where the
+drawer opens — do not hand-roll a conditional floating control beside the
+panel. `wireSidebar` owns the toggle delegation, moves focus into a
 panel on open, restores it on close (to the trigger, or to the panel's expand toggle when
 the trigger sits inside the collapsed panel), and — when a `deviceClass()` reports
 `compact` — presents the panels as a dismissable **overlay** (backdrop, Escape

package/docs/type-contracts.md

@@ -69,7 +69,8 @@ ordinary source/type gates:
   `FloatingToolbar`, `Pane`, `ResizableRegion`, `SegmentedControl`, `StateBanner`,
   `SunkenPanel`, `ToolbarText`, `CollapsiblePanel`, `Catalog`, and the wire helpers;
 - required controlled-state callbacks on `wireResizableRegions`, `wireTabBars`,
-  and `wireTabScaffold`;
+  and `wireTabScaffold`, and the required app-owned size signals on
+  `wireWorkbench`;
 - mutually exclusive count/badge metadata on `ListHeader`; and
 - protected application metadata boundaries on `AppTab`, `ListItem`,
   `ListActionRow`, `ListHeader`, `Pane`, `CatalogExample`, and

package/docs/ui-analyzer.md

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

package/docs/ui-doctor.md

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

package/docs/ux-demo.md

@@ -18,7 +18,7 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 
 - It imports public component subpaths, exercising their browser-selected reachable CSS rather than a catalog-only style path.
 - The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
-- The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, pending, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding, closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
+- The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, pending, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding (a new tab opens `pending` with a spinner and stays selectable while its panel shows a `Skeleton` heading until a simulated load completes), closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
 - Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, and feedback scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component. The former aggregate Web Awesome theme specimen is intentionally omitted because its component families are covered by those focused routes.
 - `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Functional groups follow their authored importance order; components precede compositions inside each group, equal-importance entries use alphabetical order, and the Recipes group comes last. Composition names stay concise and project a visible `Composition` sidebar tag. Non-supported Web Awesome recommendations project to a visible `Discouraged` tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
 - Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.

package/docs/webawesome-theme.md

@@ -292,19 +292,28 @@ smallest subtree that needs a different identity:
 ```css
 :root {
   --wa-color-brand-fill-loud: #7540a8;
+  --wa-color-brand-on-loud: #ffffff;
   --wa-color-focus: #7540a8;
   --wa-form-control-border-radius: 0.5rem;
 }
 
 .billing-workspace {
   --wa-color-success-fill-loud: #10a86b;
+  --wa-color-success-on-loud: #1d1d1f;
 }
 ```
 
 The shipped theme pairs every `--wa-color-{variant}-fill-loud` with an
 `--wa-color-{variant}-on-loud` that clears WCAG AA (4.5:1) in both color
-schemes. When you override a loud fill, override its `on-loud` alongside it if
-the pair no longer clears 4.5:1 (for example, white text on a bright fill).
+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