@kerfjs/ui 5.0.0-beta.7 → 5.0.0-beta.70

package/docs/webawesome-theme.md

@@ -4,10 +4,10 @@
 free components and the Kerf/Hot Sheet 2 design system.
 
 ```ts
-import type {} from '@kerfjs/ui/webawesome';
-import '@kerfjs/ui/webawesome.css';
-import '@awesome.me/webawesome/dist/components/button/button.js';
-import '@awesome.me/webawesome/dist/components/input/input.js';
+import type {} from "@kerfjs/ui/webawesome";
+import "@kerfjs/ui/webawesome.css";
+import "@awesome.me/webawesome/dist/components/button/button.js";
+import "@awesome.me/webawesome/dist/components/input/input.js";
 ```
 
 The type-only package import augments `kerfjs/jsx-runtime` with the 70
@@ -54,6 +54,189 @@ pointer targets. Override `--kui-wa-carousel-icon-size`,
 `--kui-wa-carousel-dot-hit-size` on a carousel or containing scope when a
 product needs different geometry.
 
+Code text uses Kerf's named monospace stack, `--kui-font-mono`
+(`ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono",
+monospace`), and the theme points `--wa-font-family-code` at it. Web Awesome's
+own `ui-monospace, monospace` renders the generic face (Courier on macOS) in
+Chromium, which does not recognize `ui-monospace`; because the generic
+`monospace` ends any stack, Kerf's token owns the stack rather than appending
+fallbacks after Web Awesome's. Override `--kui-font-mono` to change code text in
+both Kerf and Web Awesome components.
+
+Form fields carry the same content-item inset as the Kerf primitives: a 1px
+border with 8px inside it (`--wa-form-control-border-width`,
+`--wa-form-control-padding-block`, and `--wa-form-control-padding-inline` are set
+to the `--kui-layout-item-border-width` / `--kui-layout-item-padding` values), so
+the value sits 9px in from the field edge. 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
+(`::part(form-control-label)` plus the Slider's `::part(label)`). OTP Input
+exposes `label` instead of `form-control-label`; the theme gives it the same
+uppercase 12px/650 treatment. Inline control labels (Checkbox, Switch) keep
+their natural sentence case.
+
+On coarse touch devices, the editable part of small and extra-small Web Awesome
+Input, Number Input, Time Input, Textarea, and Select has a 16px minimum text
+size. Small field chrome keeps its compact height and desktop typography stays
+small. This prevents Safari from magnifying the page just to focus text; it does
+not constrain a user's own pinch zoom. App-owned native fields need the same
+editable-text audit.
+
+Known Date's field captions and bordered text-like field hints use the same 9px
+inline inset, keeping secondary text aligned with the value rather than the
+field's outer border. This covers Input, Known Date, Number Input, OTP Input,
+Select, Textarea, and Time Input hints; unbordered group hints retain their own
+natural geometry. OTP Input's label and hint both use the 9px field-text inset.
+
+Checkbox Group and Radio Group option regions receive the shared 8px inline
+outer inset through `::part(form-control-input)`. Unlike bordered fields, these
+groups have no shell of their own, so the explicit margin places their controls
+on the same content-item geometry without adding padding to each option. The
+Color Picker trigger receives the same 8px inline outer inset because it also
+has no bordered field shell. Slider's complete interactive region receives the
+shared 8px logical inline outer inset through `::part(slider)`, keeping its
+track, markers, references, and hint together without moving the label.
+
+Non-field chrome follows explicit, overridable control, surface, and container
+tiers:
+
+- `--kui-wa-control-inset` defaults to the 8px content-item padding. It applies
+  to tabs, tree-item trailing content, tags, and dropdown items. Tree selection
+  also uses Kerf's 8px inline outer margin, so its background reads as an inset
+  list item instead of an edge-to-edge stripe. Buttons already consume the same
+  `--wa-form-control-padding-inline` 8px value at every size, so no extra part
+  override is needed.
+- `--kui-wa-surface-margin` and `--kui-wa-surface-inset` default to 8px.
+  Accordion, Card, Details, Callout, and Include use the margin around their
+  complete surface and the inset within it. Accordion applies the outer margin
+  once to the group rather than separating connected items; Card's header,
+  body, and footer all receive the full inset.
+- Plain Details use the 8px `--kui-wa-surface-inset` on the trigger and keep the
+  body flush; plain Accordion items use that 8px inset on both trigger and body.
+  Outlined and sunken Details use the 16px `--kui-wa-container-inset` on the
+  trigger and the 8px surface inset on the body, while framed Accordion items
+  use the 16px container inset for both regions.
+- `appearance="sunken"` is a Kerf theme extension for Accordion, Card, and
+  Details. It removes raised chrome, paints the lowered semantic surface, and
+  uses the shared rounded-rectangle radius. Override
+  `--kui-wa-sunken-background` or `--kui-wa-sunken-radius` on an instance or
+  containing scope when that surface needs different tokens.
+- `--kui-wa-container-inset` defaults to the 16px homogeneous-group step. Tab
+  Panel retains this roomier tier for unframed panel content. Dialog body uses
+  the 8px surface inset, while its footer uses the 16px container inset so
+  content stays compact and the action group has a clearer boundary. These two
+  parts do not inherit the dialog's shared `--spacing` value.
+
+## Contextual transparency
+
+Keep the shared `--kui-color-*` semantic fills, foregrounds, and borders opaque
+by default. Their light and dark values mirror the Web Awesome theme, and the
+contrast checks in `tests/browser/tone-contrast.spec.ts` assume known surfaces.
+Compositing those tokens over arbitrary app backgrounds changes text contrast
+and makes the same token mean a different visible color in each container.
+
+The strongest candidate for transparency is a **component-scoped sunken
+background**, through the existing `--kui-sunken-panel-background` and
+`--kui-wa-sunken-background` overrides. A simple black overlay of 5.5% over
+white approximates `#f1f1f1`, near the current light lowered surface; a second
+nesting level becomes `#e4e4e4`. Matching the current dark lowered surface from
+`#1c1c1e` takes about 39% black, and a second layer becomes near-black
+`#0a0a0b`. An alpha that works for one level therefore needs a separate nesting
+rule or a lighter dark treatment before it can become a default. The existing
+opaque `--kui-color-surface-lowered` remains appropriate for page backgrounds.
+
+| Candidate                             | Finding                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Selected `ListItem` fill and border   | A translucent brand layer would preserve a tinted or textured backdrop. Keep it in the component's existing `--kui-list-item-selected-*` overrides: making the shared brand fill translucent would also affect components that put `--kui-color-brand-on-fill` text on it. A 16% brand overlay gives about 4.35:1 for that text over the light lowered surface and 3.99:1 over a warm `#eee7dc` surface, below the 4.5:1 text target. |
+| `ToolbarControlGroup` fill and border | A light 10% black layer approximates the current fill over white, and a dark 13% white layer approximates it over the dark surface. On a warm `#eee7dc` backdrop, the light layer puts the existing quiet text at about 3.31:1. Its dark tone already uses a translucent fill. Keep default control chrome opaque until a backdrop matrix validates its text, icons, borders, and selected state.                                     |
+| Quiet or disabled text and icons      | Keep normal and quiet text/foreground tokens opaque; alpha changes their contrast with every backdrop. Disabled controls may use component-owned opacity, as they do now, without weakening shared foreground tokens.                                                                                                                                                                                                                 |
+| Dividers and borders                  | Decorative separators can use scoped alpha over a known surface. Control boundaries and focus indicators need reliable contrast; do not replace the shared border or focus tokens with alpha globally.                                                                                                                                                                                                                                |
+
+### Bounded translucent prototype
+
+The opt-in catalog prototype (`SunkenPanel` → Backdrop-aware prototype) uses
+the existing public background overrides on `SunkenPanel`, `Pane`, and Web
+Awesome sunken Card/Details. It does not change shared semantic tokens or
+component defaults. The application assigns a depth class to each
+application-owned wrapper; the component inside inherits its public color
+override:
+
+| Depth            | Light tint  | Dark tint   | Treatment                                       |
+| ---------------- | ----------- | ----------- | ----------------------------------------------- |
+| First            | 5.5% black  | 12% black   | Shows the backdrop through the lowered surface. |
+| Second           | 3.5% black  | 5% black    | Adds a smaller inset step.                      |
+| Third and deeper | transparent | transparent | Caps accumulated darkening.                     |
+
+Over default white, the light levels approximate `#f1f1f1` then `#e9e9e9`;
+over dark default `#1c1c1e`, they approximate `#19191a` then `#171719`.
+The dark lowered backdrop reaches roughly `#0f0f11` then `#0e0e10`, which is
+still visually close to black. Warm and textured backdrops retain their tone
+and pattern; the first and second layers remain discernible in light mode but
+are subtle in dark mode. These values are sRGB estimates; actual rendering
+depends on backdrop and browser.
+
+The browser matrix covers one and two layers on default, lowered, warm, and
+two textured stripe colors in light and dark, across Chromium, Firefox, and
+WebKit. It composites computed text and control colors with each tint and
+requires at least 4.5:1 for panel text, an opaque button, Card text, and
+Details text. It also checks a visible focus outline with forced colors and
+the third layer's transparent cap. Theme colors must finish transitioning
+before contrast is measured. The prototype keeps controls on opaque semantic
+surfaces for predictable contrast.
+
+Keep this treatment opt-in. It needs explicit depth assignment, and the dark
+lowered case has too little separation to replace the opaque default. A
+future default would need a stronger depth and contrast rule for arbitrary
+backdrops, especially dark textures and nested mixed components.
+
+Add `class="hide-actions"` to a `wa-dialog` when the dialog supplies its own
+dismissal affordance and should omit Web Awesome's header action region. The
+theme sets `display: none` on the directly exported `header-actions` part; it
+does not attempt to chain `::part()` through the internal `dialog` and `header`
+parts, which CSS shadow parts do not support.
+
+Badge remains intentionally compact at Web Awesome's intrinsic `0.375em` block /
+`0.625em` inline padding (4.5px / 7.5px at its default 12px text size): it is a
+short status or count, not a content item. A badge with `appearance="filled"` or
+`appearance="filled-outlined"` uses its variant's quiet fill with normal text by
+default so every shipped semantic variant meets WCAG AA for that small text;
+filled-outlined keeps its normal variant border. Accent badges keep their loud
+fills and their variant's `on-loud` foreground, which the theme sets to clear AA
+on that fill in both themes: white on the light brand (`#0075db`) and danger
+(`#eb0005`) fills, dark text on the success and warning fills and on the pale
+dark-mode brand and danger fills.
+Override
+`--kui-wa-badge-filled-background` and `--kui-wa-badge-filled-foreground` on a
+badge or containing scope when a product needs a different contrast-safe pair,
+or `--kui-wa-badge-accent-foreground` for a reviewed accent foreground.
+Breadcrumb has no bordered or filled container, and Scroller delegates item chrome
+to its slotted children, so both retain their upstream geometry. Web Awesome
+3.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.
+
+Override a tier for a product scope after importing the theme:
+
+```css
+.roomy-editor {
+  --kui-wa-control-inset: 0.75rem;
+  --kui-wa-surface-margin: 0.75rem;
+  --kui-wa-surface-inset: 0.75rem;
+  --kui-wa-container-inset: 1.5rem;
+}
+```
+
 Accordion, Details, Breadcrumb, and Kerf Select share
 `--kui-disclosure-icon-scale` (default `.5`) so disclosure and traversal
 chevrons keep the same visual weight. The Accordion and Details components
@@ -62,8 +245,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
@@ -73,12 +255,12 @@ subtree, or for one instance after the theme import:
 
 ```css
 :root {
-  --wa-tooltip-arrow-size: .375rem;
-  --kui-wa-popover-arrow-size: .375rem;
+  --wa-tooltip-arrow-size: 0.375rem;
+  --kui-wa-popover-arrow-size: 0.375rem;
 }
 
 .pointed-popover {
-  --arrow-size: .5rem;
+  --arrow-size: 0.5rem;
 }
 ```
 
@@ -88,10 +270,9 @@ component should declare the no-arrow choice independent of theme context.
 The UX catalog includes a focused, addressable specimen for every component in
 this list. Because these are themed ecosystem components rather than
 first-class `@kerfjs/ui` exports, the sidebar keeps them under a collapsible
-`Web Awesome` heading with category subgroups. The aggregate theme route
-remains a broad visual-regression surface, while modal, drawer, toast, media,
-and helper routes make their own behavior inspectable without opening every
-state at once.
+`Web Awesome` heading with category subgroups. There is no aggregate theme
+route: the focused modal, drawer, toast, media, and helper routes make each
+component's behavior inspectable without opening every state at once.
 
 ## Badge and tag guidance
 
@@ -100,8 +281,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
@@ -178,15 +360,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: .5rem;
+  --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