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

package/ai/components/disclosure.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:disclosure` · Kerf UI · component · Structure
 
-Content a person shows and hides under a summary row: a native details element with a DisclosureArrow, a title, and an optional quiet detail, on content-item geometry, with plain, framed, and sunken appearances and native exclusive (accordion) groups.
+Content a person shows and hides under a summary row: a native details element with a DisclosureArrow, a title, and an optional quiet detail, on content-item geometry, with plain, framed, and sunken appearances, an embedded appearance for a compact panel inside a ContentItem, and native exclusive (accordion) groups.
 
 ## When to use
 
@@ -12,6 +12,7 @@ Keep secondary or optional content one press away under a summary, or let a pers
 
 - Optional or advanced content should stay out of the way until a person asks for it (advanced settings, a build log, release notes).
 - A list of questions or sections should open one at a time: give the Disclosures the same name for a native exclusive accordion.
+- A compact details panel belongs inside a ContentItem (a note card's AI feedback): use appearance embedded so the item's own inset frames it once.
 
 **Not when:**
 
@@ -36,6 +37,7 @@ Exact prop names and types: [`@kerfjs/ui/disclosure`](../public-api-signatures-v
 **Variants (configure, do not restyle):**
 
 - plain, framed, or sunken appearance
+- embedded appearance inside a ContentItem or other owner chrome: no margin, border, or padding of its own and a 24px minimum summary row
 - open or closed initially
 - a quiet detail after the title
 - an exclusive accordion group sharing a name
@@ -58,6 +60,9 @@ No wiring helper.
 Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
 - The root takes the content-item geometry (8px inline margin, a 1px border, 8px padding); the content starts on the title's text column.
+- appearance embedded drops that geometry inside a ContentItem, which already owns it: the arrow sits on the item's content inset, the summary row is at least 24px tall, and the content (a flush Text or other content without an inset) starts on the title's text column 8px below the summary. Do not use embedded outside owner chrome.
+
+While `appearance="embedded"` is set, direct children must bring no content-item inset: a child that owns its margin, border, and padding double-insets this one. Use an inset-free form such as `Text flush`, or inline content (`KUI-L204`).
 
 ## Accessibility
 

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-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-detail-dialog.md

@@ -75,7 +75,7 @@ Margin: parent · border: self · padding: child (layout role: structure). `self
 ## Accessibility
 
 - It is a native modal \<dialog> named by label: the page is inert, focus stays inside, Escape asks to close, and focus returns to the opener on close.
-- On roomy devices the detail title is a level-2 heading; every presentation keeps a close control named Close (closeLabel), and the compact back control is named by backLabel.
+- Pass describedBy, the id of app-owned summary copy, for the dialog's accessible description; the detail description describes the selection and is not wired. On roomy devices the detail title is a level-2 heading; every presentation keeps a close control named Close (closeLabel), and the compact back control is named by backLabel.
 
 ## Styling boundary
 

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/message-composer.md

@@ -50,7 +50,8 @@ Exact prop names and types: [`@kerfjs/ui/message-composer`](../public-api-signat
 
 Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
 
-- `actions` — JSX prop `actions`; accepts `KerfUiContent`; at least 1.
+- `leading` — JSX prop `leading`; accepts `KerfUiContent`; any number.
+- `trailing` — JSX prop `trailing`; accepts `KerfUiContent`; at least 1.
 
 ## State and wiring
 

package/ai/components/radio-group.md

@@ -24,6 +24,7 @@ Choose exactly one of a few options that should stay visible with room for a lab
 - [Radio](./wa-radio.md) (prefer-over)
 - [Select](./select.md) (nearest) — Use Select for a long list.
 - [ChoiceChips](./choice-chips.md) (nearest) — Use ChoiceChips for wrapping pill choices.
+- [CheckboxGroup](./checkbox-group.md) (nearest) — Use CheckboxGroup when people may choose several.
 
 ## Imports
 
@@ -62,7 +63,7 @@ No wiring helper.
 
 Margin: none · border: none · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- The label and hint sit on the text column (1px + 8px); the choices sit on the 8px control column, 12px apart.
+- The label and hint sit on the text column (1px + 8px); each choice's 20px circle (18px compact) sits on the group's inline-start edge, where a Checkbox draws its box, 8px (7px) before its label; choices stack 8px apart (--kui-space-xs), the same 28px pitch as Checkboxes in a List gap="xs", and a choice hint aligns with its label text.
 
 ## Accessibility
 
@@ -77,12 +78,12 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-radio-group`, `kui-radio-group__label`, `kui-radio-group__choices`, `kui-radio-group__choice`, `kui-radio-group__row`, `kui-radio-group__control`, `kui-radio-group__input`, `kui-radio-group__circle`, `kui-radio-group__choice-label`, `kui-radio-group__choice-hint`, `kui-radio-group__hint`, `kui-radio-group__error` on an element you write; render `RadioGroup` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-neutral-border-normal`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-color-neutral-on-quiet`, `--kui-layout-item-padding`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-neutral-border-normal`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-color-neutral-on-quiet`, `--kui-layout-item-padding`, `--kui-space-xs`. 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`).
 
 ## Related
 
-- Components: [Radio Group](./wa-radio-group.md), [Radio](./wa-radio.md), [Select](./select.md), [ChoiceChips](./choice-chips.md).
+- Components: [Radio Group](./wa-radio-group.md), [Radio](./wa-radio.md), [Select](./select.md), [ChoiceChips](./choice-chips.md), [CheckboxGroup](./checkbox-group.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
 - UX catalog route: `?component=radio-group`.

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/split-button.md

@@ -8,7 +8,7 @@ A primary action with an attached options trigger on one loud semantic fill.
 
 ## When to use
 
-Render a prominent primary action plus an options trigger (provider, model, target) as one control with a semantic tone, full-width sizing, a busy presentation, and native aria-expanded on the trigger, outside any Toolbar.
+Render a prominent primary action plus an options trigger (provider, model, target) as one control with a semantic tone, full-width sizing, a rounded or pill shape, a busy presentation, and native aria-expanded on the trigger, outside any Toolbar.
 
 - A prominent primary action has a closely related set of options chosen from an attached trigger, such as Drive with a provider menu or Deploy with targets.
 
@@ -37,8 +37,10 @@ Exact prop names and types: [`@kerfjs/ui/split-button`](../public-api-signatures
 
 - brand, neutral, success, warning, or danger tone
 - content width or fill
+- rounded or pill shape
 - busy
 - disabled primary or options
+- focusRingInset: each half's focus ring drawn inside its box for an ancestor that clips overflow
 
 ## Composition
 
@@ -60,6 +62,7 @@ Margin: none · border: self · padding: self (layout role: controls). `self` me
 ## Accessibility
 
 - Both halves are native buttons in a group; the options trigger exposes aria-haspopup, aria-expanded, and optional aria-controls, and needs optionsLabel. busy sets aria-busy on the primary.
+- Each half draws the focus ring 1px outside its box; with focusRingInset it is drawn inside, two-tone with a surface-colored line inside the ring color, so it keeps 3:1 contrast on every loud fill.
 
 ## Styling boundary
 
@@ -69,7 +72,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-split-button`, `kui-split-button__options`, `kui-split-button__icon`, `kui-split-button__label` on an element you write; render `SplitButton` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-success-fill-loud`, `--kui-color-success-on-loud`, `--kui-color-warning-fill-loud`, `--kui-color-warning-on-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-focus-ring`, `--kui-font-weight-semibold`, `--kui-layout-rounded-radius`, `--kui-space-s`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-success-fill-loud`, `--kui-color-success-on-loud`, `--kui-color-warning-fill-loud`, `--kui-color-warning-on-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-focus-ring`, `--kui-font-weight-semibold`, `--kui-layout-pill-radius`, `--kui-layout-rounded-radius`, `--kui-space-s`, `--kui-space-xs`. 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/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
@@ -56,6 +57,7 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 - core kerfjs/overlay confirm/prompt/form/choice as a bottom sheet styled by @kerfjs/ui/overlay-sheet.css
 - resizable core kerfjs/overlay bottom sheet: the kui-overlay-sheet-resizable class plus wireOverlaySheets adds the resizable DialogSurface sheet grabber
 - header with label text or heading content, headerActions, a close button, and an optional footer; withoutHeader for content that owns its heading and close control
+- accessible description by describedBy: the heading ToolbarText descriptionId or app-owned body summary copy
 - light dismiss (a backdrop press closes; otherwise the panel pulses)
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
@@ -87,7 +89,7 @@ Margin: parent · border: child · padding: self (layout role: structure). `self
 
 - DialogSurface is a native \<dialog> opened modally (showModal): it is in the top layer, the rest of the page is inert, focus stays inside, and it returns to the opener on close. Focus starts on an autofocus element, otherwise on the panel.
 - Name it with label (also its title text) or labelledBy (the id of a heading, such as a ToolbarText). The close button is named Close (closeLabel) and Escape asks to close; the cancelable kui-request-close event reports source close-button, escape, or backdrop.
-- Name a PopoverDialogSurface with label or labelledBy, and describe it with describedBy (rendered as aria-describedby), usually a title ToolbarText descriptionId.
+- Name a PopoverDialogSurface with label or labelledBy. Describe either surface with describedBy (rendered as aria-describedby on the dialog root), usually the heading ToolbarText descriptionId or app-owned summary copy in the body; rootAttributes accepts only data-\* attributes, so it never sets aria-describedby.
 - A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
 - A resizable bottom sheet's grabber is a focusable horizontal separator ("Resize sheet") with aria-valuemin, aria-valuenow, and aria-valuemax in visible px; the arrow keys, Page Up/Down, Home, and End resize it, and its slide motion is skipped under prefers-reduced-motion.
 - Use popup surfaces only for real dropdown menus with named triggers.

package/ai/components/switch.md

@@ -56,7 +56,7 @@ No wiring helper.
 
 Margin: none · border: self · padding: none (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- A 35×20 track (31.5×18 compact) 8px (7px) before its label; the hint aligns with the label text.
+- A 35×20 track (31.5×18 compact) 8px (7px) before its label; the hint sits directly under the label, on its text column, like a Checkbox hint.
 
 ## Accessibility
 

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/text.md

@@ -64,6 +64,8 @@ Margin: self · border: self · padding: self (layout role: structure). `self` m
 - Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; flush removes the border and padding. Tight line height is available for compact copy. Span has no margin by default, border, or padding. FieldLabel mirrors the themed Web Awesome label typography, 9px inline inset, and bottom gap.
 - controlMargins adds the shared control gutter outside selected physical edges without changing border or padding; avoid duplicating a parent inset. Spans retain inline display and native inline margin behavior.
 
+Inset-free (no margin, border, or padding) when `flush` or `variant="span"`: the form to use inside a parent that expects inset-free content (`KUI-L204`).
+
 ## Accessibility
 
 - Text renders a native paragraph by default; choose an h1 through h6 variant by document outline rather than appearance, or span for inline secondary text.

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/components/wa-checkbox-group.md

@@ -6,18 +6,18 @@
 
 ## When to use
 
-Ecosystem checkbox group; use Kerf Checkbox rows or ChoiceChips.
+Ecosystem checkbox group; use Kerf CheckboxGroup or ChoiceChips.
 
 - Labels and validates a related set of checkboxes.
 
 **Not when:**
 
-- Do not use it in Kerf UI; use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills.
+- Do not use it in Kerf UI; use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills.
 
 **Alternatives:**
 
-- [Checkbox](./checkbox.md) (prefer-kerf) — Use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills.
-- [ChoiceChips](./choice-chips.md) (prefer-kerf) — Use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills.
+- [CheckboxGroup](./checkbox-group.md) (prefer-kerf) — Use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills.
+- [ChoiceChips](./choice-chips.md) (prefer-kerf) — Use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills.
 
 ## Imports
 
@@ -57,6 +57,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Checkbox](./wa-checkbox.md), [Checkbox](./checkbox.md), [ChoiceChips](./choice-chips.md).
+- Components: [Checkbox](./wa-checkbox.md), [CheckboxGroup](./checkbox-group.md), [ChoiceChips](./choice-chips.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-checkbox-group`.

package/ai/components/workbench-dialog.md

@@ -75,7 +75,7 @@ Margin: parent · border: self · padding: child (layout role: structure). `self
 ## Accessibility
 
 - It is a native modal \<dialog> named by label: the page is inert, focus stays inside, Escape asks to close, and focus returns to the opener on close.
-- The title is a level-2 heading; the close control is named Close (closeLabel) and stays the outermost trailing control. An open overlay rail takes focus, keeps Tab inside it, and closes on Escape before the dialog does.
+- The title is a level-2 heading, and its description (id \<id>-description) is the dialog's accessible description unless describedBy names other content; the close control is named Close (closeLabel) and stays the outermost trailing control. An open overlay rail takes focus, keeps Tab inside it, and closes on Escape before the dialog does.
 
 ## Styling boundary