@kerfjs/ui 5.0.0-beta.107 → 5.0.0-beta.108

package/dist/styles/pane.css

@@ -76,11 +76,16 @@
    surface instead. */
 .kui-pane[data-background] {
   background: var(--_kui-pane-background);
+  --kui-color-surface-current-region: var(--_kui-pane-background);
 }
 
+/* The transparent slots keep the root's surface context. */
 .kui-pane[data-background][data-appearance="sunken"] > .kui-pane__content,
 .kui-pane[data-background][data-appearance="sunken"][data-chrome-placement="auto"]
   > :is(.kui-pane__header, .kui-pane__footer) {
+  --kui-color-surface-current: inherit;
+  --kui-color-surface-current-region: inherit;
+  --kui-color-surface-current-tint: inherit;
   background: transparent;
 }
 
@@ -266,6 +271,16 @@
   background: var(--kui-chrome-material);
 }
 
+/* The material has no single color over scrolling content; the surface
+   context takes it at rest, as a tint over the region it covers. A clear
+   header paints nothing and keeps the inherited context. */
+.kui-pane[data-header-presentation="overlay"]:not(
+    [data-header-material="clear"]
+  )
+  > .kui-pane__header {
+  --kui-color-surface-current-tint: var(--kui-chrome-material);
+}
+
 .kui-pane[data-header-presentation="overlay"][data-header-overlay="measured"]:not(
     [data-chrome-placement="auto"]
   )

package/dist/styles/surface-scaffold.css

@@ -337,6 +337,8 @@ h2.kui-dialog-surface__title {
   -webkit-backdrop-filter: var(--kui-chrome-material-filter);
   backdrop-filter: var(--kui-chrome-material-filter);
   background: var(--kui-chrome-material-raised);
+  /* The material's surface context at rest, over the raised panel. */
+  --kui-color-surface-current-tint: var(--kui-chrome-material-raised);
   /* The divider is scroll state: the register publishes it only while
      content is scrolled beneath the header. An inset shadow, so showing it
      never moves the header or the content. */

package/dist/styles/tab-bar.css

@@ -38,6 +38,12 @@
     --kui-tab-bar-strip-background,
     var(--kui-tab-bar-background)
   );
+  /* The surface context (foundation.css): the strip's fill is a tint over
+     whatever the bar sits on. */
+  --kui-color-surface-current-tint: var(
+    --kui-tab-bar-strip-background,
+    var(--kui-tab-bar-background)
+  );
   scrollbar-width: none;
   align-items: center;
   flex: var(--kui-tab-bar-strip-flex, 1 1 auto);

package/dist/styles/tab-navigator.css

@@ -70,6 +70,13 @@
 
 .kui-tab-scaffold__scene[data-background] {
   background: var(--_kui-tab-scaffold-scene-background);
+  --kui-color-surface-current-region: var(--_kui-tab-scaffold-scene-background);
+}
+
+/* The navigator's color paints its root and a docked bar over whatever holds
+   the navigator: a region in the surface context. */
+.kui-tab-scaffold[data-background] {
+  --kui-color-surface-current-region: var(--_kui-tab-scaffold-background);
 }
 
 @media (forced-colors: active) {
@@ -213,6 +220,15 @@
   background: var(--kui-chrome-material);
 }
 
+/* The material's surface context at rest (see pane.css); a clear bar keeps
+   the inherited context. */
+.kui-tab-scaffold[data-bar-presentation="overlay"]:not(
+    [data-bar-material="clear"]
+  )
+  > .kui-tab-scaffold__bar {
+  --kui-color-surface-current-tint: var(--kui-chrome-material);
+}
+
 .kui-tab-scaffold[data-bar-presentation="overlay"][data-bar-overlay="measured"] {
   position: relative;
 }

package/dist/styles/toolbar-control-group.css

@@ -132,6 +132,31 @@
   }
 }
 
+/* A sibling of an expanded trailing control yields to the trailing-priority
+   row the Toolbar moves that control onto: the same container queries and
+   responsiveAt keys as the Toolbar's own row (toolbar.css), so the group
+   hides exactly while the row is active and never wraps onto a third row at
+   a threshold restated with hideBelow. */
+@container kui-toolbar (max-width: 52rem) {
+  .kui-toolbar[data-responsive="trailing-priority"][data-responsive-at="narrow"]
+    > .kui-toolbar__trailing:has(> [data-expanded="true"])
+    > .kui-toolbar-control-group[data-visibility="yield-to-priority-row"]:not(
+      [data-expanded="true"]
+    ) {
+    display: none;
+  }
+}
+
+@container kui-toolbar (max-width: 44rem) {
+  .kui-toolbar[data-responsive="trailing-priority"][data-responsive-at="compact"]
+    > .kui-toolbar__trailing:has(> [data-expanded="true"])
+    > .kui-toolbar-control-group[data-visibility="yield-to-priority-row"]:not(
+      [data-expanded="true"]
+    ) {
+    display: none;
+  }
+}
+
 /* `shape="rounded"` swaps the default pill radius for the design system's softer
    rounded rectangle. The shared highlight contract derives every inner hover or
    selected surface from this outer radius and the group's full inset. */
@@ -206,7 +231,10 @@
     border-color 0.2s ease;
 }
 
-.kui-toolbar-control-group[data-content="search"]:has(
+/* A fill search spans a content-sized group's line. A `sizing="grow"` group
+   keeps its own grow basis instead (below): taking the whole line would make
+   it the line's hypothetical size and wrap every sibling group. */
+.kui-toolbar-control-group[data-content="search"]:not([data-sizing="grow"]):has(
     > .kui-search-field[data-expanded="true"][data-fill="true"]
   ) {
   width: 100%;

package/dist/styles/toolbar.css

@@ -16,6 +16,15 @@
   font-family: var(--kui-font-sans);
 }
 
+/* In a List, a vertical stack, the toolbar is chrome and keeps its whole
+   natural height. Its explicit one-band min-height (below) replaces the flex
+   item's automatic content minimum, so a column shrinking toward a long
+   flex scroller beside it would otherwise squeeze a wrapped or stacked
+   toolbar onto its first row and clip the rest. */
+.kui-list > .kui-toolbar {
+  flex-shrink: 0;
+}
+
 /* Safe areas: a toolbar compensates only for the inline edges its owner hands
    it through `--kui-edge-inset-inline-*` (a Pane header or footer does), so its
    box and dividers keep reaching the edge while its zones clear the unsafe

package/dist/styles/webawesome.css

@@ -54,14 +54,19 @@
        theme stylesheets build their shadows from this token, so an app that
        layers one of them keeps kerf's scheme-aware shadow color. */
     --wa-color-shadow: light-dark(rgb(0 0 0 / 0.14), rgb(0 0 0 / 0.5));
-    --wa-color-focus: light-dark(#007aff, #64d2ff);
+    /* The brand tokens follow kerf's opt-in --kui-color-brand when the app
+       sets it (foundation.css derives the ramp); unset, the literals stand. */
+    --wa-color-focus: var(--_kui-brand-focus, light-dark(#007aff, #64d2ff));
     /* Kerf-owned loud fills and on-loud text: every on-loud/fill-loud pair
        clears WCAG AA (4.5:1) in both schemes. Light brand and danger keep
        white text on a slightly deeper fill of the same hue (#0088ff ->
        #0075db, #ff383c -> #eb0005); success keeps its bright green with dark
        text, as warning already does; dark brand and danger keep their fills
        with dark text. src/foundation.css mirrors these as fallbacks. */
-    --wa-color-brand-fill-loud: light-dark(#0075db, #64d2ff);
+    --wa-color-brand-fill-loud: var(
+      --_kui-brand-fill-loud,
+      light-dark(#0075db, #64d2ff)
+    );
     --wa-color-brand-fill-quiet: color-mix(
       in srgb,
       var(--wa-color-brand-fill-loud) 8%,
@@ -86,7 +91,10 @@
     /* Kerf-owned light on-quiet values: darkened from Hot Sheet 2's hues so
        they clear AA on the lowered page background (#f2f2f7) as well as on
        the surface; src/foundation.css mirrors them as fallbacks. */
-    --wa-color-brand-on-quiet: light-dark(#0c62f3, #8acbff);
+    --wa-color-brand-on-quiet: var(
+      --_kui-brand-on-quiet,
+      light-dark(#0c62f3, #8acbff)
+    );
     --wa-color-brand-on-normal: var(--wa-color-brand-on-quiet);
     --wa-color-brand-on-loud: light-dark(#fff, #111113);
 

package/dist/surface-scaffold.d.ts

@@ -88,6 +88,14 @@ interface DialogSurfaceOptions {
      * copy in the body; rendered as `aria-describedby` on the `<dialog>`.
      */
     describedBy?: string;
+    /**
+     * An alert dialog: a confirmation that interrupts the person to report
+     * something urgent or ask before a destructive action ("Delete this
+     * topic?"). Renders `role="alertdialog"` on the `<dialog>`; set
+     * `describedBy` to the element holding the message, and leave
+     * `lightDismiss` off so the person answers it.
+     */
+    alert?: boolean;
     /** The body content. */
     children: KerfUiContent;
     /**
@@ -202,7 +210,7 @@ interface DialogSurfaceOptions {
  * floating header and footer measurement, the bottom sheet's keyboard
  * clearance and grabber, and re-render resilience while open.
  */
-declare function DialogSurface({ id, label, labelledBy, describedBy, heading, headerActions, footer, withoutHeader, lightDismiss, closeLabel, children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, minHeight, resizable, enterMotion, exitMotion, bodyLayout, headerPresentation, footerPresentation, footerOffset, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ id, label, labelledBy, describedBy, alert, heading, headerActions, footer, withoutHeader, lightDismiss, closeLabel, children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, minHeight, resizable, enterMotion, exitMotion, bodyLayout, headerPresentation, footerPresentation, footerOffset, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
 /** Where a PopoverDialogSurface appears: the top layer, or in flow. */
 type PopoverDialogSurfacePresentation = 'overlay' | 'embedded';
 /** Application `data-*` metadata on the surface root. */

package/dist/surface-scaffold.js

@@ -1,4 +1,4 @@
-export { DialogSurface, PopoverDialogSurface, PopupSurface } from './chunk-G4DRH4A5.js';
+export { DialogSurface, PopoverDialogSurface, PopupSurface } from './chunk-6CDILXF4.js';
 export { closeDialog, openDialog } from './chunk-ATGAJVZ6.js';
 
 

package/dist/text-field.d.ts

@@ -50,6 +50,12 @@ interface TextFieldOptions {
     showCount?: boolean;
     /** Single-line value kind (default `text`). */
     type?: TextFieldType;
+    /** Native lower bound for `type="number"` (number or numeric string). */
+    min?: number | string;
+    /** Native upper bound for `type="number"` (number or numeric string). */
+    max?: number | string;
+    /** Native number increment (number, numeric string, or `"any"`). */
+    step?: number | string;
     /** A multi-line field: a `<textarea>`. */
     multiline?: boolean;
     /** A multi-line field's height in lines (default 3). */
@@ -78,6 +84,6 @@ interface TextFieldOptions {
  * The whole field is one `<label>`, so clicking anywhere on it focuses the
  * input; the input is named by `label` (or `ariaLabel`) directly.
  */
-declare function TextField({ label, ariaLabel, value, name, placeholder, hint, error, size, icon, clearable, clearLabel, maxLength, showCount, type, multiline, rows, maxRows, disabled, readOnly, required, autocomplete, id, className, rootAttributes, slot, }: TextFieldProps): kerfjs.SafeHtml;
+declare function TextField({ label, ariaLabel, value, name, placeholder, hint, error, size, icon, clearable, clearLabel, maxLength, showCount, type, min, max, step, multiline, rows, maxRows, disabled, readOnly, required, autocomplete, id, className, rootAttributes, slot, }: TextFieldProps): kerfjs.SafeHtml;
 
 export { TextField, type TextFieldName, type TextFieldOptions, type TextFieldProps, type TextFieldRootAttributes, type TextFieldSize, type TextFieldType };

package/dist/text-field.js

@@ -1,4 +1,4 @@
-export { TextField } from './chunk-WU57BYYM.js';
+export { TextField } from './chunk-YVZCKXR3.js';
 
 
 

package/dist/toolbar-control-group.d.ts

@@ -19,7 +19,7 @@ type ToolbarControlGroupSelectedTone = 'brand' | 'neutral' | 'pop';
 type ToolbarControlGroupOverflow = 'visible' | 'scroll' | 'wrap';
 type ToolbarControlGroupExpandedOverflow = 'clip' | 'visible';
 type ToolbarControlGroupMenuInset = 'standard' | 'compact' | 'list-zero';
-type ToolbarControlGroupVisibility = 'always' | 'compact-only' | 'hide-collapsed-tiny' | 'yield-to-expanded-sibling';
+type ToolbarControlGroupVisibility = 'always' | 'compact-only' | 'hide-collapsed-tiny' | 'yield-to-expanded-sibling' | 'yield-to-priority-row';
 type ToolbarControlGroupSizing = 'content' | 'grow' | 'fill';
 type ToolbarControlGroupPlacement = 'start' | 'end';
 interface ToolbarActionLinkProps {
@@ -82,7 +82,13 @@ interface ToolbarControlGroupProps {
     overflow?: ToolbarControlGroupOverflow;
     /** Let app-owned anchored surfaces extend outside an expanded search group. Collapsed searches retain their clipping. */
     expandedOverflow?: ToolbarControlGroupExpandedOverflow;
-    /** Responsive visibility owned by the enclosing Toolbar container. */
+    /**
+     * Responsive visibility owned by the enclosing Toolbar container.
+     * `yield-to-priority-row` hides this trailing group exactly while its
+     * Toolbar's `responsive="trailing-priority"` row is active (an expanded
+     * trailing sibling at the Toolbar's `responsiveAt` width), so the app never
+     * restates that breakpoint with `hideBelow`.
+     */
     visibility?: ToolbarControlGroupVisibility;
     /** Hide below this Toolbar content width; requires wireToolbarVisibility. */
     hideBelow?: CssLength;

package/dist/toolbar-control-group.js

@@ -1,4 +1,4 @@
-export { ToolbarActionLink, ToolbarControlGroup } from './chunk-2PXZBFEC.js';
+export { ToolbarActionLink, ToolbarControlGroup } from './chunk-5J6Z4BWY.js';
 
 
 

package/dist/toolbar.d.ts

@@ -9,6 +9,11 @@ type ToolbarPosition = 'header' | 'footer';
 /** Control-band density: `default` (60px with 44px groups) or `compact`. */
 type ToolbarDensity = 'default' | 'compact';
 interface ToolbarProps {
+    /**
+     * The toolbar's id, so app code can address it: name it as a scrolling
+     * List's chrome in `wireScrollDividers({ targets })`, or find it in tests.
+     */
+    id?: string;
     leading?: KerfUiContent;
     center?: KerfUiContent;
     trailing?: KerfUiContent;
@@ -73,6 +78,6 @@ interface ToolbarProps {
  * toolbar) forwards, so the app configures that toolbar instead of styling it.
  */
 type ToolbarConfig = Pick<ToolbarProps, 'density' | 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
-declare function Toolbar({ leading, center, trailing, label, position, density, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
+declare function Toolbar({ id, leading, center, trailing, label, position, density, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
 export { Sides, Toolbar, type ToolbarConfig, type ToolbarDensity, type ToolbarPosition, type ToolbarProps };

package/dist/toolbar.js

@@ -1,3 +1,3 @@
-export { Toolbar } from './chunk-CMLPFIC5.js';
+export { Toolbar } from './chunk-ZN7KUMPY.js';
 
 //# sourceMappingURL=toolbar.js.map

package/dist/wire-catalog.js

@@ -1,4 +1,4 @@
-import { wireWorkbench } from './chunk-QLA25V2K.js';
+import { wireWorkbench } from './chunk-WPNIKZMJ.js';
 
 import { wireScrollDividers } from './chunk-OZ6X76G5.js';
 import { loadUxReviewProject } from './chunk-6C6DLP3W.js';

package/dist/wire-workbench.js

@@ -1,4 +1,4 @@
-export { wireWorkbench } from './chunk-QLA25V2K.js';
+export { wireWorkbench } from './chunk-WPNIKZMJ.js';
 
 
 

package/dist/workbench-dialog.js

@@ -1,7 +1,7 @@
-import { DialogSurface } from './chunk-G4DRH4A5.js';
+import { DialogSurface } from './chunk-6CDILXF4.js';
 export { closeDialog, openDialog } from './chunk-ATGAJVZ6.js';
 
-import { Workbench } from './chunk-NLMEDZRM.js';
+import { Workbench } from './chunk-CPSGUGAY.js';
 
 
 
@@ -10,7 +10,7 @@ import { ToolbarText } from './chunk-EKHDLBRP.js';
 
 
 
-import { ToolbarControlGroup } from './chunk-2PXZBFEC.js';
+import { ToolbarControlGroup } from './chunk-5J6Z4BWY.js';
 
 
 

package/dist/workbench.js

@@ -1,4 +1,4 @@
-export { Workbench } from './chunk-NLMEDZRM.js';
+export { Workbench } from './chunk-CPSGUGAY.js';
 
 
 

package/docs/accessibility.md

@@ -370,7 +370,10 @@ supporting line (or app-owned summary copy in the body) is the dialog's
 accessible description; `WorkbenchDialog` wires its title `description`
 automatically (`<id>-description`), and `ListDetailDialog` takes an explicit
 `describedBy`, since its detail description describes the selection, not the
-dialog. For a **page or view**
+dialog. A `DialogSurface` that asks before a destructive action ("Delete this
+topic?") sets `alert`, which renders `role="alertdialog"` on the native
+`<dialog>`; pair it with `describedBy` on the message so it is announced, and
+leave `lightDismiss` off so the person answers it. For a **page or view**
 title, pass `headingLevel` (usually `1`) to `ToolbarText`: it then exposes
 `role="heading"` with a matching `aria-level`, giving the view a heading landmark
 so screen-reader heading navigation and "main heading" semantics work — the same
@@ -479,7 +482,9 @@ controls; Enter and Space use native button activation. The application handles
 the supplied `data-action`, reads `data-segment-value`, updates `value`, and
 re-renders. Keep labels unique and meaningful even when `content` shows only an
 icon. The filled track uses the normal neutral text role for readable unselected
-labels in light and dark themes. Use tabs—not a segmented control—when choices switch page regions that
+labels in light and dark themes. A whole-control `disabled` disables every
+native button and marks the group `aria-disabled` while `aria-pressed` still
+reports the current choice. Use tabs—not a segmented control—when choices switch page regions that
 need `tab`/`tabpanel` semantics.
 
 ## ChoiceChips
@@ -539,6 +544,12 @@ its label; the input itself reports `required`. The focus ring is drawn on the
 box around the input (`:focus-within`), 3px with a 1px offset like every Kerf
 control.
 
+For `type="number"`, `min`, `max`, and `step` pass through to the native input.
+Each accepts a number or string; `step="any"` allows arbitrary decimals.
+They are omitted for other input types and `multiline` textareas. Native
+constraint validation (`rangeUnderflow`, `rangeOverflow`, and `stepMismatch`)
+then applies without custom field wiring.
+
 `clearable` adds a native `<button>` named by `clearLabel` (default "Clear")
 after the input. It is hidden while the field is empty, is a normal Tab stop,
 and with `wireTextFields(root)` empties the field, dispatches bubbling `input`
@@ -567,12 +578,16 @@ a surface that changes the background behind its children publishes the
 surface context (`--kui-color-surface-current`, `-region`, and `-tint`; see
 `docs/component-contract.md`), and the line layers it the same way the page
 does. On a sunken panel, a quiet `ContentItem`, a lowered `FramedList`, a
-raised `List`, popup, or dialog, or a sunken Pane, Workbench area, or
-TabNavigator scene, the line matches the pixels outside the box, so it reads
-as a cut through the fill instead of a light halo. On a doubly sunken surface
-the brand ring still clears 3:1 against the line (about 3.2:1 in light, 6.9:1
-in dark). A sunken surface's grain is not part of the line, and a translucent
-glass material, which has no single color, falls back to the base surface.
+raised `List`, popup, or dialog, a highlighted `FramedList` row, a sunken
+Pane, Workbench area, or TabNavigator scene, or a Pane or TabNavigator app
+`background`, the line matches the pixels outside the box, so it reads as a
+cut through the fill instead of a light halo. On a doubly sunken surface the
+brand ring still clears 3:1 against the line (about 3.2:1 in light, 6.9:1 in
+dark). A sunken surface's grain is not part of the line. Translucent glass
+chrome (an overlay header, bar, or bottom toolbar, a dialog's floating
+header) has no single color over scrolling content, so the line paints the
+material over the surface beneath it: exact at rest, an approximation while
+content scrolls under the bar.
 
 ## Checkbox, RadioGroup, and Switch
 
@@ -786,7 +801,8 @@ the Tab order while collapsed or not inline. `wireWorkbench`, given a panel's
 `collapsed` signal, returns focus stranded in a closing panel to the control that
 opened it, else the restore control, else a control whose `aria-controls` names the
 panel; an open overlay panel takes focus and keeps Tab inside it (the ARIA dialog
-pattern). See [`workbench.md`](workbench.md).
+pattern), whether its own toggle or a persistent toggle outside the Workbench
+opened it, as soon as the panel can take focus. See [`workbench.md`](workbench.md).
 
 ## Chrome material
 

package/docs/component-contract.md

@@ -424,11 +424,17 @@ background behind its children publishes, on its own painted element, the
 foundation tokens `--kui-color-surface-current` (the opaque surface beneath:
 a raised `DialogSurface`, popover dialog, `AnchoredSurface`, or `List`
 `surface`, and a sunken Pane's opaque auto chrome, set it and clear both
-layers), `--kui-color-surface-current-region` (a layout region's translucent
-fill: a sunken `Pane`, `Workbench` area, or `TabNavigator` scene), and
-`--kui-color-surface-current-tint` (a content surface's translucent fill: a
-`SunkenPanel`, a sunken `Disclosure`, a lowered `FramedList`, a quiet,
-hovered, pressed, or selected `ContentItem`). They are undeclared at `:root`
+layers), `--kui-color-surface-current-region` (a layout region's fill: a sunken
+`Pane`, `Workbench` area, or `TabNavigator` scene, and a `Pane`'s or
+`TabNavigator`'s app `background`), and `--kui-color-surface-current-tint` (a
+content surface's fill: a `SunkenPanel`, a sunken `Disclosure`, a lowered
+`FramedList` and its highlighted row, a quiet, hovered, pressed, or selected
+`ContentItem`, a `TabBar` strip, and translucent glass chrome at rest — a
+`Pane` overlay header, `NavStack` overlay chrome or bottom toolbar, a
+`TabNavigator` overlay bar, and a dialog's floating header; clear chrome
+paints nothing and keeps the inherited context). Interactive rows (`ListItem`,
+`ListActionRow`, `SummaryRow`) are buttons or links themselves, so no control
+nests on their hover or selection fill and they publish nothing. They are undeclared at `:root`
 and a scoped `[data-kui-tint]` resets them. A control that must match what
 lies behind it (the inset focus ring's inner line on `Button` and
 `SplitButton`) layers tint over region over the opaque color, falling back to
@@ -635,7 +641,14 @@ preferences remove that entrance animation.
 Use `visibility="yield-to-expanded-sibling"` on trailing groups that should
 leave a 480px-or-narrower toolbar while a sibling trailing group is expanded.
 They return when it collapses or the toolbar widens; leading and center zones
-remain visible.
+remain visible. In a `responsive="trailing-priority"` Toolbar, use
+`visibility="yield-to-priority-row"` instead: the group leaves exactly while
+the expanded trailing control has its own row, from the same container query
+as the row at the Toolbar's `responsiveAt` (832px for `narrow`, 704px for
+`compact`, both inclusive). Do not restate that width with `hideBelow`, which
+hides strictly below its threshold: at exactly 704px the row is active while
+`hideBelow={rem(44)}` still shows the group, which then wraps onto a third
+row.
 A group's controls are plain `<button>`s (a standalone `Button` belongs outside a group); a popup menu is a `PopupMenu`, which renders its own
 trigger. By default a group stays on one row: each icon sits beside its label,
 and the enclosing `Toolbar`'s responsive policy relocates whole groups. Set

package/docs/component-selection.md

@@ -108,6 +108,30 @@ useful subtree. Prefer a component prop or component-specific token when the
 change belongs to one component or instance, and preserve the documented
 foreground/background contrast relationships and visible focus ring.
 
+### Brand color
+
+Set the opt-in `--kui-color-brand` once on `:root` to give the application its
+own brand. Any color works: Kerf derives the whole brand ramp from it — the
+loud fill (and the quiet and normal fills and borders mixed from it), its
+on-loud text, brand text and links, brand text on brand fills, and the focus
+ring — clamping lightness in each color scheme so every pair keeps WCAG AA for
+any hue. Unset, every brand token keeps its tuned default exactly. With the
+Web Awesome integration the same derivation drives `--wa-color-brand-*` and
+`--wa-color-focus`.
+
+```css
+:root {
+  --kui-color-brand: #1a7f37;
+}
+```
+
+Do not change the brand by overriding `--kui-color-brand-fill-loud` alone:
+brand text (`--kui-color-brand-on-quiet`, `--kui-color-brand-on-fill`) and the
+focus ring are separate tuned values and would stay the default blue. Choose a
+brand hue apart from the status tones it shares surfaces with: `info` follows
+the brand, so a green brand makes an info banner read like `success`. For one
+subtree with a different identity, use a scoped `tint` accent instead.
+
 ### Typed runtime dimensions
 
 Use `Row`, `Grid`, or `List` spacing shorthands for repeated sibling spacing: `gap="xs"`,
@@ -643,15 +667,15 @@ the control's dimensions, shows `LoadingSpinner` in its place, sets
 group hides only the glyph; a `content="text"` or `"mixed"` group hides the
 whole control, label included, so the spinner never draws over text.
 
-| Want                           | Put in the zone                                                                        | Notes                                                                                                          |
-| ------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| 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              |
-| One primary application action | `trailing={<Button tone="brand">New Ticket…</Button>}`                                 | The standalone button keeps its own chrome; use `tone="danger"` when the action is destructive                 |
-| 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 |
-| A command menu                 | `<ToolbarControlGroup single nestedDropdown><PopupMenu … /></ToolbarControlGroup>`     | Register `@kerfjs/ui/popup-menu/register` once; set `menuInset` on the group                                   |
-| A collapsible search box       | `<ToolbarControlGroup single><SearchField collapsible … /></ToolbarControlGroup>`      | The group animates the iconic ↔ expanded states; `wireSearchFields` manages expand/collapse/focus by default   |
+| Want                           | Put in the zone                                                                        | Notes                                                                                                                                           |
+| ------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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                                               |
+| One primary application action | `trailing={<Button tone="brand">New Ticket…</Button>}`                                 | The standalone button keeps its own chrome; use `tone="success"` for a positive pricing check or `tone="danger"` when the action is destructive |
+| 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                                  |
+| A command menu                 | `<ToolbarControlGroup single nestedDropdown><PopupMenu … /></ToolbarControlGroup>`     | Register `@kerfjs/ui/popup-menu/register` once; set `menuInset` on the group                                                                    |
+| A collapsible search box       | `<ToolbarControlGroup single><SearchField collapsible … /></ToolbarControlGroup>`      | The group animates the iconic ↔ expanded states; `wireSearchFields` manages expand/collapse/focus by default                                    |
 
 ### Room for an expanded search
 
@@ -665,9 +689,11 @@ other controls; plan for it instead:
   beside the siblings.
 - If a useful search cannot fit beside the other controls, set those controls
   aside while it is open. Mark them `visibility="yield-to-expanded-sibling"`
-  (they leave a 480px-or-narrower toolbar while a sibling is expanded), or
-  gather them behind a "…" `PopupMenu` overflow group. The application decides
-  which controls yield.
+  (they leave a 480px-or-narrower toolbar while a sibling is expanded), or, in
+  a `responsive="trailing-priority"` Toolbar,
+  `visibility="yield-to-priority-row"` (they leave exactly while the expanded
+  control has its own row), or gather them behind a "…" `PopupMenu` overflow
+  group. The application decides which controls yield.
 
 ### Application surfaces below search
 

package/docs/design/templates/button/tones-dark.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 84" width="520" height="84"><defs><clipPath id="ct0"><rect x="29" y="33" width="105.3" height="18"/></clipPath><clipPath id="ct1"><rect x="160.3" y="33" width="51" height="18"/></clipPath><clipPath id="ct2"><rect x="237.3" y="33" width="104.8" height="18"/></clipPath></defs><rect x="20" y="20" width="123.3" height="44" rx="12" fill="rgb(100,210,255)"/><rect x="20.5" y="20.5" width="122" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="29" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(17,17,19)">Save Changes</text><rect x="151.3" y="20" width="69" height="44" rx="12" fill="rgb(229,229,234)"/><rect x="151.5" y="20.5" width="68" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="160.28" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(28,28,30)">Cancel</text><rect x="228.3" y="20" width="122.8" height="44" rx="12" fill="rgb(255,56,60)"/><rect x="228.5" y="20.5" width="122" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="237.27" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(17,17,19)">Delete Project</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 84" width="520" height="84"><defs><clipPath id="ct0"><rect x="29" y="33" width="105.3" height="18"/></clipPath><clipPath id="ct1"><rect x="160.3" y="33" width="51" height="18"/></clipPath><clipPath id="ct2"><rect x="237.3" y="33" width="88.9" height="18"/></clipPath><clipPath id="ct3"><rect x="352.2" y="33" width="104.8" height="18"/></clipPath></defs><rect x="20" y="20" width="123.3" height="44" rx="12" fill="rgb(100,210,255)"/><rect x="20.5" y="20.5" width="122" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="29" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(17,17,19)">Save Changes</text><rect x="151.3" y="20" width="69" height="44" rx="12" fill="rgb(229,229,234)"/><rect x="151.5" y="20.5" width="68" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="160.28" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(28,28,30)">Cancel</text><rect x="228.3" y="20" width="106.9" height="44" rx="12" fill="rgb(52,199,89)"/><rect x="228.5" y="20.5" width="106" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="237.27" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(29,29,31)">Price Check</text><rect x="343.2" y="20" width="122.8" height="44" rx="12" fill="rgb(255,56,60)"/><rect x="343.5" y="20.5" width="122" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="352.16" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(17,17,19)">Delete Project</text></svg>

package/docs/design/templates/button/tones.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 84" width="520" height="84"><defs><clipPath id="ct0"><rect x="29" y="33" width="105.3" height="18"/></clipPath><clipPath id="ct1"><rect x="160.3" y="33" width="51" height="18"/></clipPath><clipPath id="ct2"><rect x="237.3" y="33" width="104.8" height="18"/></clipPath></defs><rect x="20" y="20" width="123.3" height="44" rx="12" fill="rgb(0,117,219)"/><rect x="20.5" y="20.5" width="122" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="29" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(255,255,255)">Save Changes</text><rect x="151.3" y="20" width="69" height="44" rx="12" fill="rgb(72,72,74)"/><rect x="151.5" y="20.5" width="68" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="160.28" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(255,255,255)">Cancel</text><rect x="228.3" y="20" width="122.8" height="44" rx="12" fill="rgb(235,0,5)"/><rect x="228.5" y="20.5" width="122" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="237.27" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(255,255,255)">Delete Project</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 84" width="520" height="84"><defs><clipPath id="ct0"><rect x="29" y="33" width="105.3" height="18"/></clipPath><clipPath id="ct1"><rect x="160.3" y="33" width="51" height="18"/></clipPath><clipPath id="ct2"><rect x="237.3" y="33" width="88.9" height="18"/></clipPath><clipPath id="ct3"><rect x="352.2" y="33" width="104.8" height="18"/></clipPath></defs><rect x="20" y="20" width="123.3" height="44" rx="12" fill="rgb(0,117,219)"/><rect x="20.5" y="20.5" width="122" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="29" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(255,255,255)">Save Changes</text><rect x="151.3" y="20" width="69" height="44" rx="12" fill="rgb(72,72,74)"/><rect x="151.5" y="20.5" width="68" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="160.28" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(255,255,255)">Cancel</text><rect x="228.3" y="20" width="106.9" height="44" rx="12" fill="rgb(52,199,89)"/><rect x="228.5" y="20.5" width="106" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="237.27" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(29,29,31)">Price Check</text><rect x="343.2" y="20" width="122.8" height="44" rx="12" fill="rgb(235,0,5)"/><rect x="343.5" y="20.5" width="122" height="43" rx="11.5" fill="none" stroke="rgba(0,0,0,0)" stroke-width="1"/><text x="352.16" y="48" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="16" font-weight="500" fill="rgb(255,255,255)">Delete Project</text></svg>