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

package/ai/components/README.md

@@ -29,6 +29,8 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Toolbar](./toolbar.md) — Leading, centered, and trailing toolbar composition.
 - [ToolbarControlGroup](./toolbar-control-group.md) — Provide complete toolbar action geometry through configuration, including semantic anchors, overflow containment, and dropdown menu insets without application CSS.
 - [Surface Scaffolds](./surface-scaffold.md) — Configure recurring dialog and popup geometry without consumer ::part() overrides.
+- [ListDetailDialog](./list-detail-dialog.md) — Present a selectable list beside the selected item's detail inside a modal, with the dialog's title and close control in the detail column and a one-pane drill-down on compact devices.
+- [WorkbenchDialog](./workbench-dialog.md) — Present an editing task with side panels (layers, an inspector) inside a modal, with the dialog's title and close control in the work area and rails that overlay the work area on compact devices instead of narrowing it.
 - [FloatingToolbar](./floating-toolbar.md) — A transparent, forced-dark toolbar that floats over its container's content.
 - [ToolbarText](./toolbar-text.md) — Extra-large through extra-small toolbar identity text.
 - [Text](./text.md) — Render paragraph semantics by default, h1 through h6 when selected, or geometry-free inline secondary text as a span while independently configuring quiet or danger tone, compact through extra-large size, or monospace font.
@@ -44,6 +46,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [ListInsetControl](./list-inset-control.md) — Apply the standard 8px outer margin to all physical sides of a self-bordered control by default, or only the sides selected with the canonical Sides contract.
 - [ListInsetText](./list-inset-text.md) — Apply the full 8px margin + 1px transparent border + 8px padding to all physical sides of bare text by default, or only the sides selected with the canonical Sides contract.
 - [ContentItem](./content-item.md) — Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.
+- [Disclosure](./disclosure.md) — Keep secondary or optional content one press away under a summary, or let a person open one of several sections at a time.
 
 ## Kerf UI — Navigation
 
@@ -51,22 +54,30 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [ListHeader](./list-header.md) — Fill the available section width by default, or shrink-wrap without outer geometry when inline, while splitting a dormant title and optional count or combined badge/status indicators from a logical-end action with an 18px visual; disclosure mode renders the title cluster as a button with a default production DisclosureArrow.
 - [ListActionRow](./list-action-row.md) — Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.
 - [ListItem](./list-item.md) — Selectable, disabled, trailing, and multiline action or link rows.
-- [Application Tabs](./application-tabs.md) — Show AppTab and TabBar in a complete controlled composition.
-- [AppTab](./tabs.md) — Render a controlled application tab with compact or icon-only presentation, a visible drop target, optional full-name display, and an optional pinned leading position.
+- [Application Tabs](./application-tabs.md) — Show TabBarItem and TabBar in a complete controlled composition.
+- [TabBarItem](./tabs.md) — Render a controlled application tab with compact or icon-only presentation, a visible drop target, optional full-name display, and an optional pinned leading position.
 - [TabBar](./tab-bar.md) — Controlled tab strips whose tabs shrink and scroll while fixed leading, trailing, and far-edge end actions remain visible.
 
 ## Kerf UI — Controls
 
 - [SegmentedControl](./segmented-control.md) — Controlled exclusive choices in toolbar, rounded-rectangle, and pill presentations.
 - [ChoiceChips](./choice-chips.md) — 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.
-- [Composer](./composer.md) — Write a chat message or prompt in a raised frame whose border turns brand while focus is within, with a field that grows between row bounds and a trailing send action.
-- [TokenSearchField](./token-search-field.md) — Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
+- [ColorSwatches](./color-swatches.md) — Let a person choose one color from a small fixed palette (a label, tag, or command color), or no color.
+- [ColorPicker](./color-picker.md) — Let a person choose any color precisely, by dragging, typing channel or hex values, sampling the screen, or picking a preset or saved sample.
+- [ColorField](./color-field.md) — Put a color choice in a form or inspector without keeping a full picker open.
+- [MessageComposer](./message-composer.md) — Write a chat message or prompt in a raised frame whose border turns brand while focus is within, with a field that grows between row bounds and a trailing send action.
+- [SearchField](./search-field.md) — Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
+- [TagField](./tag-field.md) — Collect a list of short values (labels, recipients, keywords) as removable tags, each submitted as its own form value.
 - [ResizableRegion](./resize.md) — Pointer and keyboard-operable split region with a customizable handle icon.
 - [Select](./select.md) — Choose one or more controlled values, keep unavailable choices visible, and optionally select all enabled choices or clear a multiple selection.
 - [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.
-- [PopupMenu](./popup-menu.md) — A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.
-- [IconButton](./icon-button.md) — Render an icon-only action as a square one form-control height on each side, so it matches an adjacent wa-input or Select, without ::part overrides.
-- [IconToggleButton](./icon-toggle-button.md) — Render an icon-only aria-pressed toggle in content or a pane footer, where a Toolbar does not belong, with the 44px contained geometry and raised pressed face of a single ToolbarControlGroup.
+- [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.
+- [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.
 - [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.
 
@@ -75,75 +86,82 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [AnchoredSurface](./anchored-surface.md) — Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
 - [Feedback](./feedback.md) — Banners, empty states, and labeled progress.
 - [StateBanner](./state-banner.md) — Present persistent inline feedback or attractive non-status emphasis with a named semantic tone.
+- [Toast](./toast.md) — Show a brief, non-blocking confirmation or status message that dismisses itself, without hand-written toast CSS.
+- [Tooltip](./tooltip.md) — Explain a control or value on hover and keyboard focus with a styled tooltip, without hand-written tooltip CSS.
 - [CornerStatus](./corner-status.md) — Show ongoing app-level progress such as "Loading…" or "Updating Tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
 - [EdgeActivityIndicator](./edge-activity-indicator.md) — Signal ambient background activity (server work, sync) along the top edge of the viewport without allocating layout or taking the pointer, with Kerf-owned motion and reduced-motion handling.
 - [EmptyState](./empty-state.md) — Actionable empty and busy content states.
 - [LoadingSpinner](./loading-spinner.md) — Meaningfully labeled or decorative progress.
+- [ProgressBar](./progress-bar.md) — Show how far a measurable task has gone (an upload, a migration, a quota) or that work of unknown size is under way.
+- [ProgressRing](./progress-ring.md) — Show compact progress (a claim's time remaining, a per-row upload) where a bar does not fit.
 - [Skeleton](./skeleton.md) — A subtle, unanimated loading placeholder block for a not-yet-known value slot.
 
 ## Web Awesome — Actions
 
-- [Button](./wa-button.md) — Action control with semantic variants, appearances, loading, and icon support.
-- [Button Group](./wa-button-group.md) (conditional) — Exceptional grouped actions; prefer Kerf SegmentedControl for exclusive choices.
+- [Button](./wa-button.md) (avoid) — Ecosystem action button; use Kerf Button.
+- [Button Group](./wa-button-group.md) (avoid) — Ecosystem button group; use Kerf ToolbarControlGroup, SplitButton, or SegmentedControl.
 - [Copy Button](./wa-copy-button.md) — Copies a supplied value and announces success or failure.
-- [Dropdown](./wa-dropdown.md) (conditional) — Action-menu primitive; prefer Kerf Select when choosing a value.
-- [Dropdown Item](./wa-dropdown-item.md) (conditional) — Action-menu row; prefer Kerf Select options for value selection.
+- [Dropdown](./wa-dropdown.md) (avoid) — Ecosystem action menu; use Kerf PopupMenu, or Select when choosing a value.
+- [Dropdown Item](./wa-dropdown-item.md) (avoid) — Ecosystem action-menu row; use Kerf PopupMenu items or Select choices.
 
 ## Web Awesome — Forms
 
-- [Checkbox](./wa-checkbox.md) — Binary form control with checked, indeterminate, and disabled states.
-- [Checkbox Group](./wa-checkbox-group.md) — Labels and validates a related set of checkboxes.
-- [Color Picker](./wa-color-picker.md) — Color input with swatches, formats, opacity, and eyedropper support.
-- [Input](./wa-input.md) — Text input with labels, hints, clear controls, and semantic appearances.
+- [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.
+- [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.
 - [Number Input](./wa-number-input.md) — Numeric input with keyboard and stepper controls.
-- [Option](./wa-option.md) (underlying) — Underlying ecosystem option; prefer choices passed to Kerf Select.
+- [Option](./wa-option.md) (avoid) — Ecosystem select option; use Kerf Select choices.
 - [OTP Input](./wa-otp-input.md) — Experimental segmented one-time-password input.
-- [Radio](./wa-radio.md) — Single-choice control used inside a radio group.
-- [Radio Group](./wa-radio-group.md) — Labels and manages a mutually exclusive set of radios.
+- [Radio](./wa-radio.md) (avoid) — Ecosystem radio; use Kerf RadioGroup choices.
+- [Radio Group](./wa-radio-group.md) (avoid) — Ecosystem radio group; use Kerf RadioGroup, ChoiceChips, or SegmentedControl.
 - [Rating](./wa-rating.md) — Interactive rating control with accessible labeling.
-- [Select](./wa-select.md) (underlying) — Underlying ecosystem field; prefer Kerf Select for app UI.
-- [Slider](./wa-slider.md) — Range input with markers and value tooltip support.
-- [Switch](./wa-switch.md) — Immediate on/off setting control.
-- [Textarea](./wa-textarea.md) — Multiline text field with labels, hints, and resize behavior.
+- [Select](./wa-select.md) (avoid) — Ecosystem select field; use Kerf Select.
+- [Slider](./wa-slider.md) (avoid) — Ecosystem range slider; use the Kerf Slider.
+- [Switch](./wa-switch.md) (avoid) — Ecosystem switch; use Kerf Switch.
+- [Textarea](./wa-textarea.md) (avoid) — Ecosystem multi-line input; use Kerf TextField with multiline.
 - [Time Input](./wa-time-input.md) — Experimental segmented time field with an optional picker.
+- [Tag Input](./wa-tag-input.md) (avoid) — Ecosystem tag input; use the Kerf TagField.
 
 ## Web Awesome — Layout
 
-- [Accordion](./wa-accordion.md) — Coordinates one or more collapsible content sections.
-- [Accordion Item](./wa-accordion-item.md) — Experimental labeled disclosure section used by an accordion.
-- [Card](./wa-card.md) — Groups related content and optional header, media, and footer slots.
-- [Details](./wa-details.md) — Single disclosure panel for secondary information.
-- [Dialog](./wa-dialog.md) — Modal surface for focused tasks and confirmations.
+- [Accordion](./wa-accordion.md) (avoid) — Ecosystem accordion; use Kerf Disclosures sharing a name.
+- [Accordion Item](./wa-accordion-item.md) (avoid) — Ecosystem accordion item; use a Kerf Disclosure in a named group.
+- [Card](./wa-card.md) (avoid) — Ecosystem card; use Kerf ContentItem or SunkenPanel.
+- [Details](./wa-details.md) (avoid) — Ecosystem disclosure; use the Kerf Disclosure.
+- [Dialog](./wa-dialog.md) (avoid) — Ecosystem dialog; use Kerf DialogSurface with openDialog and closeDialog.
 - [Divider](./wa-divider.md) — Visual separator for related groups of content.
-- [Drawer](./wa-drawer.md) — Edge-anchored modal surface for navigation or secondary tasks.
-- [Page](./wa-page.md) — Responsive application shell with navigation, banner, and main slots.
-- [Scroller](./wa-scroller.md) — Overflow container with accessible scrolling affordances.
-- [Split Panel](./wa-split-panel.md) (conditional) — Alternative split API; prefer Kerf ResizableRegion for application panes.
+- [Drawer](./wa-drawer.md) (avoid) — Ecosystem drawer; use Kerf DialogSurface sheets or CollapsiblePanel.
+- [Page](./wa-page.md) (avoid) — Ecosystem page shell; use the Kerf app layouts.
+- [Scroller](./wa-scroller.md) (avoid) — Ecosystem scroll container; use Kerf Pane scroll edges or ColumnTrack.
+- [Split Panel](./wa-split-panel.md) (avoid) — Alternative split API; use Kerf ResizableRegion for application panes.
 
 ## Web Awesome — Navigation
 
 - [Breadcrumb](./wa-breadcrumb.md) — Ordered navigation trail for the current location.
 - [Breadcrumb Item](./wa-breadcrumb-item.md) — One link or current-location item in a breadcrumb.
 - [Pagination](./wa-pagination.md) — Experimental page navigation for a bounded result set.
-- [Tab](./wa-tab.md) (conditional) — Ecosystem tab label; prefer Kerf TabBar or SegmentedControl.
-- [Tab Group](./wa-tab-group.md) (conditional) — Ecosystem tabs; prefer Kerf TabBar or SegmentedControl.
-- [Tab Panel](./wa-tab-panel.md) (conditional) — Ecosystem tab panel; prefer app-owned panels with Kerf navigation.
+- [Stepper](./wa-stepper.md) — Ordered indicator for a multi-step process, such as checkout or setup, with optional step-by-step navigation.
+- [Step](./wa-step.md) — Marker and label for one stage of a wa-stepper process, with completed, loading, disabled, and semantic-color states.
+- [Tab](./wa-tab.md) (avoid) — Ecosystem tab label; use Kerf TabBar or SegmentedControl.
+- [Tab Group](./wa-tab-group.md) (avoid) — Ecosystem tabs; use Kerf TabBar or SegmentedControl.
+- [Tab Panel](./wa-tab-panel.md) (avoid) — Ecosystem tab panel; use Kerf TabBar with application-owned panels.
 - [Tree](./wa-tree.md) (exceptional) — Specialized hierarchy; use only when the product requires tree behavior.
 - [Tree Item](./wa-tree-item.md) (exceptional) — Specialized tree row; use only as part of a required tree.
 
 ## Web Awesome — Feedback
 
-- [Badge](./wa-badge.md) — Compact status or count label with semantic variants.
-- [Callout](./wa-callout.md) — Prominent contextual message with semantic variants.
-- [Progress Bar](./wa-progress-bar.md) — Linear indicator for determinate or indeterminate progress.
-- [Progress Ring](./wa-progress-ring.md) — Circular indicator for determinate or indeterminate progress.
-- [Skeleton](./wa-skeleton.md) — Placeholder shape for content that is still loading.
-- [Spinner](./wa-spinner.md) — Compact indeterminate activity indicator.
-- [Tag](./wa-tag.md) — Compact categorization label with optional removal action.
-- [Toast](./wa-toast.md) — Placement-aware stack of transient notifications.
-- [Toast Item](./wa-toast-item.md) — One dismissible notification inside a toast stack.
-- [Tooltip](./wa-tooltip.md) — Brief contextual label anchored to a control.
+- [Badge](./wa-badge.md) (avoid) — Ecosystem badge; use Kerf Badge.
+- [Callout](./wa-callout.md) (avoid) — Ecosystem callout; use Kerf StateBanner.
+- [Progress Bar](./wa-progress-bar.md) (avoid) — Ecosystem progress bar; use the Kerf ProgressBar.
+- [Progress Ring](./wa-progress-ring.md) (avoid) — Ecosystem progress ring; use the Kerf ProgressRing.
+- [Skeleton](./wa-skeleton.md) (avoid) — Ecosystem placeholder; use Kerf Skeleton.
+- [Spinner](./wa-spinner.md) (avoid) — Ecosystem spinner; use Kerf LoadingSpinner.
+- [Tag](./wa-tag.md) (avoid) — Ecosystem tag; use Kerf Chip.
+- [Toast](./wa-toast.md) (avoid) — Ecosystem toast stack; use kerfjs/overlay toast() with @kerfjs/ui/overlay-toast.css.
+- [Toast Item](./wa-toast-item.md) (avoid) — Ecosystem toast item; use kerfjs/overlay toast() with @kerfjs/ui/overlay-toast.css.
+- [Tooltip](./wa-tooltip.md) (avoid) — Ecosystem tooltip; use kerfjs/overlay tooltip() with @kerfjs/ui/overlay-tooltip.css.
 
 ## Web Awesome — Media
 
@@ -163,11 +181,11 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Format Bytes](./wa-format-bytes.md) — Locale-aware byte and bit value formatter.
 - [Format Date](./wa-format-date.md) — Locale-aware date and time formatter.
 - [Format Number](./wa-format-number.md) — Locale-aware number, currency, unit, and percentage formatter.
-- [Include](./wa-include.md) — Loads and injects an external HTML fragment.
+- [Include](./wa-include.md) (avoid) — Ecosystem remote HTML include; fetch with kerfjs/async and render Kerf content.
 - [Intersection Observer](./wa-intersection-observer.md) — Declaratively emits visibility changes for slotted content.
 - [Mutation Observer](./wa-mutation-observer.md) — Declaratively emits DOM mutation records for slotted content.
-- [Popover](./wa-popover.md) — Anchored non-modal surface built on popup positioning.
-- [Popup](./wa-popup.md) (conditional) — Preferred low-level anchored positioning when Tooltip or Popover do not fit.
+- [Popover](./wa-popover.md) (avoid) — Ecosystem popover; use Kerf AnchoredSurface.
+- [Popup](./wa-popup.md) (avoid) — Ecosystem positioning primitive; use Kerf AnchoredSurface or kerfjs/overlay positioning.
 - [Random Content](./wa-random-content.md) — Experimental helper that selects one slotted item at random.
 - [Relative Time](./wa-relative-time.md) — Locale-aware human description of a date relative to now.
 - [Resize Observer](./wa-resize-observer.md) — Declaratively emits size changes for slotted content.
@@ -177,7 +195,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Desktop Application Shell](./recipe-app-shell.md) — App bar above a Workbench with resizable navigation and inspector rails, relocated rail toggles, narrow-container overlays, and explicit pane scroll owners.
 - [Navigation Sidebar](./recipe-navigation-sidebar.md) — Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.
 - [Workspace Header](./recipe-workspace-header.md) — Page identity with primary, secondary, and overflow actions that relocate at narrow widths.
-- [List-detail dialog](./recipe-list-detail-dialog.md) — Production modal laid out as a workbench: a full-height SplitView list sidebar with its own toolbar beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.
+- [List-detail dialog](./recipe-list-detail-dialog.md) — Production ListDetailDialog: a full-height list column with its own title beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.
 - [Composer Form](./recipe-composer-form.md) — One visible publishing-form surface with Toolbar heading hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.
 - [List Workspace States](./recipe-list-workspace-states.md) — Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.
 - [Compact Toolbar Choices and Actions](./recipe-compact-toolbar.md) — A compact toolbar that distinguishes grouped commands, a visible exclusive choice, a longer Select, and one ordinary action.

package/ai/components/application-tabs.md

@@ -8,9 +8,9 @@ Controlled document tabs with application-owned state and panels.
 
 ## When to use
 
-Show AppTab and TabBar in a complete controlled composition.
+Show TabBarItem and TabBar in a complete controlled composition.
 
-- Compose application state, panels, actions, overflow, and reordering around TabBar and AppTab.
+- Compose application state, panels, actions, overflow, and reordering around TabBar and TabBarItem.
 
 **Not when:**
 
@@ -36,7 +36,7 @@ No props: this entry has no JavaScript API.
 - Parents: any.
 - Contexts: `application-ui`.
 - Children: unrestricted.
-- Built from: [AppTab](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Card](./wa-card.md).
+- Built from: [TabBarItem](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Pane](./pane.md).
 
 ## State and wiring
 
@@ -60,6 +60,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [AppTab](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Card](./wa-card.md).
+- Components: [TabBarItem](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Pane](./pane.md).
 - Docs: [`docs/accessibility.md`](../../docs/accessibility.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
 - UX catalog route: `?component=application-tabs`.

package/ai/components/badge.md

@@ -37,6 +37,7 @@ Exact prop names and types: [`@kerfjs/ui/badge`](../public-api-signatures-v1.md#
 - leading icon
 - title tooltip and data-\* rootAttributes
 - maxWidth caps the badge and truncates long text with an ellipsis, defaulting the title to string or number content
+- placement="corner": a count or dot straddling the top-trailing corner of an icon-only Button or a ToolbarControlGroup button
 
 ## Composition
 

package/ai/components/button.md

@@ -0,0 +1,91 @@
+# Button
+
+<!-- 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:button` · Kerf UI · component · Controls
+
+A standalone action button: a native button (or a link with href) in a neutral, brand, or danger tone and a primary, secondary, or plain emphasis, at the 44px control height or compact.
+
+## When to use
+
+Trigger an action from a dialog footer, a form, or content outside any Toolbar, with Kerf's button chrome and native button semantics.
+
+- A dialog footer, a form, or content needs an action button: tone="brand" for the main action, tone="danger" for a destructive one, and emphasis="secondary" or "plain" for the quieter actions beside it.
+- A 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.
+
+**Not when:**
+
+- Do not use inside a ToolbarControlGroup; give the group plain \<button> controls, which it styles.
+- Do not use for an icon-only action; use an icon-only Button (with pressed for an on/off toggle).
+- Do not use for a menu trigger; use PopupMenu.
+
+**Alternatives:**
+
+- [Button](./wa-button.md) (prefer-over)
+- [ToolbarControlGroup](./toolbar-control-group.md) (nearest) — Inside a Toolbar, compose plain buttons in a ToolbarControlGroup.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/button` — exports `Button`.
+- CSS: the browser build of `@kerfjs/ui/button` pulls its CSS automatically; import `@kerfjs/ui/button.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/button`](../public-api-signatures-v1.md#kerfjsuibutton) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, brand, or danger tone
+- primary, secondary, or plain emphasis
+- default or compact size
+- rounded (default) or pill shape
+- 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
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LoadingSpinner](./loading-spinner.md).
+
+## State and wiring
+
+**The app owns:** the label and its delegated action; what a press does while loading; form ownership.
+
+No wiring helper.
+
+## 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
+
+- 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".
+- With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag.
+
+## Styling boundary
+
+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-button`, `kui-button__icon`, `kui-button__label`, `kui-button__spinner`.
+
+Never put `kui-button`, `kui-button__icon`, `kui-button__label`, `kui-button__spinner` on an element you write; render `Button` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-on-quiet`, `--kui-color-brand-border-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-on-quiet`, `--kui-color-danger-border-loud`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-layout-rounded-radius`. Set a token only where its public contract allows; prefer a prop.
+
+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: [LoadingSpinner](./loading-spinner.md), [Button](./wa-button.md), [ToolbarControlGroup](./toolbar-control-group.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=button`.

package/ai/components/checkbox.md

@@ -0,0 +1,89 @@
+# 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)
+- [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 align with the label text.
+
+## 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), [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/choice-chips.md

@@ -12,6 +12,7 @@ Choose one value, or with multiple any number of values, from a visible set too
 
 - 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:**
 
@@ -29,20 +30,23 @@ Choose one value, or with multiple any number of values, from a visible set too
 
 - 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) in `public-api-signatures-v1.md`. Do not infer props from examples.
+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) or multiple (checkboxes) selection
+- 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):
 
@@ -59,7 +63,9 @@ Exact prop names and types: [`@kerfjs/ui/choice-chips`](../public-api-signatures
 
 - value — controlled
 
-No wiring helper.
+**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
 

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`.