@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.101

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,186 @@ pointer targets. Override `--kui-wa-carousel-icon-size`,
 `--kui-wa-carousel-dot-hit-size` on a carousel or containing scope when a
 product needs different geometry.
 
+Code text uses Kerf's named monospace stack, `--kui-font-mono`
+(`ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono",
+monospace`), and the theme points `--wa-font-family-code` at it. Web Awesome's
+own `ui-monospace, monospace` renders the generic face (Courier on macOS) in
+Chromium, which does not recognize `ui-monospace`; because the generic
+`monospace` ends any stack, Kerf's token owns the stack rather than appending
+fallbacks after Web Awesome's. Override `--kui-font-mono` to change code text in
+both Kerf and Web Awesome components.
+
+Form fields carry the same content-item inset as the Kerf primitives: a 1px
+border with 8px inside it (`--wa-form-control-border-width`,
+`--wa-form-control-padding-block`, and `--wa-form-control-padding-inline` are set
+to the `--kui-layout-item-border-width` / `--kui-layout-item-padding` values), so
+the value sits 9px in from the field edge. Native buttons and fields, plus Web
+Awesome buttons and fields, use the 12px `--kui-layout-rounded-radius` through
+`--wa-form-control-border-radius`; explicit pill and circular shapes retain
+their own radius. Default-size single-line controls
+share Kerf's 44px control height — the height of a Kerf `Select`, a toolbar
+group, and a list row — so a `wa-input` or `wa-button` sits flush beside a Kerf
+`Select`. The theme sets `--wa-form-control-height` to `2.75em` (44px at the
+16px default) on Button, Color Picker, Input, Known Date, Number Input, Radio
+Group, Select, 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 shared sunken surface
+  (`--kui-sunken-surface`: the lowered semantic color with the same fine grain
+  texture as every Kerf sunken surface), and uses the shared rounded-rectangle
+  radius. The texture is generated by the first Kerf sunken component that
+  renders; a page with only Web Awesome sunken surfaces calls
+  `ensureSunkenTexture()` once. Override
+  `--kui-wa-sunken-background` or `--kui-wa-sunken-radius` on an instance or
+  containing scope when that surface needs different tokens.
+- `--kui-wa-container-inset` defaults to the 16px homogeneous-group step. Tab
+  Panel retains this roomier tier for unframed panel content. Dialog body uses
+  the 8px surface inset, while its footer uses the 16px container inset so
+  content stays compact and the action group has a clearer boundary. These two
+  parts do not inherit the dialog's shared `--spacing` value.
+
+## Contextual transparency
+
+The lowered surface, neutral quiet/normal fills, and neutral borders are
+translucent shared theme colors. The foundation mirrors them when Web Awesome
+is absent. Nested SunkenPanel, Pane, and Web Awesome sunken surfaces therefore
+composite on their actual backdrop without application-owned depth wrappers
+or component-token overrides.
+
+The lowered tint is `--wa-color-surface-lowered` in the Web Awesome theme and
+`--kui-color-surface-lowered` in the Kerf foundation fallback;
+`--wa-color-neutral-fill-quiet` and `--kui-color-neutral-fill-quiet` share it.
+`SunkenPanel`, sunken Pane, Workbench, and TabNavigator surfaces read it by
+default through the optional `--kui-sunken-panel-background` override. Web
+Awesome Accordion, Card, and Details with `appearance="sunken"` read it
+through the optional `--kui-wa-sunken-background` override. These names do
+not denote separate opaque colors or distinct depth levels. A deliberate
+nested surface adds another translucent layer and can make hierarchy clearer;
+avoid painting a second background on a wrapper that represents the same
+surface. Inspect the composed result over the real backdrop in light and dark
+modes.
+
+The lowered light tint is `rgb(0 0 98.076923 / 0.05098)` (approximately
+`#f2f2f7` over white); dark is `rgb(228.157895 228.157895 255 / 0.07451)`
+(approximately `#111113` over black). Repeated layers darken in light mode
+and brighten in dark mode. The same value is used at every depth; there is no
+arbitrary third-level cap. Neutral normal fills and borders use alpha values
+chosen to retain their former single-layer appearance over the default surface.
+Their painted result adapts to other backgrounds. Neutral on-quiet text uses
+`#626267` / `#c2c2c6` to retain AA contrast across the tested layered catalog
+surfaces.
+
+Default/raised surfaces remain opaque canvas and overlay anchors. The optional
+document baseline paints an opaque default surface on `html` and one lowered
+layer on `body`. Normal/quiet foregrounds, focus indicators, and loud neutral
+fills remain opaque for legible controls. Colored semantic fill/border tokens
+also remain opaque pending their separate contrast evaluation. Transparency
+is not a guarantee of contrast on an arbitrary photograph or infinitely nested
+surface; applications must verify their actual composition and keep text and
+interactive controls on suitable surfaces.
+
+The catalog demonstrates three directly nested panels, a sunken Pane containing
+a panel, and a Web Awesome card containing details, using public components and
+no demo stylesheet. Browser tests cover repeated layers, actual compositing,
+text contrast, light/dark switching, narrow/wide layouts, and forced colors.
+
+The built-in close control of a `wa-dialog` or `wa-drawer` matches a borderless
+single `ToolbarControlGroup` button, the close a toolbar-composed dialog uses
+(see the list-detail dialog recipe): a 40px circle with no border and the
+neutral hover fill, in place of Web Awesome's 35px rounded square. The theme
+sizes it through the directly exported `close-button__base` part, so the
+default header and a toolbar-composed header present one close affordance.
+
+Add `class="hide-actions"` to a `wa-dialog` when the dialog supplies its own
+dismissal affordance and should omit Web Awesome's header action region. The
+theme sets `display: none` on the directly exported `header-actions` part; it
+does not attempt to chain `::part()` through the internal `dialog` and `header`
+parts, which CSS shadow parts do not support.
+
+Badge remains intentionally compact at Web Awesome's intrinsic `0.375em` block /
+`0.625em` inline padding (4.5px / 7.5px at its default 12px text size): it is a
+short status or count, not a content item. A badge with `appearance="filled"` or
+`appearance="filled-outlined"` uses its variant's quiet fill with normal text by
+default so every shipped semantic variant meets WCAG AA for that small text;
+filled-outlined keeps its normal variant border. Accent badges keep their loud
+fills and their variant's `on-loud` foreground, which the theme sets to clear AA
+on that fill in both themes: white on the light brand (`#0075db`) and danger
+(`#eb0005`) fills, dark text on the success and warning fills and on the pale
+dark-mode brand and danger fills.
+Override
+`--kui-wa-badge-filled-background` and `--kui-wa-badge-filled-foreground` on a
+badge or containing scope when a product needs a different contrast-safe pair,
+or `--kui-wa-badge-accent-foreground` for a reviewed accent foreground.
+Breadcrumb has no bordered or filled container, and Scroller delegates item chrome
+to its slotted children, so both retain their upstream geometry. Web Awesome
+3.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 +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
@@ -73,12 +252,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 +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
 
@@ -100,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
@@ -178,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: .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