@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

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

@@ -0,0 +1,90 @@
+# Checkbox
+
+<!-- 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` · Kerf UI · component · Controls
+
+A native checkbox drawn as a Kerf box beside its label, with hint and error text on the label's column, a mixed (indeterminate) state, and native form participation.
+
+## When to use
+
+Turn one independent option on or off in a form or settings list, including a parent whose children are partly checked, without Web Awesome.
+
+- A form or settings list has an independent yes/no option that is submitted or applied with the rest of the form.
+- A parent option summarizes partly checked children: indeterminate, with wireCheckboxes(root).
+
+**Not when:**
+
+- Do not use for a setting that applies the moment it changes; use Switch.
+- Do not use for one choice among several; use RadioGroup, ChoiceChips, or SegmentedControl.
+- Do not use for several wrapping tag-like choices; use ChoiceChips multiple.
+
+**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.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/checkbox` — exports `Checkbox`, `wireCheckboxes`.
+- CSS: the browser build of `@kerfjs/ui/checkbox` pulls its CSS automatically; import `@kerfjs/ui/checkbox.css` manually only without the `browser` export condition.
+- Wiring: `wireCheckboxes` from `@kerfjs/ui/wire-checkboxes` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/checkbox`](../public-api-signatures-v1.md#kerfjsuicheckbox) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- checked
+- indeterminate
+- hint
+- error
+- required
+- disabled
+- default or compact size
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** checked and indeterminate state; validation and error copy; what a change does.
+
+**Wiring:** `wireCheckboxes` is optional.
+
+## Geometry
+
+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 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
+
+- A native \<input type="checkbox"> inside its \<label>, invisibly over the drawn box, so the label names it and pointer, keyboard, touch exploration, and forms reach the real control; Space toggles it and focus shows the focus ring on the box.
+- The hint and error form the input's aria-description; an error sets aria-invalid="true" and the danger border. indeterminate sets the native indeterminate property through wireCheckboxes, so assistive technology reports a mixed state.
+
+## 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`, `kui-checkbox__row`, `kui-checkbox__control`, `kui-checkbox__input`, `kui-checkbox__box`, `kui-checkbox__label`, `kui-checkbox__hint`, `kui-checkbox__error`.
+
+Never put `kui-checkbox`, `kui-checkbox__row`, `kui-checkbox__control`, `kui-checkbox__input`, `kui-checkbox__box`, `kui-checkbox__label`, `kui-checkbox__hint`, `kui-checkbox__error` on an element you write; render `Checkbox` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-brand-on-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`. 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: [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/chip.md

@@ -0,0 +1,80 @@
+# Chip
+
+<!-- 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:chip` · Kerf UI · component · Foundation
+
+A short tag with semantic or inherited tone, an optional accessible remove button, a native link and download form, or a native action button, including compact and disabled variants.
+
+## When to use
+
+Render removable tags, file or link chips, and activatable action chips without application rules on Web Awesome internals or anchor and button chrome.
+
+- Show a short tag that the application can remove through a delegated action, including a compact or disabled tag.
+- Show a downloadable file or a short link with chip geometry, such as the referenced files of a chat message; set tone inherit inside a brand-loud or neutral ContentItem bubble.
+- Offer a short value the user can activate to apply it, such as a filter token in a search syntax help popover that inserts itself into the query: set action (and itemId) so the whole chip is a native button.
+
+**Not when:**
+
+- Use Badge for non-interactive status and count metadata.
+- Do not use the remove button without a specific accessible name.
+- Use ListItemLink for a navigation row and ToolbarActionLink for a toolbar link.
+- Use ChoiceChips when the chips choose a persistent value with radio or checkbox state; an action chip fires a one-shot command.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/chip` — exports `Chip`.
+- CSS: the browser build of `@kerfjs/ui/chip` pulls its CSS automatically; import `@kerfjs/ui/chip.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#kerfjsuichip) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, info, pop, success, warning, danger, or inherit tone
+- quiet, solid, or outline appearance
+- pill or rounded shape
+- compact or default size
+- removable, link, action, or plain, enabled or disabled
+- rootAttributes: safe data-\* identity on the plain, link, or action root
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** tag text and identity; remove action and list update; link destination and download file name; action handler and its effect; disabled policy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## 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.
+- A link chip is a native anchor named by its visible label; external adds a safe rel, a new tab, and an "(opens in new tab)" name suffix, and a disabled link chip drops its destination and leaves the tab order.
+- The inherit tone paints no fill, so its label keeps the surrounding text contrast, and its focus ring follows the surrounding foreground.
+- An action chip is one native button (type button) named by its visible label or by actionLabel, which should include that label; Enter and Space activate it, it shows the focus ring on keyboard focus, and a disabled action chip is a disabled button that leaves the tab order. It cannot also be a link or carry a remove button.
+- Keep meaningful tag text visible because tone is supplementary.
+
+## 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-chip`.
+
+Never put `kui-chip` on an element you write; render `Chip` 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`).
+
+## Related
+
+- 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=chip`.

package/ai/components/choice-chips.md

@@ -0,0 +1,93 @@
+# ChoiceChips
+
+<!-- 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:choice-chips` · Kerf UI · component · Controls
+
+A wrapping set of separated pill chips backed by native radios (one exclusive value) or, with multiple, native checkboxes (any number of values), with optional leading color swatches or icons.
+
+## When to use
+
+Choose one value, or with multiple any number of values, from a visible set too large for a segmented track, such as a color palette with labeled swatches or a set of annotation intents.
+
+- Expose one exclusive choice among several visible options that must wrap onto more rows, such as a labeled color palette with swatches.
+- Set multiple when the person may turn any number of visible, wrapping options on or off, such as label filters or annotation intents.
+- Pick one icon from many (a command or category icon): presentation="icons" with an icon and label per choice and maxHeight to scroll a long grid, instead of an application grid of buttons.
+
+**Not when:**
+
+- Use SegmentedControl for a few compact choices on one track.
+- Use Select when the choice list is long or space is tight; a multiple Select keeps a long multi-value list behind one trigger.
+- Do not use it for removable tags (Chip).
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+- [Select](./select.md) (nearest)
+- [Radio Group](./wa-radio-group.md) (prefer-over) — Use ChoiceChips instead of button-appearance radios that must wrap; a joined button group wraps into ragged rows with shared borders.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/choice-chips` — exports `ChoiceChips`.
+- JavaScript: `@kerfjs/ui/css-values` — exports `fillColor`.
+- JavaScript: `@kerfjs/ui/wire-choice-chips` — exports `wireChoiceChips`, `readChoiceChips`.
+- CSS: the browser build of `@kerfjs/ui/choice-chips` pulls its CSS automatically; import `@kerfjs/ui/choice-chips.css` manually only without the `browser` export condition.
+- Wiring: `wireChoiceChips` from `@kerfjs/ui/wire-choice-chips` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/choice-chips`](../public-api-signatures-v1.md#kerfjsuichoice-chips), [`@kerfjs/ui/css-values`](../public-api-signatures-v1.md#kerfjsuicss-values), [`@kerfjs/ui/wire-choice-chips`](../public-api-signatures-v1.md#kerfjsuiwire-choice-chips) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- color swatch, transparent (struck-through) swatch, icon, or text-only choices
+- single (radios), multiple: 'toggle' (checkboxes), or multiple: true (a modifier-key multi-select listbox)
+- default or compact size
+- disabled group or disabled choices
+- required (single selection only)
+- presentation="icons": square 36px icon-only choices (an icon picker) named by hidden labels with hover titles, and maxHeight for a scrolling grid
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `choices[].swatch`: color grammar; raw values: forbid; shorthands `transparent`; helpers `fillColor`, `uiColor`, `colorVar` — e.g. `swatch: fillColor("#3b82f6")`
+
+## Composition
+
+- Parents: any.
+- Contexts: `wrapping-exclusive-choice`, `wrapping-multiple-choice`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+- value — controlled
+
+**Wiring:** `wireChoiceChips` is required.
+
+- Gives a multiple: true group its listbox selection: pointer and keyboard gestures, roving focus, aria-selected, hidden form inputs, and a change event on the group. Radio and toggle groups use native inputs and need no wiring.
+
+## Geometry
+
+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.
+
+## Accessibility
+
+- Name the radio group (or, with multiple, the checkbox group) with label or with labelledBy pointing at a visible heading.
+- Every choice keeps a visible text label; a swatch or icon is decorative.
+
+## 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-choice-chips`.
+
+Never put `kui-choice-chips` on an element you write; render `ChoiceChips` 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`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [Radio Group](./wa-radio-group.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#choicechips`](../../docs/accessibility.md#choicechips).
+- UX catalog route: `?component=choice-chips`.

package/ai/components/collapsible-panel.md

@@ -0,0 +1,103 @@
+# CollapsiblePanel
+
+<!-- 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:collapsible-panel` · Kerf UI · component · Structure
+
+A standalone controlled left or right rail or bottom drawer with standard collapse icons and optional compact-overlay behavior through wireSidebar.
+
+## When to use
+
+Add one independently collapsible peripheral panel without adopting the complete multi-panel Workbench shell.
+
+- An application needs one collapsible side rail or bottom drawer outside a full Workbench.
+- The panel should become a dismissable, focus-managed overlay on compact devices.
+
+**Not when:**
+
+- Do not use CollapsiblePanel for a complete editor shell with multiple coordinated rails and a drawer; use Workbench.
+- Do not preserve an empty icon-only rail when collapsed; move the restore control into adjacent visible chrome.
+
+**Alternatives:**
+
+- [Workbench](./workbench.md) (larger-composition) — Use Workbench when the central work area coordinates multiple peripheral panels.
+- [Collapsible Sidebar](./recipe-collapsible-sidebar.md) (recipe) — Use the production recipe for collapse, restore, compact overlay, focus, and persistence ownership.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/collapsible-panel` — exports `CollapsiblePanelSide`, `collapsiblePanelToggleIcon`, `CollapsiblePanelToolbarToggle`, `CollapsiblePanelToolbar`, `CollapsiblePanelToggleProps`, `CollapsiblePanelToggle`, `CollapsiblePanelProps`, `CollapsiblePanel`, `CollapsiblePanelRelocatedProps`, `CollapsiblePanelRelocated`.
+- CSS: the browser build of `@kerfjs/ui/collapsible-panel` pulls its CSS automatically; import `@kerfjs/ui/collapsible-panel.css` manually only without the `browser` export condition.
+- Wiring: `wireSidebar` from `@kerfjs/ui/wire-sidebar` (required).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/collapsible-panel`](../public-api-signatures-v1.md#kerfjsuicollapsible-panel), [`@kerfjs/ui/wire-sidebar`](../public-api-signatures-v1.md#kerfjsuiwire-sidebar), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- left rail
+- right rail
+- bottom drawer
+- collapsed
+- compact overlay
+- compact responsive replacement
+- hidden separator
+- slide, fade-slide, or instant content
+- clipped, scrolling, or popup-visible content
+- safe-area restore control
+- chrome dividers only while scrolled (wired by wireScrollDividers)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** controlled collapsed state; panel content and size; toggle placement; persistence policy; compact-device policy.
+
+**Wiring:** `wireSidebar`, `wireScrollDividers` is required.
+
+- Use wireSidebar as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-collapsible-responsive` on `the root passed to wireSidebar` (`wireSidebar`): With a deviceClass: "inline" on a wide device class, otherwise the compact presentation ("overlay" or "hidden"). Re-applied if a re-render drops it.
+- `data-collapsible-overlay` on `the root passed to wireSidebar` (`wireSidebar`): With a deviceClass on a compact device: "true" for the overlay presentation, "false" for hidden. Absent on a wide device class. Re-applied if a re-render drops it.
+- `data-morph-preserve` on `kui-collapsible-panel__backdrop` (`wireSidebar`): Keeps the injected compact-overlay backdrop through the application's re-render; the helper creates and removes the backdrop itself.
+- `data-scroll-overflow` on `kui-pane__content of each panel and work-area Pane` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
+- `data-scroll-divider` on `kui-pane__header and kui-pane__footer of each panel and work-area Pane` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it.
+
+## Geometry
+
+Margin: none · border: self · padding: child (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The panel owns its dock-edge separator and size track; its child content owns internal padding and scrolling.
+
+## Accessibility
+
+- Give the panel region and every collapse or restore control an accessible label.
+- Keep the restore control outside the disappearing panel and use wireSidebar for focus transfer, Escape, backdrop dismissal, and compact focus trapping.
+
+## 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-collapsible-panel`, `kui-collapsible-panel--left`, `kui-collapsible-panel--right`, `kui-collapsible-panel--bottom`, `kui-collapsible-panel__content`, `kui-collapsible-panel__restore`, `kui-collapsible-panel__backdrop`, `kui-collapsible-panel__toggle`.
+
+Never put `kui-collapsible-panel`, `kui-collapsible-panel--left`, `kui-collapsible-panel--right`, `kui-collapsible-panel--bottom`, `kui-collapsible-panel__content`, `kui-collapsible-panel__restore`, `kui-collapsible-panel__backdrop`, `kui-collapsible-panel__toggle` on an element you write; render `CollapsiblePanel` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-collapsible-panel-width`, `--kui-collapsible-panel-height`, `--kui-collapsible-panel-popup-z`, `--kui-collapsible-panel-overlay-z`, `--kui-collapsible-panel-restore-inset`, `--kui-collapsible-panel-restore-z`, `--kui-collapsible-panel-backdrop-z`. 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: [LucideIcon](./lucide-icon.md), [Workbench](./workbench.md), [Collapsible Sidebar](./recipe-collapsible-sidebar.md).
+- Docs: [`docs/collapsible-panel.md`](../../docs/collapsible-panel.md), [`docs/collapsible-panel.md#recipe-and-coverage`](../../docs/collapsible-panel.md#recipe-and-coverage).
+- UX catalog route: `?component=collapsible-panel`.

package/ai/components/color-field.md

@@ -0,0 +1,92 @@
+# ColorField
+
+<!-- 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:color-field` · Kerf UI · component · Controls
+
+A form field for a color: a label above a trigger that shows the color as a swatch (over a checkerboard) and its hex value, opening a ColorPicker in an AnchoredSurface below it, with a hint or error, compact size, required, disabled, and a hidden input for the hex value.
+
+## When to use
+
+Put a color choice in a form or inspector without keeping a full picker open.
+
+- A form or inspector row sets one color (a fill, border, or theme color): render ColorField with id, label, value, and mode, wire wireColorFields with onChange, and re-render with the reported value and mode.
+- The popup picker should offer presets or samples: pass them through wireColorFields' pickers option, keyed by field id.
+
+**Not when:**
+
+- Do not use it when the color is the main task of the view; show a ColorPicker inline.
+- Do not use it for a small curated palette; use ColorSwatches.
+- Do not use wa-color-picker.
+
+**Alternatives:**
+
+- [ColorPicker](./color-picker.md) (nearest) — Use an inline ColorPicker when choosing the color is the view's main task.
+- [ColorSwatches](./color-swatches.md) (nearest) — Use ColorSwatches for a fixed palette.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/color-field` — exports `ColorField`, `ColorFieldProps`, `ColorFieldSize`, `ColorFieldRootAttributes`.
+- CSS: the browser build of `@kerfjs/ui/color-field` pulls its CSS automatically; import `@kerfjs/ui/color-field.css` manually only without the `browser` export condition.
+- Wiring: `wireColorFields` from `@kerfjs/ui/wire-color-fields` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/color-field`](../public-api-signatures-v1.md#kerfjsuicolor-field) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- with a hint
+- compact size
+- with opacity or opaque (alpha)
+- error
+- disabled
+- required
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [ColorPicker](./color-picker.md), [AnchoredSurface](./anchored-surface.md), [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** the value and model (update them from onChange and re-render); per-field picker presets and samples (wireColorFields pickers); the field name and form association.
+
+**Wiring:** `wireColorFields` is required.
+
+- Use wireColorFields as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-value` on `kui-color-field` (`wireColorFields`): The committed color, updated by the wiring until the app re-renders, so reopening the picker starts from the last edit.
+- `data-mode` on `kui-color-field` (`wireColorFields`): The committed color model, updated the same way as data-value.
+
+## Geometry
+
+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 trigger matches TextField's box, label, hint, and error geometry.
+
+## Accessibility
+
+- The trigger is a button named by the label and the current hex value, with aria-haspopup dialog and aria-expanded; the hint and error describe it.
+- The picker opens in a non-modal AnchoredSurface named by the label; Escape or a press outside closes it and focus returns to the trigger.
+
+## 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-field`, `kui-color-field__label`, `kui-color-field__required`, `kui-color-field__trigger`, `kui-color-field__swatch`, `kui-color-field__hex`, `kui-color-field__chevron`, `kui-color-field__hint`, `kui-color-field__error`.
+
+Never put `kui-color-field`, `kui-color-field__label`, `kui-color-field__required`, `kui-color-field__trigger`, `kui-color-field__swatch`, `kui-color-field__hex`, `kui-color-field__chevron`, `kui-color-field__hint`, `kui-color-field__error` on an element you write; render `ColorField` 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`).
+
+## Related
+
+- Components: [ColorPicker](./color-picker.md), [AnchoredSurface](./anchored-surface.md), [LucideIcon](./lucide-icon.md), [ColorSwatches](./color-swatches.md).
+- Docs: [`docs/color-field.md`](../../docs/color-field.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=color-field`.

package/ai/components/color-picker.md

@@ -0,0 +1,93 @@
+# ColorPicker
+
+<!-- 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:color-picker` · Kerf UI · component · Controls
+
+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
+
+Let a person choose any color precisely, by dragging, typing channel or hex values, sampling the screen, or picking a preset or saved sample.
+
+- Any color is allowed and the person may need precision (a fill, stroke, or brand color): render ColorPicker with value, wire wireColorPickers with onChange, and re-render with the reported value and mode.
+- A design tool keeps presets or saved colors: pass presets, samples, and addSampleAction.
+
+**Not when:**
+
+- Do not use it for a small curated palette; use ColorSwatches.
+- Do not leave it always open in a form; use ColorField, which opens it from a swatch and hex trigger.
+- Do not use wa-color-picker or a native color input styled by hand.
+
+**Alternatives:**
+
+- [ColorSwatches](./color-swatches.md) (nearest) — Use ColorSwatches for a fixed palette.
+
+## Imports
+
+- 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.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/color-picker`](../public-api-signatures-v1.md#kerfjsuicolor-picker) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- with or without opacity
+- 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
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [ColorSwatches](./color-swatches.md), [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** the value and mode (update them from onChange and re-render); presets and samples, and adding to samples on addSampleAction; the field name and form association.
+
+**Wiring:** `wireColorPickers` is required.
+
+- Use wireColorPickers as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-shown` on `kui-color-picker__channel` (`wireColorPickers`): The text a channel, hex, or opacity field last showed, so leaving an unedited field commits nothing.
+- `data-count` on `kui-color-picker__channels` (`wireColorPickers`): How many channel fields the current model shows (1 for Grayscale, 3 otherwise).
+
+## Geometry
+
+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 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.
+- 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__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__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`).
+
+## Related
+
+- Components: [ColorSwatches](./color-swatches.md), [LucideIcon](./lucide-icon.md).
+- Docs: [`docs/color-picker.md`](../../docs/color-picker.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=color-picker`.