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

package/ai/component-composition.json

@@ -344,6 +344,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",
@@ -2055,7 +2058,7 @@
         "obligations": [
           "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."
@@ -2290,7 +2293,7 @@
       "accessibility": {
         "obligations": [
           "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."
         ]
       },
       "cssValueProps": [],
@@ -2389,7 +2392,7 @@
       "accessibility": {
         "obligations": [
           "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."
         ]
       },
       "cssValueProps": [],
@@ -2653,8 +2656,12 @@
       "diagnostics": [],
       "provenance": {
         "selection": "ai/component-catalog.json",
-        "composition": "generated-permissive-default"
-      }
+        "composition": "docs/disclosure.md#embedded-in-a-content-item"
+      },
+      "insetFreeWhen": [
+        { "prop": "flush", "equals": true },
+        { "prop": "variant", "equals": "span" }
+      ]
     },
     {
       "key": "@kerfjs/ui:headers",
@@ -4148,7 +4155,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."
           ]
         }
       },
@@ -4173,8 +4181,9 @@
       "diagnostics": [],
       "provenance": {
         "selection": "ai/component-catalog.json",
-        "composition": "generated-permissive-default"
-      }
+        "composition": "docs/disclosure.md#embedded-in-a-content-item"
+      },
+      "insetFreeChildren": [{ "prop": "appearance", "equals": "embedded" }]
     },
     {
       "key": "@kerfjs/ui:application-tabs",
@@ -4747,14 +4756,17 @@
           "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."
           ]
         }
       },
       "accessibility": {
         "obligations": [
           "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."
         ]
       },
       "cssValueProps": [],
@@ -4765,7 +4777,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",
@@ -4884,8 +4897,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": []
@@ -5547,7 +5567,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."
           ]
         }
       },
@@ -5592,6 +5612,82 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:checkbox-group",
+      "package": "@kerfjs/ui",
+      "id": "checkbox-group",
+      "name": "CheckboxGroup",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        { "id": "checked values", "owner": "application", "required": false },
+        {
+          "id": "choices and their copy",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "validation and error copy",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["controls"],
+        "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."
+          ]
+        }
+      },
+      "accessibility": {
+        "obligations": [
+          "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."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-checkbox-group",
+        "publicClasses": [
+          "kui-checkbox-group",
+          "kui-checkbox-group__label",
+          "kui-checkbox-group__choices",
+          "kui-checkbox-group__hint",
+          "kui-checkbox-group__error"
+        ],
+        "rootElement": "fieldset",
+        "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"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:radio-group",
       "package": "@kerfjs/ui",
@@ -5630,7 +5726,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."
           ]
         }
       },
@@ -5671,7 +5767,8 @@
           "--kui-font-s",
           "--kui-font-xs",
           "--kui-color-neutral-on-quiet",
-          "--kui-layout-item-padding"
+          "--kui-layout-item-padding",
+          "--kui-space-xs"
         ]
       },
       "diagnostics": [],
@@ -5713,7 +5810,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."
           ]
         }
       },
@@ -5995,7 +6092,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.",
+          "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\".",
           "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."
         ]
@@ -6079,7 +6176,8 @@
       },
       "accessibility": {
         "obligations": [
-          "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."
         ]
       },
       "cssValueProps": [],
@@ -6105,6 +6203,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"

package/ai/component-composition.schema.json

@@ -169,6 +169,18 @@
           "minItems": 1,
           "uniqueItems": true
         },
+        "insetFreeChildren": {
+          "description": "Prop values under which the entry's direct JSX children must bring no content-item inset. While any condition holds, a child whose layout.geometry owns its margin, border, and padding (self on all three) double-insets the entry's own geometry unless one of the child's insetFreeWhen conditions holds; eslint-plugin-kerfjs reports it as KUI-L204.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/propCondition" },
+          "minItems": 1
+        },
+        "insetFreeWhen": {
+          "description": "Prop values that render this inset-bearing entry with no margin, border, or padding of its own (Text flush). Any one condition makes the element inset-free.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/propCondition" },
+          "minItems": 1
+        },
         "rendersAs": {
           "description": "For a wrapper component: the cataloged roots it renders (package-qualified keys), any one of them or nothing. Composition checks treat an element of this entry as each declared root: a zone accepts it only if it accepts every root, and each root's parent contract applies to where it is placed.",
           "type": "array",
@@ -369,6 +381,26 @@
       },
       "additionalProperties": false
     },
+    "propCondition": {
+      "type": "object",
+      "required": ["prop", "equals"],
+      "properties": {
+        "prop": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9]*$",
+          "description": "A JSX prop of the element."
+        },
+        "equals": {
+          "anyOf": [
+            { "type": "string" },
+            { "type": "number" },
+            { "type": "boolean" }
+          ],
+          "description": "The statically written value that satisfies the condition. A bare boolean prop (<Text flush />) equals true."
+        }
+      },
+      "additionalProperties": false
+    },
     "cssValueProp": {
       "type": "object",
       "required": [

package/ai/components/README.md

@@ -73,12 +73,13 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Combobox](./combobox.md) — Let people pick an existing value or create a new one by typing (tags, labels, recipients), with the themed field chrome, the ARIA combobox pattern, and a touch-safe font size, without a native datalist or app CSS.
 - [TextField](./text-field.md) — Collect free text (names, addresses, notes, comments) with Kerf's field chrome, a visible or accessible label, supporting and validation text, and native input semantics.
 - [Checkbox](./checkbox.md) — Turn one independent option on or off in a form or settings list, including a parent whose children are partly checked, without Web Awesome.
+- [CheckboxGroup](./checkbox-group.md) — Choose any number of a few related options that should stay visible under one group label, with native keyboard behavior and form participation.
 - [RadioGroup](./radio-group.md) — Choose exactly one of a few options that should stay visible with room for a label and hint each, with native keyboard behavior and form participation.
 - [Switch](./switch.md) — Turn a setting on or off the moment it changes, such as live updates or a preference, without Web Awesome.
 - [Slider](./slider.md) — Let a person pick a value from a range where the relative position matters more than an exact number (volume, zoom, opacity, a threshold).
 - [PopupMenu](./popup-menu.md) — A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, drawn by Kerf as a native menu in the top layer.
 - [Button](./button.md) — Trigger an action from a dialog footer, a form, or content outside any Toolbar, with Kerf's button chrome and native button semantics.
-- [SplitButton](./split-button.md) — 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.
+- [SplitButton](./split-button.md) — 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.
 - [FilePicker](./file-picker.md) — Let people choose or drop files (attachments, evidence, imports) without app CSS: a link-toned browse trigger and a dashed drop target that highlights while dragging, both around visually hidden native file inputs.
 
 ## Kerf UI — Feedback
@@ -107,7 +108,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 ## Web Awesome — Forms
 
 - [Checkbox](./wa-checkbox.md) (avoid) — Ecosystem checkbox; use Kerf Checkbox.
-- [Checkbox Group](./wa-checkbox-group.md) (avoid) — Ecosystem checkbox group; use Kerf Checkbox rows or ChoiceChips.
+- [Checkbox Group](./wa-checkbox-group.md) (avoid) — Ecosystem checkbox group; use Kerf CheckboxGroup or ChoiceChips.
 - [Color Picker](./wa-color-picker.md) (avoid) — Ecosystem color picker; use the Kerf ColorField or ColorPicker.
 - [Input](./wa-input.md) (avoid) — Ecosystem text input; use Kerf TextField.
 - [Known Date](./wa-known-date.md) — Experimental segmented field for partially or fully known dates.

package/ai/components/button.md

@@ -13,6 +13,7 @@ Trigger an action from a dialog footer, a form, or content outside any Toolbar,
 - 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 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.
 
 **Not when:**
 
@@ -41,6 +42,7 @@ Exact prop names and types: [`@kerfjs/ui/button`](../public-api-signatures-v1.md
 - 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
@@ -48,6 +50,7 @@ Exact prop names and types: [`@kerfjs/ui/button`](../public-api-signatures-v1.md
 - disabled
 - link (href)
 - 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
 
 ## Composition
 
@@ -68,7 +71,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.
+- 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".
 - 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.
 

package/ai/components/checkbox-group.md

@@ -0,0 +1,89 @@
+# CheckboxGroup
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:checkbox-group` · Kerf UI · component · Controls
+
+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.
+
+## When to use
+
+Choose any number of a few related options that should stay visible under one group label, with native keyboard behavior and form participation.
+
+- 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.
+
+**Not when:**
+
+- 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:**
+
+- [Checkbox Group](./wa-checkbox-group.md) (prefer-over)
+- [Checkbox](./checkbox.md) (nearest) — Use Checkbox for one independent option, or a mixed parent above its children.
+- [RadioGroup](./radio-group.md) (nearest) — Use RadioGroup when exactly one option may be chosen.
+- [ChoiceChips](./choice-chips.md) (nearest) — Use ChoiceChips multiple for wrapping pill choices.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/checkbox-group` — exports `CheckboxGroup`.
+- CSS: the browser build of `@kerfjs/ui/checkbox-group` pulls its CSS automatically; import `@kerfjs/ui/checkbox-group.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/checkbox-group`](../public-api-signatures-v1.md#kerfjsuicheckbox-group) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- vertical or horizontal
+- per-choice hint
+- disabled choice
+- whole group disabled
+- hint
+- error
+- default or compact size
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Checkbox](./checkbox.md).
+
+## State and wiring
+
+**The app owns:** checked values; choices and their copy; validation and error copy.
+
+No wiring helper.
+
+## Geometry
+
+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.
+
+- 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.
+
+## 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.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-checkbox-group`, `kui-checkbox-group__label`, `kui-checkbox-group__choices`, `kui-checkbox-group__hint`, `kui-checkbox-group__error`.
+
+Never put `kui-checkbox-group`, `kui-checkbox-group__label`, `kui-checkbox-group__choices`, `kui-checkbox-group__hint`, `kui-checkbox-group__error` on an element you write; render `CheckboxGroup` instead (`KUI-L103`).
+
+Public tokens it reads: `--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`. 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: [Checkbox](./checkbox.md), [Checkbox Group](./wa-checkbox-group.md), [RadioGroup](./radio-group.md), [ChoiceChips](./choice-chips.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=checkbox-group`.

package/ai/components/checkbox.md

@@ -22,6 +22,7 @@ Turn one independent option on or off in a form or settings list, including a pa
 **Alternatives:**
 
 - [Checkbox](./wa-checkbox.md) (prefer-over)
+- [CheckboxGroup](./checkbox-group.md) (nearest) — Use CheckboxGroup for a labeled set of related options.
 - [Switch](./switch.md) (nearest) — Use Switch for a setting that applies immediately.
 - [ChoiceChips](./choice-chips.md) (nearest) — Use ChoiceChips multiple for several visible, wrapping choices.
 
@@ -63,7 +64,7 @@ Exact prop names and types: [`@kerfjs/ui/checkbox`](../public-api-signatures-v1.
 
 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 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.
 
 ## Accessibility
 
@@ -84,6 +85,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [LucideIcon](./lucide-icon.md), [Checkbox](./wa-checkbox.md), [Switch](./switch.md), [ChoiceChips](./choice-chips.md).
+- Components: [LucideIcon](./lucide-icon.md), [Checkbox](./wa-checkbox.md), [CheckboxGroup](./checkbox-group.md), [Switch](./switch.md), [ChoiceChips](./choice-chips.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=checkbox`.

package/ai/components/color-picker.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:color-picker` · Kerf UI · component · Controls
 
-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.
+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.
 
 ## When to use
 
@@ -25,7 +25,7 @@ Let a person choose any color precisely, by dragging, typing channel or hex valu
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/color-picker` — exports `ColorPicker`, `ColorPickerProps`, `ColorPickerMode`, `ColorPickerSamples`, `ColorPickerRootAttributes`, `colorPickerChannels`, `colorPickerAreaText`, `colorPickerStyle`.
+- JavaScript: `@kerfjs/ui/color-picker` — exports `ColorPicker`, `ColorPickerProps`, `ColorPickerMode`, `ColorPickerSamples`, `ColorPickerRootAttributes`, `colorPickerChannels`, `colorPickerSlider`, `ColorPickerSliderState`, `colorPickerAreaText`, `colorPickerStyle`.
 - CSS: the browser build of `@kerfjs/ui/color-picker` pulls its CSS automatically; import `@kerfjs/ui/color-picker.css` manually only without the `browser` export condition.
 - Wiring: `wireColorPickers` from `@kerfjs/ui/wire-color-pickers` (required).
 - Declared side effects: browser-condition-css.
@@ -37,7 +37,7 @@ Exact prop names and types: [`@kerfjs/ui/color-picker`](../public-api-signatures
 **Variants (configure, do not restyle):**
 
 - 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
@@ -66,20 +66,23 @@ Exact prop names and types: [`@kerfjs/ui/color-picker`](../public-api-signatures
 
 Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- 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.
 
 ## 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.
 
 ## Styling boundary
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public class hooks (select for layout placement only, never to change the component's look): `kui-color-picker`, `kui-color-picker__surface`, `kui-color-picker__area`, `kui-color-picker__area-thumb`, `kui-color-picker__hue`, `kui-color-picker__opacity`, `kui-color-picker__controls`, `kui-color-picker__mode-wrap`, `kui-color-picker__mode-icon`, `kui-color-picker__mode`, `kui-color-picker__tool`, `kui-color-picker__channels`, `kui-color-picker__hex-row`, `kui-color-picker__field`, `kui-color-picker__field-label`, `kui-color-picker__field--hex`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-color-picker`, `kui-color-picker__surface`, `kui-color-picker__area`, `kui-color-picker__area-thumb`, `kui-color-picker__sliders`, `kui-color-picker__slider`, `kui-color-picker__opacity`, `kui-color-picker__controls`, `kui-color-picker__mode-wrap`, `kui-color-picker__mode-icon`, `kui-color-picker__mode`, `kui-color-picker__tool`, `kui-color-picker__channels`, `kui-color-picker__hex-row`, `kui-color-picker__field`, `kui-color-picker__field-label`, `kui-color-picker__field--hex`.
 
-Never put `kui-color-picker`, `kui-color-picker__surface`, `kui-color-picker__area`, `kui-color-picker__area-thumb`, `kui-color-picker__hue`, `kui-color-picker__opacity`, `kui-color-picker__controls`, `kui-color-picker__mode-wrap`, `kui-color-picker__mode-icon`, `kui-color-picker__mode`, `kui-color-picker__tool`, `kui-color-picker__channels`, `kui-color-picker__hex-row`, `kui-color-picker__field`, `kui-color-picker__field-label`, `kui-color-picker__field--hex` on an element you write; render `ColorPicker` instead (`KUI-L103`).
+Never put `kui-color-picker`, `kui-color-picker__surface`, `kui-color-picker__area`, `kui-color-picker__area-thumb`, `kui-color-picker__sliders`, `kui-color-picker__slider`, `kui-color-picker__opacity`, `kui-color-picker__controls`, `kui-color-picker__mode-wrap`, `kui-color-picker__mode-icon`, `kui-color-picker__mode`, `kui-color-picker__tool`, `kui-color-picker__channels`, `kui-color-picker__hex-row`, `kui-color-picker__field`, `kui-color-picker__field-label`, `kui-color-picker__field--hex` on an element you write; render `ColorPicker` instead (`KUI-L103`).
 
 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/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`. 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/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