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

package/ai/component-catalog.json

@@ -115,7 +115,8 @@
         "quiet, solid, or outline appearance",
         "pill or rounded shape",
         "compact or default size",
-        "removable, link, action, or plain, enabled or disabled"
+        "removable, link, action, or plain, enabled or disabled",
+        "rootAttributes: safe data-* identity on the plain, link, or action root"
       ],
       "accessibility": [
         "The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.",
@@ -487,7 +488,8 @@
         "--kui-focus-ring",
         "--kui-shadow-s",
         "--kui-shadow-m",
-        "--kui-shadow-l"
+        "--kui-shadow-l",
+        "--kui-color-brand"
       ],
       "links": {
         "catalogRoute": "?component=foundation",
@@ -1791,7 +1793,7 @@
       ],
       "variants": [
         "no dividers (default)",
-        "scroll dividers when named as wireScrollDividers targets chrome",
+        "scroll dividers when named as wireScrollDividers targets chrome (by its id)",
         "top/right/bottom/left divider combinations",
         "centered content",
         "stacked zones at compact or narrow widths",
@@ -1970,6 +1972,7 @@
         "standard, compact, or list-zero dropdown menu inset",
         "visible, horizontally scrollable, or whole-action wrapping overflow",
         "always visible or compact-only responsive visibility",
+        "yield to an expanded trailing sibling at 480px, or exactly while a trailing-priority Toolbar row is active (yield-to-priority-row)",
         "relocate on panel collapse",
         "avatar scrim",
         "contained avatar background on a single group or selected multi-button highlight",
@@ -2171,6 +2174,7 @@
         "small, medium, or large dialog",
         "data-* rootAttributes (a data-key) so sibling dialogs morph by identity",
         "modal, side-sheet, fullscreen, or bottom-sheet dialog",
+        "alert dialog (alert): role=\"alertdialog\" on the native dialog, described by its message through describedBy",
         "bottom sheet attached to the bottom edge: square bottom corners, safe-area and virtual-keyboard clearance behind the panel, slide (or standard) enter and exit motion, and an optional resizable top grabber bounded by minHeight and maxHeight",
         "typed modal preferred width, viewport gutter, and maximum height, including viewport cap",
         "definite viewport-bounded modal height and a fill body layout for one child",
@@ -4152,7 +4156,7 @@
         "top/right/bottom/left text and control inset combinations",
         "fill: the layout root fills a definite-height parent",
         "rootAttributes: safe data-*, aria-*, and structural role on the root",
-        "scroll dividers when named as wireScrollDividers targets chrome",
+        "scroll dividers when named as wireScrollDividers targets chrome or scroller (by its id)",
         "multi-select grid for rich ContentItem rows",
         "contentWidth (compact 440px, medium 640px, wide 864px) and contentAlign for a readable, centered page column"
       ],
@@ -5274,6 +5278,7 @@
       "uses": [
         "tabs",
         "toolbar-control-group",
+        "button",
         "wa-button"
       ],
       "purpose": "Controlled tab strips whose tabs shrink and scroll while fixed leading, trailing, and far-edge end actions remain visible.",
@@ -5319,7 +5324,7 @@
         "intrinsic or fill allocation",
         "separate or adjacent trailing action",
         "far-edge end action",
-        "standalone Web Awesome action in trailing or end",
+        "standalone Kerf Button or Web Awesome action in trailing or end",
         "overflow dividers on each side with tabs scrolled out of view (wired by wireScrollDividers)"
       ],
       "accessibility": [
@@ -5469,7 +5474,8 @@
         "pill",
         "equal width",
         "small",
-        "placeholder (loading)"
+        "placeholder (loading)",
+        "disabled (whole control)"
       ],
       "accessibility": [
         "Keep choice labels meaningful and every enabled native button in sequential Tab order."
@@ -6710,7 +6716,7 @@
       "category": "Controls",
       "kind": "component",
       "source": "kerf",
-      "description": "A labeled single-line input or multi-line textarea with hint and error text, an optional leading icon, clear button, and character count, at the 44px control height or compact.",
+      "description": "A labeled single-line input or multi-line textarea with hint and error text, an optional leading icon, clear button, character count, and native numeric constraints, at the 44px control height or compact.",
       "uses": [
         "lucide-icon"
       ],
@@ -6722,7 +6728,8 @@
       "useWhen": [
         "A form or dialog collects a line of free text: label names it (or ariaLabel when nearby content already does), hint explains it, and error reports a validation problem.",
         "People write a longer note or message: multiline with rows, or rows plus maxRows to grow with the content; maxLength with showCount shows the remaining budget.",
-        "A filter or search field needs a leading icon and a clear button: icon and clearable."
+        "A filter or search field needs a leading icon and a clear button: icon and clearable.",
+        "An exact number needs native range or decimal-step validation: type=number with min, max, and step (including step=any)."
       ],
       "avoidWhen": [
         "Do not use when only existing values are allowed; use Select.",
@@ -6768,7 +6775,8 @@
         "disabled",
         "read-only",
         "required",
-        "email, password, search, url, tel, or number type"
+        "email, password, search, url, tel, or number type",
+        "number type with native min, max, and step constraints"
       ],
       "accessibility": [
         "The whole field is a <label> around a native <input> or <textarea>, so clicking anywhere on it focuses the field; the input is named by label (aria-label, with the visible label text hidden from assistive technology so the clear button and count stay out of the name) or by ariaLabel. Focus shows the standard focus ring around the box.",
@@ -7558,7 +7566,7 @@
       "category": "Controls",
       "kind": "component",
       "source": "kerf",
-      "description": "A standalone action button: a native button (or a link with href) in a neutral, brand, or danger tone and a primary, secondary, or plain emphasis, at the 44px control height or compact.",
+      "description": "A standalone action button: a native button (or a link with href) in a neutral, brand, success, or danger tone and a primary, secondary, or plain emphasis, at the 44px control height or compact.",
       "uses": [
         "loading-spinner"
       ],
@@ -7567,7 +7575,7 @@
         "Button"
       ],
       "useWhen": [
-        "A dialog footer, a form, or content needs an action button: tone=\"brand\" for the main action, tone=\"danger\" for a destructive one, and emphasis=\"secondary\" or \"plain\" for the quieter actions beside it.",
+        "A dialog footer, a form, or content needs an action button: tone=\"brand\" for the main action, tone=\"success\" for a positive action such as a pricing check, tone=\"danger\" for a destructive one, and emphasis=\"secondary\" or \"plain\" for the quieter actions beside it.",
         "A form submits or resets: type=\"submit\" or \"reset\" (the default type never submits), with name, value, and form when needed.",
         "An action navigates: href renders a link with the same chrome.",
         "A single primary action spans its form, sheet, or narrow column: fill makes it span the parent's available inline width, label centered, as SplitButton's fill does."
@@ -7594,7 +7602,7 @@
         "form ownership"
       ],
       "variants": [
-        "neutral, brand, or danger tone",
+        "neutral, brand, success, or danger tone",
         "primary, secondary, or plain emphasis",
         "default or compact size",
         "rounded (default) or pill shape",
@@ -7610,7 +7618,7 @@
       ],
       "accessibility": [
         "A native <button> (type=\"button\" unless set) or, with href, an <a>; its label names it, or ariaLabel when the label is not enough. Focus shows the standard focus ring 1px outside the box; with focusRingInset it is drawn inside the box, two-tone with a surface-colored line inside the ring color, so it keeps 3:1 contrast on a loud fill of its own hue.",
-        "Loading shows a spinner in place of the label, which still names the button, and sets aria-busy=\"true\". A disabled link drops its href and reports aria-disabled=\"true\".",
+        "Loading shows a spinner in place of the label, which still names the button, and sets aria-busy=\"true\". A disabled link drops its href and reports aria-disabled=\"true\". Disabled success uses a quiet success fill and readable on-fill text instead of fading the label.",
         "With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag."
       ],
       "geometry": {
@@ -7643,6 +7651,11 @@
         "--kui-color-brand-fill-quiet",
         "--kui-color-brand-on-quiet",
         "--kui-color-brand-border-loud",
+        "--kui-color-success-fill-loud",
+        "--kui-color-success-on-loud",
+        "--kui-color-success-fill-quiet",
+        "--kui-color-success-on-fill",
+        "--kui-color-success-border-loud",
         "--kui-color-danger-fill-loud",
         "--kui-color-danger-on-loud",
         "--kui-color-danger-fill-quiet",

package/ai/component-composition-rules.json

@@ -178,14 +178,14 @@
       {
         "id": "trailing",
         "jsx": { "prop": "trailing" },
-        "accepts": ["toolbar-control-group", "wa-button"],
+        "accepts": ["toolbar-control-group", "button", "wa-button"],
         "cardinality": { "min": 0, "max": 1 },
         "exclusiveWith": []
       },
       {
         "id": "end",
         "jsx": { "prop": "end" },
-        "accepts": ["toolbar-control-group", "wa-button"],
+        "accepts": ["toolbar-control-group", "button", "wa-button"],
         "cardinality": { "min": 0, "max": 1 },
         "exclusiveWith": []
       }

package/ai/component-composition.json

@@ -415,7 +415,8 @@
           "--kui-focus-ring",
           "--kui-shadow-s",
           "--kui-shadow-m",
-          "--kui-shadow-l"
+          "--kui-shadow-l",
+          "--kui-color-brand"
         ]
       },
       "diagnostics": [],
@@ -4378,14 +4379,14 @@
         {
           "id": "trailing",
           "jsx": { "prop": "trailing" },
-          "accepts": ["toolbar-control-group", "wa-button"],
+          "accepts": ["toolbar-control-group", "button", "wa-button"],
           "cardinality": { "min": 0, "max": 1 },
           "exclusiveWith": []
         },
         {
           "id": "end",
           "jsx": { "prop": "end" },
-          "accepts": ["toolbar-control-group", "wa-button"],
+          "accepts": ["toolbar-control-group", "button", "wa-button"],
           "cardinality": { "min": 0, "max": 1 },
           "exclusiveWith": []
         }
@@ -6093,7 +6094,7 @@
       "accessibility": {
         "obligations": [
           "A native <button> (type=\"button\" unless set) or, with href, an <a>; its label names it, or ariaLabel when the label is not enough. Focus shows the standard focus ring 1px outside the box; with focusRingInset it is drawn inside the box, two-tone with a surface-colored line inside the ring color, so it keeps 3:1 contrast on a loud fill of its own hue.",
-          "Loading shows a spinner in place of the label, which still names the button, and sets aria-busy=\"true\". A disabled link drops its href and reports aria-disabled=\"true\".",
+          "Loading shows a spinner in place of the label, which still names the button, and sets aria-busy=\"true\". A disabled link drops its href and reports aria-disabled=\"true\". Disabled success uses a quiet success fill and readable on-fill text instead of fading the label.",
           "With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag."
         ]
       },
@@ -6118,6 +6119,11 @@
           "--kui-color-brand-fill-quiet",
           "--kui-color-brand-on-quiet",
           "--kui-color-brand-border-loud",
+          "--kui-color-success-fill-loud",
+          "--kui-color-success-on-loud",
+          "--kui-color-success-fill-quiet",
+          "--kui-color-success-on-fill",
+          "--kui-color-success-border-loud",
           "--kui-color-danger-fill-loud",
           "--kui-color-danger-on-loud",
           "--kui-color-danger-fill-quiet",

package/ai/components/button.md

@@ -4,13 +4,13 @@
 
 `@kerfjs/ui:button` · Kerf UI · component · Controls
 
-A standalone action button: a native button (or a link with href) in a neutral, brand, or danger tone and a primary, secondary, or plain emphasis, at the 44px control height or compact.
+A standalone action button: a native button (or a link with href) in a neutral, brand, success, or danger tone and a primary, secondary, or plain emphasis, at the 44px control height or compact.
 
 ## When to use
 
 Trigger an action from a dialog footer, a form, or content outside any Toolbar, with Kerf's button chrome and native button semantics.
 
-- A dialog footer, a form, or content needs an action button: tone="brand" for the main action, tone="danger" for a destructive one, and emphasis="secondary" or "plain" for the quieter actions beside it.
+- A dialog footer, a form, or content needs an action button: tone="brand" for the main action, tone="success" for a positive action such as a pricing check, tone="danger" for a destructive one, and emphasis="secondary" or "plain" for the quieter actions beside it.
 - A form submits or resets: type="submit" or "reset" (the default type never submits), with name, value, and form when needed.
 - An action navigates: href renders a link with the same chrome.
 - A single primary action spans its form, sheet, or narrow column: fill makes it span the parent's available inline width, label centered, as SplitButton's fill does.
@@ -38,7 +38,7 @@ Exact prop names and types: [`@kerfjs/ui/button`](../public-api-signatures-v1.md
 
 **Variants (configure, do not restyle):**
 
-- neutral, brand, or danger tone
+- neutral, brand, success, or danger tone
 - primary, secondary, or plain emphasis
 - default or compact size
 - rounded (default) or pill shape
@@ -72,7 +72,7 @@ Margin: none · border: self · padding: self (layout role: controls). `self` me
 ## Accessibility
 
 - A native \<button> (type="button" unless set) or, with href, an \<a>; its label names it, or ariaLabel when the label is not enough. Focus shows the standard focus ring 1px outside the box; with focusRingInset it is drawn inside the box, two-tone with a surface-colored line inside the ring color, so it keeps 3:1 contrast on a loud fill of its own hue.
-- Loading shows a spinner in place of the label, which still names the button, and sets aria-busy="true". A disabled link drops its href and reports aria-disabled="true".
+- Loading shows a spinner in place of the label, which still names the button, and sets aria-busy="true". A disabled link drops its href and reports aria-disabled="true". Disabled success uses a quiet success fill and readable on-fill text instead of fading the label.
 - With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag.
 
 ## Styling boundary
@@ -83,7 +83,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-button`, `kui-button__icon`, `kui-button__label`, `kui-button__spinner` on an element you write; render `Button` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-on-quiet`, `--kui-color-brand-border-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-on-quiet`, `--kui-color-danger-border-loud`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-layout-rounded-radius`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-on-quiet`, `--kui-color-brand-border-loud`, `--kui-color-success-fill-loud`, `--kui-color-success-on-loud`, `--kui-color-success-fill-quiet`, `--kui-color-success-on-fill`, `--kui-color-success-border-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-on-quiet`, `--kui-color-danger-border-loud`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-layout-rounded-radius`. Set a token only where its public contract allows; prefer a prop.
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 

package/ai/components/chip.md

@@ -38,6 +38,7 @@ Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#k
 - pill or rounded shape
 - compact or default size
 - removable, link, action, or plain, enabled or disabled
+- rootAttributes: safe data-\* identity on the plain, link, or action root
 
 ## Composition
 

package/ai/components/foundation.md

@@ -55,7 +55,7 @@ Margin: none · border: none · padding: none (layout role: foundation). `self`
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public tokens it reads: `--kui-font-sans`, `--kui-font-mono`, `--kui-font-2xs`, `--kui-font-xs`, `--kui-font-s`, `--kui-font-m`, `--kui-font-l`, `--kui-font-xl`, `--kui-font-2xl`, `--kui-font-weight-semibold`, `--kui-space-none`, `--kui-space-2xs`, `--kui-space-xs`, `--kui-space-s`, `--kui-space-m`, `--kui-space-l`, `--kui-space-xl`, `--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`, `--kui-layout-inline-margin`, `--kui-layout-item-border-width`, `--kui-layout-item-padding`, `--kui-layout-item-gap`, `--kui-layout-content-gap`, `--kui-layout-control-gap`, `--kui-layout-metadata-gap`, `--kui-layout-highlight-inset`, `--kui-layout-rounded-radius`, `--kui-layout-pill-radius`, `--kui-toolbar-group-inner-size`, `--kui-toolbar-group-size`, `--kui-toolbar-gap`, `--kui-safe-area-block-start`, `--kui-safe-area-block-end`, `--kui-safe-area-inline-start`, `--kui-safe-area-inline-end`, `--kui-radius-s`, `--kui-radius-m`, `--kui-radius-l`, `--kui-radius-circle`, `--kui-radius-pill`, `--kui-disclosure-icon-scale`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-surface-lowered`, `--kui-sunken-texture`, `--kui-sunken-surface`, `--kui-color-surface-current`, `--kui-color-surface-current-region`, `--kui-color-surface-current-tint`, `--kui-chrome-material`, `--kui-chrome-material-raised`, `--kui-chrome-material-filter`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-text-link`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-loud`, `--kui-color-brand-on-quiet`, `--kui-color-brand-on-normal`, `--kui-color-brand-on-loud`, `--kui-color-brand-on-fill`, `--kui-color-pop-fill-loud`, `--kui-color-pop-fill-quiet`, `--kui-color-pop-fill-normal`, `--kui-color-pop-border-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-border-loud`, `--kui-color-pop-on-quiet`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-loud`, `--kui-color-pop-on-fill`, `--kui-color-success-fill-loud`, `--kui-color-success-fill-quiet`, `--kui-color-success-fill-normal`, `--kui-color-success-border-quiet`, `--kui-color-success-border-normal`, `--kui-color-success-border-loud`, `--kui-color-success-on-quiet`, `--kui-color-success-on-normal`, `--kui-color-success-on-loud`, `--kui-color-success-on-fill`, `--kui-color-warning-fill-loud`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-fill-normal`, `--kui-color-warning-border-quiet`, `--kui-color-warning-border-normal`, `--kui-color-warning-border-loud`, `--kui-color-warning-on-quiet`, `--kui-color-warning-on-normal`, `--kui-color-warning-on-loud`, `--kui-color-warning-on-fill`, `--kui-color-danger-fill-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-fill-normal`, `--kui-color-danger-border-quiet`, `--kui-color-danger-border-normal`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-color-danger-on-normal`, `--kui-color-danger-on-loud`, `--kui-color-danger-on-fill`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-shadow-m`, `--kui-shadow-l`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-font-sans`, `--kui-font-mono`, `--kui-font-2xs`, `--kui-font-xs`, `--kui-font-s`, `--kui-font-m`, `--kui-font-l`, `--kui-font-xl`, `--kui-font-2xl`, `--kui-font-weight-semibold`, `--kui-space-none`, `--kui-space-2xs`, `--kui-space-xs`, `--kui-space-s`, `--kui-space-m`, `--kui-space-l`, `--kui-space-xl`, `--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`, `--kui-layout-inline-margin`, `--kui-layout-item-border-width`, `--kui-layout-item-padding`, `--kui-layout-item-gap`, `--kui-layout-content-gap`, `--kui-layout-control-gap`, `--kui-layout-metadata-gap`, `--kui-layout-highlight-inset`, `--kui-layout-rounded-radius`, `--kui-layout-pill-radius`, `--kui-toolbar-group-inner-size`, `--kui-toolbar-group-size`, `--kui-toolbar-gap`, `--kui-safe-area-block-start`, `--kui-safe-area-block-end`, `--kui-safe-area-inline-start`, `--kui-safe-area-inline-end`, `--kui-radius-s`, `--kui-radius-m`, `--kui-radius-l`, `--kui-radius-circle`, `--kui-radius-pill`, `--kui-disclosure-icon-scale`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-surface-lowered`, `--kui-sunken-texture`, `--kui-sunken-surface`, `--kui-color-surface-current`, `--kui-color-surface-current-region`, `--kui-color-surface-current-tint`, `--kui-chrome-material`, `--kui-chrome-material-raised`, `--kui-chrome-material-filter`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-text-link`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-loud`, `--kui-color-brand-on-quiet`, `--kui-color-brand-on-normal`, `--kui-color-brand-on-loud`, `--kui-color-brand-on-fill`, `--kui-color-pop-fill-loud`, `--kui-color-pop-fill-quiet`, `--kui-color-pop-fill-normal`, `--kui-color-pop-border-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-border-loud`, `--kui-color-pop-on-quiet`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-loud`, `--kui-color-pop-on-fill`, `--kui-color-success-fill-loud`, `--kui-color-success-fill-quiet`, `--kui-color-success-fill-normal`, `--kui-color-success-border-quiet`, `--kui-color-success-border-normal`, `--kui-color-success-border-loud`, `--kui-color-success-on-quiet`, `--kui-color-success-on-normal`, `--kui-color-success-on-loud`, `--kui-color-success-on-fill`, `--kui-color-warning-fill-loud`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-fill-normal`, `--kui-color-warning-border-quiet`, `--kui-color-warning-border-normal`, `--kui-color-warning-border-loud`, `--kui-color-warning-on-quiet`, `--kui-color-warning-on-normal`, `--kui-color-warning-on-loud`, `--kui-color-warning-on-fill`, `--kui-color-danger-fill-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-fill-normal`, `--kui-color-danger-border-quiet`, `--kui-color-danger-border-normal`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-color-danger-on-normal`, `--kui-color-danger-on-loud`, `--kui-color-danger-on-fill`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-shadow-m`, `--kui-shadow-l`, `--kui-color-brand`. Set a token only where its public contract allows; prefer a prop.
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 

package/ai/components/list.md

@@ -61,7 +61,7 @@ Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#k
 - top/right/bottom/left text and control inset combinations
 - fill: the layout root fills a definite-height parent
 - rootAttributes: safe data-\*, aria-\*, and structural role on the root
-- scroll dividers when named as wireScrollDividers targets chrome
+- scroll dividers when named as wireScrollDividers targets chrome or scroller (by its id)
 - multi-select grid for rich ContentItem rows
 - contentWidth (compact 440px, medium 640px, wide 864px) and contentAlign for a readable, centered page column
 

package/ai/components/segmented-control.md

@@ -40,6 +40,7 @@ Exact prop names and types: [`@kerfjs/ui/segmented-control`](../public-api-signa
 - equal width
 - small
 - placeholder (loading)
+- disabled (whole control)
 
 ## Composition
 

package/ai/components/surface-scaffold.md

@@ -41,6 +41,7 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 - small, medium, or large dialog
 - data-\* rootAttributes (a data-key) so sibling dialogs morph by identity
 - modal, side-sheet, fullscreen, or bottom-sheet dialog
+- alert dialog (alert): role="alertdialog" on the native dialog, described by its message through describedBy
 - bottom sheet attached to the bottom edge: square bottom corners, safe-area and virtual-keyboard clearance behind the panel, slide (or standard) enter and exit motion, and an optional resizable top grabber bounded by minHeight and maxHeight
 - typed modal preferred width, viewport gutter, and maximum height, including viewport cap
 - definite viewport-bounded modal height and a fill body layout for one child

package/ai/components/tab-bar.md

@@ -45,7 +45,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-bar`](../public-api-signatures-v1.m
 - intrinsic or fill allocation
 - separate or adjacent trailing action
 - far-edge end action
-- standalone Web Awesome action in trailing or end
+- standalone Kerf Button or Web Awesome action in trailing or end
 - overflow dividers on each side with tabs scrolled out of view (wired by wireScrollDividers)
 
 ## Composition
@@ -53,14 +53,14 @@ Exact prop names and types: [`@kerfjs/ui/tab-bar`](../public-api-signatures-v1.m
 - Parents: any.
 - Contexts: `tabpanel-navigation`.
 - Children: only `tab-bar-item` (required: `tab-bar-item`).
-- Built from: [TabBarItem](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
+- Built from: [TabBarItem](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./button.md), [Button](./wa-button.md).
 
 Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
 
 - `tabs` — JSX prop `children`; accepts [TabBarItem](./tabs.md); at least 1.
 - `leading` — JSX prop `leading`; accepts [ToolbarControlGroup](./toolbar-control-group.md); 0–1.
-- `trailing` — JSX prop `trailing`; accepts [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md); 0–1.
-- `end` — JSX prop `end`; accepts [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md); 0–1.
+- `trailing` — JSX prop `trailing`; accepts [ToolbarControlGroup](./toolbar-control-group.md), [Button](./button.md), [Button](./wa-button.md); 0–1.
+- `end` — JSX prop `end`; accepts [ToolbarControlGroup](./toolbar-control-group.md), [Button](./button.md), [Button](./wa-button.md); 0–1.
 
 ## State and wiring
 
@@ -109,6 +109,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [TabBarItem](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [Tab Group](./wa-tab-group.md).
+- Components: [TabBarItem](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./button.md), [Button](./wa-button.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [Tab Group](./wa-tab-group.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
 - UX catalog route: `?component=tab-bar`.

package/ai/components/text-field.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:text-field` · Kerf UI · component · Controls
 
-A labeled single-line input or multi-line textarea with hint and error text, an optional leading icon, clear button, and character count, at the 44px control height or compact.
+A labeled single-line input or multi-line textarea with hint and error text, an optional leading icon, clear button, character count, and native numeric constraints, at the 44px control height or compact.
 
 ## When to use
 
@@ -13,6 +13,7 @@ Collect free text (names, addresses, notes, comments) with Kerf's field chrome,
 - A form or dialog collects a line of free text: label names it (or ariaLabel when nearby content already does), hint explains it, and error reports a validation problem.
 - People write a longer note or message: multiline with rows, or rows plus maxRows to grow with the content; maxLength with showCount shows the remaining budget.
 - A filter or search field needs a leading icon and a clear button: icon and clearable.
+- An exact number needs native range or decimal-step validation: type=number with min, max, and step (including step=any).
 
 **Not when:**
 
@@ -53,6 +54,7 @@ Exact prop names and types: [`@kerfjs/ui/text-field`](../public-api-signatures-v
 - read-only
 - required
 - email, password, search, url, tel, or number type
+- number type with native min, max, and step constraints
 
 ## Composition
 

package/ai/components/toolbar-control-group.md

@@ -57,6 +57,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-control-group`](../public-api-s
 - standard, compact, or list-zero dropdown menu inset
 - visible, horizontally scrollable, or whole-action wrapping overflow
 - always visible or compact-only responsive visibility
+- yield to an expanded trailing sibling at 480px, or exactly while a trailing-priority Toolbar row is active (yield-to-priority-row)
 - relocate on panel collapse
 - avatar scrim
 - contained avatar background on a single group or selected multi-button highlight

package/ai/components/toolbar.md

@@ -31,7 +31,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.m
 **Variants (configure, do not restyle):**
 
 - no dividers (default)
-- scroll dividers when named as wireScrollDividers targets chrome
+- scroll dividers when named as wireScrollDividers targets chrome (by its id)
 - top/right/bottom/left divider combinations
 - centered content
 - stacked zones at compact or narrow widths

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.107` and `kerfjs@5.0.0-beta.107`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.109` and `kerfjs@5.0.0-beta.109`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -172,6 +172,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;
@@ -236,7 +241,7 @@ 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 };
 ```
@@ -347,7 +352,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 {
@@ -410,7 +415,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;
@@ -893,6 +904,12 @@ interface ListProps {
     /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
     controlInsets?: Sides;
     className?: string;
+    /**
+     * The list's id, so app code can address it: name it as a
+     * `wireScrollDividers` scroller (with a `Toolbar` above it as its chrome),
+     * or find it in tests.
+     */
+    id?: string;
     /**
      * Safe `data-*`, `aria-*`, and structural `role` metadata (a named drop
      * `region`, `aria-busy`); List-owned structural attributes remain
@@ -910,7 +927,7 @@ interface ListProps {
  */
 type ListConfig = Pick<ListProps, 'gap' | 'hAlign' | 'vAlign' | 'dividerSides' | 'textInsets' | 'controlInsets'>;
 /** A stretch-aligned vertical stack with optional gap, flex, fill, scroll, and dividers. */
-declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, scrollClearance, frame, maxHeight, minHeight, surface, inset, contentWidth, contentAlign, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
+declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, scrollClearance, frame, maxHeight, minHeight, surface, inset, contentWidth, contentAlign, dividerSides, textInsets, controlInsets, className, id, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, List, type ListConfig, type ListContentWidth, type ListInset, type ListProps, type ListSurface, ListVerticalAlignment, ScrollClearance, Sides, UiGap };
 ```
@@ -1444,12 +1461,12 @@ interface TabBarProps {
     label: string;
     children: KerfUiContent;
     leading?: KerfUiContent;
-    /** Tab-local action: a ToolbarControlGroup or a standalone Web Awesome button. */
+    /** Tab-local action: one ToolbarControlGroup, Kerf Button, or Web Awesome button. */
     trailing?: KerfUiContent;
     /**
      * Action pinned to the far edge of the bar. Combine with an adjacent `trailing`
      * action when the tab-local and workspace-level actions must remain distinct.
-     * Accepts a ToolbarControlGroup or a standalone Web Awesome button.
+     * Accepts one ToolbarControlGroup, Kerf Button, or Web Awesome button.
      */
     end?: KerfUiContent;
     className?: string;
@@ -3447,10 +3464,12 @@ interface SegmentedControlProps<Value extends string = string> {
     className?: string;
     /** Render as a loading placeholder: every choice keeps its live label or icon, none is selected, and every segment is disabled. */
     placeholder?: boolean;
+    /** Disable the whole control: every segment is disabled and dimmed, the selection stays visible, and the group reports `aria-disabled`. A choice's own `disabled` still disables just that segment. */
+    disabled?: boolean;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function SegmentedControl<Value extends string>({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, slot, }: SegmentedControlProps<Value>): kerfjs.SafeHtml;
+declare function SegmentedControl<Value extends string>({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, disabled, slot, }: SegmentedControlProps<Value>): kerfjs.SafeHtml;
 
 export { SegmentedControl, type SegmentedControlAppearance, type SegmentedControlChoice, type SegmentedControlLayout, type SegmentedControlProps, type SegmentedControlShape, type SegmentedControlSize };
 ```
@@ -4324,6 +4343,19 @@ import './css-values.js';
  * and derives its fill, border, and focus ring from `currentColor`.
  */
 type ChipTone = SemanticTone | 'inherit';
+/** Safe `data-*` identity on a Chip root; Chip-owned attributes are protected. */
+type ChipRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-tone'?: never;
+    'data-appearance'?: never;
+    'data-shape'?: never;
+    'data-size'?: never;
+    'data-disabled'?: never;
+    'data-truncate'?: never;
+    'data-item-id'?: never;
+    'data-link'?: never;
+    'data-action'?: never;
+}>;
 interface ChipCommonProps {
     /** Decorative leading icon, normally an unsized LucideIcon. */
     icon?: SafeHtml;
@@ -4334,6 +4366,11 @@ interface ChipCommonProps {
     disabled?: boolean;
     /** Record identifier available to an application delegated action handler. */
     itemId?: string;
+    /**
+     * Safe `data-*` identity on the chip root (a plain, link, or action chip),
+     * for tests and delegated handlers; use `itemId` for the record id.
+     */
+    rootAttributes?: ChipRootAttributes;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -4409,9 +4446,9 @@ type ChipProps = ChipCommonProps & ChipLabelProps & (({
  * `href` is set, or a native button when `action` is set. The application
  * owns removal, the link destination, and the action handler.
  */
-declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, href, download, external, removeAction, removeLabel, action, actionLabel, }: ChipProps): SafeHtml;
+declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, rootAttributes, className, slot, href, download, external, removeAction, removeLabel, action, actionLabel, }: ChipProps): SafeHtml;
 
-export { Chip, type ChipProps, type ChipTone };
+export { Chip, type ChipProps, type ChipRootAttributes, type ChipTone };
 ```
 
 ## `@kerfjs/ui/lucide-icon`
@@ -4701,6 +4738,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;
     /**
@@ -4815,7 +4860,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. */
@@ -6126,6 +6171,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). */
@@ -6154,7 +6205,7 @@ 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 };
 ```
@@ -6556,8 +6607,8 @@ import { BadgeTone } from './badge.js';
 import './css-values.js';
 import './semantic-tone-CdW013KF.js';
 
-/** The color family: `neutral` (default), `brand` for the main action, `danger` for a destructive one. */
-type ButtonTone = 'neutral' | 'brand' | 'danger';
+/** The color family: `neutral` (default), `brand` for the main action, `success` for a positive one, `danger` for a destructive one. */
+type ButtonTone = 'neutral' | 'brand' | 'success' | 'danger';
 /**
  * How loudly it asks: `primary` (default) fills the button, `secondary`
  * outlines it, and `plain` shows only its text until hovered.
@@ -6660,7 +6711,7 @@ interface ButtonOptions {
 }
 /**
  * A standalone action button: a native `<button>` (or a link with `href`)
- * in one of three tones and three emphases, at the 44px control height or
+ * in one of four tones and three emphases, at the 44px control height or
  * compact, with a label or as an icon-only square, rounded or pill-shaped,
  * sized to its label or filling its parent's width, and optionally a
  * `pressed` toggle. Inside a