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

package/README.md

@@ -280,6 +280,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `TextField`                                                  | `@kerfjs/ui/text-field`                 | `@kerfjs/ui/text-field.css`              |
 | `wireTextFields`                                             | `@kerfjs/ui/wire-text-fields`           | —                                        |
 | `Checkbox`                                                   | `@kerfjs/ui/checkbox`                   | `@kerfjs/ui/checkbox.css`                |
+| `CheckboxGroup`                                              | `@kerfjs/ui/checkbox-group`             | `@kerfjs/ui/checkbox-group.css`          |
 | `wireCheckboxes`                                             | `@kerfjs/ui/wire-checkboxes`            | —                                        |
 | `RadioGroup`                                                 | `@kerfjs/ui/radio-group`                | `@kerfjs/ui/radio-group.css`             |
 | `Switch`                                                     | `@kerfjs/ui/switch`                     | `@kerfjs/ui/switch.css`                  |
@@ -867,7 +868,7 @@ import "@kerfjs/ui/popup-menu/register";
 
 `select/register` defines the form-associated `kui-select` root and wires every `Select` in the document; `popup-menu/register` wires every `PopupMenu` (opening, keyboard navigation, submenus, the `kui-menu-select` event, and focus return). That boundary keeps custom-element and document-listener side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it, and also prove that no public entry except `@kerfjs/ui/webawesome.css` pulls in Web Awesome. Either registration also installs help tags: an icon-only Select, PopupMenu, or `aria-label`-named `<button>` in a `ToolbarControlGroup` shows its name in an `aria-hidden` tooltip on hover and keyboard focus. A toolbar with icon-only buttons but neither control imports `@kerfjs/ui/help-tags/register`, which registers only the tooltip.
 
-`PopupMenu` items may include `submenu` children, `checked` choices, a leading `icon`, trailing `details`, `disabledReason`, and a `danger` tone. The app owns choice state and dispatches each item's `action`. For a right-click menu, set `context: true`, a `label`, and `anchor={pointSignal.value}`; the app's `contextmenu` handler stores `{ x: event.clientX, y: event.clientY }` in that signal and calls `openPopupMenu(menu)`. The menu renders its own zero-footprint anchor host and keeps the point across re-renders, so it needs no wrapper or CSS (`openPopupMenuAt(menu, x, y)` still opens a menu rendered without `anchor`); `closePopupMenu(menu)` closes it programmatically. See [component selection](docs/component-selection.md#popup-menu-migration) for examples.
+`PopupMenu` items may include `submenu` children, `checked` choices, a leading `icon`, trailing `details`, `disabledReason`, and a `danger` tone. The app owns choice state and dispatches each item's `action`. For a right-click menu, set `context: true`, a `label`, and `anchor={pointSignal.value}`; the app's `contextmenu` handler stores `{ x: event.clientX, y: event.clientY }` in that signal and calls `openPopupMenu(menu)`. The menu renders its own zero-footprint anchor host and keeps the point across re-renders, so it needs no wrapper or CSS (`openPopupMenuAt(menu, x, y, { placement? })` still opens a menu rendered without `anchor`); `closePopupMenu(menu)` closes it programmatically. See [component selection](docs/component-selection.md#popup-menu-migration) for examples.
 Use `label` for a visible label or `ariaLabel` for a visually hidden name. A
 nonempty visible label takes precedence when both are supplied. Kerf names the
 native trigger without adding visible label spacing; this also works with

package/ai/application-ui-diagnostic-ids-v1.json

@@ -62,6 +62,7 @@
     "KUI-L201",
     "KUI-L202",
     "KUI-L203",
+    "KUI-L204",
     "KUI-L301",
     "KUI-L401",
     "KUI-L402",

package/ai/application-ui-profile.defaults.json

@@ -90,9 +90,14 @@
     },
     "boolean-option": {
       "preferred": "@kerfjs/ui:checkbox",
-      "avoid": ["@kerfjs/ui:wa-checkbox", "@kerfjs/ui:wa-checkbox-group"],
+      "avoid": ["@kerfjs/ui:wa-checkbox"],
       "rationale": "Render Checkbox, a native checkbox drawn as a Kerf box."
     },
+    "multiple-option": {
+      "preferred": "@kerfjs/ui:checkbox-group",
+      "avoid": ["@kerfjs/ui:wa-checkbox-group"],
+      "rationale": "Render CheckboxGroup, a native fieldset of Checkboxes with a choices array, laid out like RadioGroup."
+    },
     "exclusive-option": {
       "preferred": "@kerfjs/ui:radio-group",
       "avoid": ["@kerfjs/ui:wa-radio-group", "@kerfjs/ui:wa-radio"],

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.",
@@ -416,6 +417,9 @@
         "--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",
@@ -484,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",
@@ -1788,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",
@@ -1967,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",
@@ -2168,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",
@@ -2183,12 +2190,13 @@
         "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)"
       ],
       "accessibility": [
         "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."
@@ -2439,7 +2447,7 @@
       ],
       "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."
       ],
       "geometry": {
         "margin": "parent",
@@ -2572,7 +2580,7 @@
       ],
       "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."
       ],
       "geometry": {
         "margin": "parent",
@@ -4148,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"
       ],
@@ -5014,7 +5022,7 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "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.",
+      "description": "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.",
       "uses": [
         "disclosure-arrow",
         "lucide-icon"
@@ -5028,7 +5036,8 @@
       ],
       "useWhen": [
         "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 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."
       ],
       "avoidWhen": [
         "Do not use it to switch between peer views; use a SegmentedControl or TabBar.",
@@ -5050,6 +5059,7 @@
       ],
       "variants": [
         "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"
@@ -5063,7 +5073,8 @@
         "border": "self",
         "padding": "self",
         "notes": [
-          "The root takes the content-item geometry (8px inline margin, a 1px border, 8px padding); the content starts on the title's text column."
+          "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."
         ]
       },
       "delivery": {
@@ -5462,7 +5473,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."
@@ -5732,7 +5744,7 @@
       "category": "Controls",
       "kind": "component",
       "source": "kerf",
-      "description": "A full inline color picker: a saturation and brightness area, hue and opacity sliders, an RGB/HSL/HSB/Grayscale model menu with channel fields, a hex field (8 digits below full opacity) and opacity field, a screen sampler where the EyeDropper API exists, and optional preset and sample swatches.",
+      "description": "A full inline color picker: a saturation and brightness area, a slider per channel of the color model (red, green, and blue; hue, saturation, and lightness or brightness; or one gray level) whose tracks paint the colors each channel produces while the others hold (the hue track a fixed full-saturation rainbow), an opacity slider, an RGB/HSL/HSB/Grayscale model menu that switches the sliders and channel fields together, a hex field (8 digits below full opacity) and opacity field, a screen sampler where the EyeDropper API exists, and optional preset and sample swatches.",
       "uses": [
         "color-swatches",
         "lucide-icon"
@@ -5745,6 +5757,8 @@
         "ColorPickerSamples",
         "ColorPickerRootAttributes",
         "colorPickerChannels",
+        "colorPickerSlider",
+        "ColorPickerSliderState",
         "colorPickerAreaText",
         "colorPickerStyle"
       ],
@@ -5771,21 +5785,24 @@
       ],
       "variants": [
         "with or without opacity",
-        "RGB, HSL, HSB, or Grayscale channel fields",
+        "RGB, HSL, HSB, or Grayscale channel sliders and fields",
         "presets and titled sample groups with an add button",
         "screen sampler where the EyeDropper API exists",
         "disabled"
       ],
       "accessibility": [
         "The area is a slider named Saturation and Brightness with a spoken value; the arrow keys move it (Shift for 10% steps), Page Up and Down change brightness, Home and End saturation.",
-        "Hue and opacity are native range inputs; every field is named (Red, Hue, Hex Color, Opacity); the picker is a named group."
+        "Every channel slider and the opacity slider is a native range input named for its channel (Red, Hue, Lightness, Gray Level, Opacity) with a spoken value in the channel's unit (210°, 40%, or a 0–255 byte); every field is named (Red, Hue, Hex Color, Opacity); the picker is a named group.",
+        "The saturation and brightness area and every slider track carry a 1px inner edge halfway to the text color, so an area or track as dark or as light as the surface around it keeps at least 3:1 non-text contrast against it; increased contrast draws the edge in the full text color and forced colors in CanvasText.",
+        "Every thumb draws a two-tone ring, a white border inside a dark outline, so it keeps at least 3:1 non-text contrast against light and dark area and track colors alike.",
+        "Every slider track runs in the writing direction, as the native range does: in right-to-left text its gradient starts at the right, under the thumb at the channel's minimum."
       ],
       "geometry": {
         "margin": "none",
         "border": "self",
         "padding": "self",
         "notes": [
-          "The panel takes the shared block-content inset and a 320px maximum width; its rows are 12px apart."
+          "The panel takes the shared block-content inset and a 320px maximum width; its rows are 12px apart and its sliders form one group 8px apart."
         ]
       },
       "delivery": {
@@ -5820,7 +5837,8 @@
         "kui-color-picker__surface",
         "kui-color-picker__area",
         "kui-color-picker__area-thumb",
-        "kui-color-picker__hue",
+        "kui-color-picker__sliders",
+        "kui-color-picker__slider",
         "kui-color-picker__opacity",
         "kui-color-picker__controls",
         "kui-color-picker__mode-wrap",
@@ -6697,7 +6715,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"
       ],
@@ -6709,7 +6727,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.",
@@ -6755,7 +6774,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.",
@@ -6851,6 +6871,11 @@
           "id": "wa-checkbox",
           "relationship": "prefer-over"
         },
+        {
+          "id": "checkbox-group",
+          "relationship": "nearest",
+          "when": "Use CheckboxGroup for a labeled set of related options."
+        },
         {
           "id": "switch",
           "relationship": "nearest",
@@ -6885,7 +6910,7 @@
         "border": "self",
         "padding": "none",
         "notes": [
-          "A 20px box (18px compact) 8px (7px) before its label; hint and error align with the label text."
+          "A 20px box (18px compact) 8px (7px) before its label; hint and error sit directly under the label, on its text column, like a grouped choice hint. Stack standalone Checkboxes in a List gap=\"xs\" (8px), the same 28px pitch as RadioGroup choices."
         ]
       },
       "delivery": {
@@ -6935,6 +6960,108 @@
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
+    {
+      "id": "checkbox-group",
+      "name": "CheckboxGroup",
+      "category": "Controls",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A native fieldset of Kerf Checkboxes with the group label above, per-choice hints, and hint and error text below, stacked or wrapping like a RadioGroup.",
+      "uses": [
+        "checkbox"
+      ],
+      "purpose": "Choose any number of a few related options that should stay visible under one group label, with native keyboard behavior and form participation.",
+      "publicExports": [
+        "CheckboxGroup"
+      ],
+      "useWhen": [
+        "A form asks for any of two to about eight related options under one label, each with a readable label and an optional hint, and every checked value submits under one name."
+      ],
+      "avoidWhen": [
+        "Do not use for one choice among several; use RadioGroup.",
+        "Do not use for a single independent option or a parent with a mixed state; use Checkbox.",
+        "Do not use for settings that apply the moment they change; use Switch.",
+        "Do not use for many short tag-like or wrapping pill choices; use ChoiceChips multiple."
+      ],
+      "alternatives": [
+        {
+          "id": "wa-checkbox-group",
+          "relationship": "prefer-over"
+        },
+        {
+          "id": "checkbox",
+          "relationship": "nearest",
+          "when": "Use Checkbox for one independent option, or a mixed parent above its children."
+        },
+        {
+          "id": "radio-group",
+          "relationship": "nearest",
+          "when": "Use RadioGroup when exactly one option may be chosen."
+        },
+        {
+          "id": "choice-chips",
+          "relationship": "nearest",
+          "when": "Use ChoiceChips multiple for wrapping pill choices."
+        }
+      ],
+      "appOwns": [
+        "checked values",
+        "choices and their copy",
+        "validation and error copy"
+      ],
+      "variants": [
+        "vertical or horizontal",
+        "per-choice hint",
+        "disabled choice",
+        "whole group disabled",
+        "hint",
+        "error",
+        "default or compact size"
+      ],
+      "accessibility": [
+        "A native <fieldset> (a group) named by its legend (label), ariaLabel, or labelledBy; each choice is a Kerf Checkbox, a native checkbox inside its <label>, invisibly over the drawn box. Every checkbox is its own Tab stop and Space toggles it; each checked value submits under name.",
+        "The group's hint and error form its aria-description; an error sets aria-invalid on the group and the danger border on each box. A choice's hint is that checkbox's aria-description. disabled disables the fieldset, and so every checkbox, natively."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "self",
+        "notes": [
+          "Laid out exactly like a RadioGroup: the label and hint sit on the text column (1px + 8px); each choice's 20px box (18px compact) sits on the group's inline-start edge 8px (7px) before its label; choices stack 8px apart (--kui-space-xs), the same 28px pitch as RadioGroup choices, wrap with a 24px column gap when horizontal, and a choice hint sits directly under its label text."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/checkbox-group",
+        "manualCssImport": "@kerfjs/ui/checkbox-group.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-checkbox-group",
+        "kui-checkbox-group__label",
+        "kui-checkbox-group__choices",
+        "kui-checkbox-group__hint",
+        "kui-checkbox-group__error"
+      ],
+      "publicTokens": [
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-text-quiet",
+        "--kui-color-danger-on-quiet",
+        "--kui-font-m",
+        "--kui-font-s",
+        "--kui-font-xs",
+        "--kui-layout-item-padding",
+        "--kui-space-xs"
+      ],
+      "rootElement": "fieldset",
+      "links": {
+        "catalogRoute": "?component=checkbox-group",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "radio-group",
       "name": "RadioGroup",
@@ -6973,6 +7100,11 @@
           "id": "choice-chips",
           "relationship": "nearest",
           "when": "Use ChoiceChips for wrapping pill choices."
+        },
+        {
+          "id": "checkbox-group",
+          "relationship": "nearest",
+          "when": "Use CheckboxGroup when people may choose several."
         }
       ],
       "appOwns": [
@@ -6999,7 +7131,7 @@
         "border": "none",
         "padding": "self",
         "notes": [
-          "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."
         ]
       },
       "delivery": {
@@ -7037,7 +7169,8 @@
         "--kui-font-s",
         "--kui-font-xs",
         "--kui-color-neutral-on-quiet",
-        "--kui-layout-item-padding"
+        "--kui-layout-item-padding",
+        "--kui-space-xs"
       ],
       "rootElement": "fieldset",
       "links": {
@@ -7099,7 +7232,7 @@
         "border": "self",
         "padding": "none",
         "notes": [
-          "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."
         ]
       },
       "delivery": {
@@ -7432,7 +7565,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"
       ],
@@ -7441,9 +7574,10 @@
         "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."
+        "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."
       ],
       "avoidWhen": [
         "Do not use inside a ToolbarControlGroup; give the group plain <button> controls, which it styles.",
@@ -7467,21 +7601,23 @@
         "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",
+        "content width (default) or fill: spans the parent's available inline width, label centered and ellipsized when it no longer fits",
         "leading icon",
         "icon-only square (icon and ariaLabel, no label)",
         "pressed toggle (aria-pressed) on any tone and emphasis",
         "loading",
         "disabled",
         "link (href)",
-        "badge (a count, short text, or true for a dot) over the corner, named through badgeLabel, with badgeTone"
+        "badge (a count, short text, or true for a dot) over the corner, named through badgeLabel, with badgeTone",
+        "focusRingInset: the focus ring drawn inside the box for an ancestor that clips overflow"
       ],
       "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.",
-        "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\".",
+        "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\". 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": {
@@ -7514,6 +7650,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",
@@ -7542,7 +7683,7 @@
         "lucide-icon",
         "loading-spinner"
       ],
-      "purpose": "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.",
+      "purpose": "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.",
       "publicExports": [
         "SplitButton"
       ],
@@ -7574,11 +7715,14 @@
       "variants": [
         "brand, neutral, success, warning, or danger tone",
         "content width or fill",
+        "rounded or pill shape",
         "busy",
-        "disabled primary or options"
+        "disabled primary or options",
+        "focusRingInset: each half's focus ring drawn inside its box for an ancestor that clips overflow"
       ],
       "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."
+        "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."
       ],
       "geometry": {
         "margin": "none",
@@ -7612,6 +7756,7 @@
         "--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"
@@ -9041,29 +9186,29 @@
       "category": "Forms",
       "kind": "component",
       "source": "webawesome",
-      "description": "Ecosystem checkbox group; use Kerf Checkbox rows or ChoiceChips.",
+      "description": "Ecosystem checkbox group; use Kerf CheckboxGroup or ChoiceChips.",
       "uses": [
         "wa-checkbox"
       ],
-      "purpose": "Ecosystem checkbox group; use Kerf Checkbox rows or ChoiceChips.",
+      "purpose": "Ecosystem checkbox group; use Kerf CheckboxGroup or ChoiceChips.",
       "customElement": "wa-checkbox-group",
       "useWhen": [
         "Labels and validates a related set of checkboxes."
       ],
       "avoidWhen": [
-        "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."
       ],
       "recommendation": "avoid",
       "alternatives": [
         {
-          "id": "checkbox",
+          "id": "checkbox-group",
           "relationship": "prefer-kerf",
-          "when": "Use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills."
+          "when": "Use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills."
         },
         {
           "id": "choice-chips",
           "relationship": "prefer-kerf",
-          "when": "Use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills."
+          "when": "Use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills."
         }
       ],
       "geometry": {

package/ai/component-composition-rules.json

@@ -122,6 +122,17 @@
     },
     "zones": []
   },
+  "@kerfjs/ui:text": {
+    "_source": "docs/disclosure.md#embedded-in-a-content-item",
+    "insetFreeWhen": [
+      { "prop": "flush", "equals": true },
+      { "prop": "variant", "equals": "span" }
+    ]
+  },
+  "@kerfjs/ui:disclosure": {
+    "_source": "docs/disclosure.md#embedded-in-a-content-item",
+    "insetFreeChildren": [{ "prop": "appearance", "equals": "embedded" }]
+  },
   "@kerfjs/ui:list-header": {
     "_source": "docs/accessibility.md#shared-rules",
     "contexts": ["navigation-list"],
@@ -263,8 +274,15 @@
     "contexts": ["chat-composer", "dialog-floating-footer"],
     "zones": [
       {
-        "id": "actions",
-        "jsx": { "prop": "actions" },
+        "id": "leading",
+        "jsx": { "prop": "leading" },
+        "accepts": ["KerfUiContent"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing",
+        "jsx": { "prop": "trailing" },
         "accepts": ["KerfUiContent"],
         "cardinality": { "min": 1, "max": "unbounded" },
         "exclusiveWith": []

package/ai/component-composition.d.ts

@@ -39,6 +39,11 @@ export type CatalogCssValueProp = {
   unsafeHelper?: string;
   examples: string[];
 };
+/** A statically written JSX prop value; a bare boolean prop equals `true`. */
+export type CatalogPropCondition = {
+  prop: string;
+  equals: string | number | boolean;
+};
 export interface CatalogCompositionEntry {
   key: CatalogQualifiedKey;
   package: string;
@@ -52,6 +57,12 @@ export interface CatalogCompositionEntry {
   /** For a wrapper component: the cataloged roots it renders (any one of
    *  them, or nothing). Composition checks treat its elements as each root. */
   rendersAs?: CatalogQualifiedKey[];
+  /** Prop values under which direct JSX children must bring no content-item
+   *  inset; a child owning its margin, border, and padding reports KUI-L204
+   *  unless one of its `insetFreeWhen` conditions holds. */
+  insetFreeChildren?: CatalogPropCondition[];
+  /** Prop values that render this inset-bearing entry without its inset. */
+  insetFreeWhen?: CatalogPropCondition[];
   /** Additional JSX exports in this selection entry with their own placement. */
   jsxExports?: Record<
     string,