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

package/ai/components/slider.md

@@ -0,0 +1,84 @@
+# Slider
+
+<!-- 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:slider` · Kerf UI · component · Controls
+
+A value on a continuous or stepped range: a native range input drawn as a track, a brand fill, and a thumb, with a label row, an optional live readout and unit, labeled tick stops, a hint, compact size, and disabled state.
+
+## When to use
+
+Let a person pick a value from a range where the relative position matters more than an exact number (volume, zoom, opacity, a threshold).
+
+- A setting is a value in a known range and dragging to it is natural (volume, zoom, opacity): render Slider with min, max, step, and a label; add showValue and unit for a readout.
+- Discrete stops deserve names under the track: pass ticks.
+
+**Not when:**
+
+- Do not use it when the exact number matters or the range is huge; use a TextField with type number.
+- Do not use it for an on/off choice (use Switch) or for a few named options (use SegmentedControl).
+- Do not use wa-slider.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest) — Use a SegmentedControl for a handful of named options.
+- [TextField](./text-field.md) (nearest) — Use a numeric TextField when the exact value matters.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/slider` — exports `Slider`, `SliderProps`, `SliderSize`, `SliderTick`, `SliderRootAttributes`.
+- CSS: the browser build of `@kerfjs/ui/slider` pulls its CSS automatically; import `@kerfjs/ui/slider.css` manually only without the `browser` export condition.
+- Wiring: `wireSliders` from `@kerfjs/ui/wire-sliders` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/slider`](../public-api-signatures-v1.md#kerfjsuislider) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- labeled with a live readout and unit
+- stepped with labeled ticks
+- compact size
+- disabled
+- ariaLabel without a visible label
+- orientation="vertical" with a length, minimum at the bottom, for a volume control in a popup
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the value (read it on input or change through action) and re-rendering with it; min, max, step, and ticks; the label, hint, and unit.
+
+**Wiring:** `wireSliders` is optional.
+
+## 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.
+
+- It fills the available width with the shared block-content inset (a transparent 1px border and 8px padding), so its label sits on the text column.
+
+## Accessibility
+
+- It is a native range input: arrow keys, Page Up and Down, Home, and End step it, and the platform announces its value (with a unit, as aria-valuetext).
+- The label names it, the hint describes it, and the readout is hidden from assistive technology because the input already reports its value; forced colors draw a Highlight fill on a GrayText track.
+
+## 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-slider`, `kui-slider__header`, `kui-slider__label`, `kui-slider__value`, `kui-slider__input`, `kui-slider__ticks`, `kui-slider__tick`, `kui-slider__hint`.
+
+Never put `kui-slider`, `kui-slider__header`, `kui-slider__label`, `kui-slider__value`, `kui-slider__input`, `kui-slider__ticks`, `kui-slider__tick`, `kui-slider__hint` on an element you write; render `Slider` 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: [SegmentedControl](./segmented-control.md), [TextField](./text-field.md).
+- Docs: [`docs/slider.md`](../../docs/slider.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=slider`.

package/ai/components/surface-scaffold.md

@@ -4,13 +4,13 @@
 
 `@kerfjs/ui:surface-scaffold` · Kerf UI · component · Structure
 
-Typed Web Awesome dialog preferred widths and viewport bounds, presentation, and popup inset composition.
+A native modal dialog (DialogSurface) with Kerf's header, body, and footer chrome, typed preferred widths, viewport bounds, and presentations, plus a non-modal popover dialog and popup inset composition.
 
 ## When to use
 
 Configure recurring dialog and popup geometry without consumer ::part() overrides.
 
-- A Web Awesome dialog or dropdown needs a standard size, presentation, body/footer inset, or list-compatible menu inset.
+- A modal task needs a dialog: render a DialogSurface with a label (or labelledBy plus a heading), its body as children, and its buttons as footer, then open it with openDialog() and close it with closeDialog(), the close button, or any element with data-dialog-close. A raw Web Awesome dropdown that needs a list-compatible menu inset uses PopupSurface.
 - A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText.
 - A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions.
 - A dialog that must leave the page interactive and close on Escape or an outside press uses PopoverDialogSurface; one that fills its body with a SplitView or Pane uses height and bodyLayout="fill".
@@ -20,17 +20,17 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 
 **Not when:**
 
-- Do not use it as a generic layout wrapper or to replace application-owned modal state and focus lifecycle.
+- Do not use it as a generic layout wrapper, and do not toggle the dialog's open attribute (that opens it non-modally); open and close it with openDialog() and closeDialog().
 - Do not stack a dialog body inset around children that already own List or content-item geometry; use bodyInset none.
-- Do not put quiet secondary text of your own in a floating dialog header; it can fall below AA over the content passing beneath. A ToolbarText slotted as the dialog's label (or into header-actions) is fine: its title takes the normal text color and its description lifts halfway toward it, keeping AA.
+- Do not put quiet secondary text of your own in a floating dialog header; it can fall below AA over the content passing beneath. A ToolbarText as the dialog's heading (or in headerActions) is fine: its title takes the normal text color and its description lifts halfway toward it, keeping AA.
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/surface-scaffold` — exports `DialogSurface`, `PopoverDialogSurface`, `PopupSurface`, `wireOverlaySheets`.
+- JavaScript: `@kerfjs/ui/surface-scaffold` — exports `DialogSurface`, `openDialog`, `closeDialog`, `PopoverDialogSurface`, `PopupSurface`, `wireOverlaySheets`.
 - CSS: the browser build of `@kerfjs/ui/surface-scaffold` pulls its CSS automatically; import `@kerfjs/ui/surface-scaffold.css` manually only without the `browser` export condition.
 - Registration: import `@kerfjs/ui/surface-scaffold/register` once (a side effect).
 - Wiring: `wireOverlaySheets` from `@kerfjs/ui/wire-overlay-sheets` (optional).
-- Declared side effects: browser-condition-css, custom-element-registration.
+- Declared side effects: browser-condition-css, document-listeners.
 
 ## Props
 
@@ -55,6 +55,8 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 - standard, compact, or zero-inset popup menu
 - core kerfjs/overlay confirm/prompt/form/choice as a bottom sheet styled by @kerfjs/ui/overlay-sheet.css
 - resizable core kerfjs/overlay bottom sheet: the kui-overlay-sheet-resizable class plus wireOverlaySheets adds the resizable DialogSurface sheet grabber
+- header with label text or heading content, headerActions, a close button, and an optional footer; withoutHeader for content that owns its heading and close control
+- light dismiss (a backdrop press closes; otherwise the panel pulses)
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
 
@@ -69,11 +71,11 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 - Parents: any.
 - Contexts: `application-ui`.
 - Children: unrestricted.
-- Built from: [Dialog](./wa-dialog.md), [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md).
+- Built from: [LucideIcon](./lucide-icon.md), [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md).
 
 ## State and wiring
 
-**The app owns:** open state; focus lifecycle; dismissal policy; content; outer placement; whether core kerfjs/overlay dialogs presented as bottom sheets take this package's geometry and slide (import @kerfjs/ui/overlay-sheet.css; exitClass 'kui-overlay-sheet-exit' for the slide out; the kui-overlay-sheet-resizable class plus wireOverlaySheets for a resize grabber).
+**The app owns:** open state (openDialog and closeDialog); whether a close request may proceed (cancel kui-request-close to keep the dialog open; the panel pulses); dismissal policy (lightDismiss); content, heading, header actions, and footer; outer placement; whether core kerfjs/overlay dialogs presented as bottom sheets take this package's geometry and slide (import @kerfjs/ui/overlay-sheet.css; exitClass 'kui-overlay-sheet-exit' for the slide out; the kui-overlay-sheet-resizable class plus wireOverlaySheets for a resize grabber).
 
 **Wiring:** `wireOverlaySheets` is optional.
 
@@ -83,19 +85,20 @@ Margin: parent · border: child · padding: self (layout role: structure). `self
 
 ## Accessibility
 
-- Supply the wrapped wa-dialog label and retain Web Awesome's native modal and focus behavior.
+- 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.
 - 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 falls back to Web Awesome's under prefers-reduced-motion.
+- 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.
 
 ## 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-dialog-surface`, `kui-popover-dialog-surface`, `kui-popup-surface`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-dialog-surface`, `kui-dialog-surface__body`, `kui-dialog-surface__close`, `kui-dialog-surface__footer`, `kui-dialog-surface__header`, `kui-dialog-surface__header-actions`, `kui-dialog-surface__title`, `kui-popover-dialog-surface`, `kui-popup-surface`.
 
-Never put `kui-dialog-surface` on an element you write; render `DialogSurface` instead (`KUI-L103`).
+Never put `kui-dialog-surface`, `kui-dialog-surface__body`, `kui-dialog-surface__close`, `kui-dialog-surface__footer`, `kui-dialog-surface__header`, `kui-dialog-surface__header-actions`, `kui-dialog-surface__title` on an element you write; render `DialogSurface` instead (`KUI-L103`).
 
 Never put `kui-popover-dialog-surface` on an element you write; render `PopoverDialogSurface` instead (`KUI-L103`).
 
@@ -107,6 +110,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Dialog](./wa-dialog.md), [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md).
+- Components: [LucideIcon](./lucide-icon.md), [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md).
 - Docs: [`docs/surface-scaffold.md`](../../docs/surface-scaffold.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
 - UX catalog route: `?component=surface-scaffold`.

package/ai/components/switch.md

@@ -0,0 +1,81 @@
+# Switch
+
+<!-- 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:switch` · Kerf UI · component · Controls
+
+An on/off setting that applies immediately: a native checkbox with role="switch" drawn as a track and thumb beside its label, with a hint on the label's column.
+
+## When to use
+
+Turn a setting on or off the moment it changes, such as live updates or a preference, without Web Awesome.
+
+- A setting takes effect immediately when toggled, in a settings list or a pane footer.
+
+**Not when:**
+
+- Do not use for an option a form submits later; use Checkbox.
+- Do not use for an icon-only toolbar toggle; use an icon-only Button with pressed, or a ToolbarControlGroup toggle.
+
+**Alternatives:**
+
+- [Switch](./wa-switch.md) (prefer-over)
+- [Checkbox](./checkbox.md) (nearest) — Use Checkbox for an option a form submits.
+- [Button](./button.md) (nearest) — Use an icon-only Button with pressed for an icon-only toggle.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/switch` — exports `Switch`.
+- CSS: the browser build of `@kerfjs/ui/switch` pulls its CSS automatically; import `@kerfjs/ui/switch.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/switch`](../public-api-signatures-v1.md#kerfjsuiswitch) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- on or off
+- hint
+- disabled
+- default or compact size
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** checked state; applying the setting.
+
+No wiring helper.
+
+## 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 35×20 track (31.5×18 compact) 8px (7px) before its label; the hint aligns with the label text.
+
+## Accessibility
+
+- A native \<input type="checkbox" role="switch"> inside its \<label>, invisibly over the drawn track, so the label names it and assistive technology announces on or off; Space toggles it and focus shows the focus ring on the track. The hint is its aria-description. The thumb's slide is skipped when reduced motion is preferred.
+
+## 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-switch`, `kui-switch__row`, `kui-switch__control`, `kui-switch__input`, `kui-switch__track`, `kui-switch__thumb`, `kui-switch__label`, `kui-switch__hint`.
+
+Never put `kui-switch`, `kui-switch__row`, `kui-switch__control`, `kui-switch__input`, `kui-switch__track`, `kui-switch__thumb`, `kui-switch__label`, `kui-switch__hint` on an element you write; render `Switch` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-neutral-border-normal`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-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: [Switch](./wa-switch.md), [Checkbox](./checkbox.md), [Button](./button.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=switch`.

package/ai/components/tab-bar.md

@@ -52,12 +52,12 @@ Exact prop names and types: [`@kerfjs/ui/tab-bar`](../public-api-signatures-v1.m
 
 - Parents: any.
 - Contexts: `tabpanel-navigation`.
-- Children: only `app-tab` (required: `app-tab`).
-- Built from: [AppTab](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
+- Children: only `tab-bar-item` (required: `tab-bar-item`).
+- Built from: [TabBarItem](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
 
 Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
 
-- `tabs` — JSX prop `children`; accepts [AppTab](./tabs.md); at least 1.
+- `tabs` — JSX prop `children`; accepts [TabBarItem](./tabs.md); at least 1.
 - `leading` — JSX prop `leading`; accepts [ToolbarControlGroup](./toolbar-control-group.md); 0–1.
 - `trailing` — JSX prop `trailing`; accepts [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md); 0–1.
 - `end` — JSX prop `end`; accepts [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md); 0–1.
@@ -73,8 +73,8 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 **Wiring-owned state attributes** — never render, remove, or branch on these as app state:
 
-- `data-tab-dragging` on `AppTab (data-component="app-tab")` (`wireTabBars`): "true" on the tab being dragged.
-- `data-tab-drop-position` on `AppTab (data-component="app-tab")` (`wireTabBars`): "before" or "after" on the tab under the pointer: where the dragged tab would land.
+- `data-tab-dragging` on `TabBarItem (data-component="tab-bar-item")` (`wireTabBars`): "true" on the tab being dragged.
+- `data-tab-drop-position` on `TabBarItem (data-component="tab-bar-item")` (`wireTabBars`): "before" or "after" on the tab under the pointer: where the dragged tab would land.
 - `data-tab-autoscroll` on `kui-tab-bar__tabs` (`wireTabBars`): "start" or "end" while a drag near that edge auto-scrolls the strip.
 - `data-scroll-overflow` on `kui-tab-bar__tabs` (`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 `chrome named in wireScrollDividers targets (a TabBar strip has none)` (`wireScrollDividers`): The sides, in t/r/b/l order, on which that chrome currently draws its scroll divider. Re-applied if a re-render drops it.
@@ -109,6 +109,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [AppTab](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [Tab Group](./wa-tab-group.md).
+- Components: [TabBarItem](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [Tab Group](./wa-tab-group.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
 - UX catalog route: `?component=tab-bar`.

package/ai/components/tab-navigator.md

@@ -20,7 +20,7 @@ Switch among two to five co-equal top-level destinations on compact devices whil
 
 **Alternatives:**
 
-- [AppTab](./tabs.md) (semantic-alternative) — Use TabBar and AppTab for document-style tabpanels, overflow, closing, or reordering.
+- [TabBarItem](./tabs.md) (semantic-alternative) — Use TabBar and TabBarItem for document-style tabpanels, overflow, closing, or reordering.
 - [Workbench](./workbench.md) (roomy-alternative) — Promote top-level destinations to a rail or sidebar on desktop-class layouts.
 
 ## Imports
@@ -100,6 +100,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Badge](./badge.md), [AppTab](./tabs.md), [Workbench](./workbench.md).
+- Components: [Badge](./badge.md), [TabBarItem](./tabs.md), [Workbench](./workbench.md).
 - Docs: [`docs/tab-navigator.md`](../../docs/tab-navigator.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
 - UX catalog route: `?component=tab-navigator`.

package/ai/components/tabs.md

@@ -1,4 +1,4 @@
-# AppTab
+# TabBarItem
 
 <!-- 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`. -->
 
@@ -22,13 +22,13 @@ Render a controlled application tab with compact or icon-only presentation, a vi
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/app-tab` — exports `AppTab`.
-- CSS: the browser build of `@kerfjs/ui/app-tab` pulls its CSS automatically; import `@kerfjs/ui/app-tab.css` manually only without the `browser` export condition.
+- JavaScript: `@kerfjs/ui/tab-bar-item` — exports `TabBarItem`.
+- CSS: the browser build of `@kerfjs/ui/tab-bar-item` pulls its CSS automatically; import `@kerfjs/ui/tab-bar-item.css` manually only without the `browser` export condition.
 - Declared side effects: browser-condition-css.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/app-tab`](../public-api-signatures-v1.md#kerfjsuiapp-tab) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/tab-bar-item`](../public-api-signatures-v1.md#kerfjsuitab-bar-item) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
@@ -80,11 +80,11 @@ Margin: none · border: self · padding: self (layout role: navigation). `self`
 
 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-app-tab`, `kui-app-tab__close`, `kui-app-tab__close-icon`, `kui-app-tab__name`, `kui-app-tab__select`, `kui-app-tab__trailing`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-tab-bar-item`, `kui-tab-bar-item__close`, `kui-tab-bar-item__close-icon`, `kui-tab-bar-item__name`, `kui-tab-bar-item__select`, `kui-tab-bar-item__trailing`.
 
-Never put `kui-app-tab`, `kui-app-tab__close`, `kui-app-tab__close-icon`, `kui-app-tab__name`, `kui-app-tab__select`, `kui-app-tab__trailing` on an element you write; render `AppTab` instead (`KUI-L103`).
+Never put `kui-tab-bar-item`, `kui-tab-bar-item__close`, `kui-tab-bar-item__close-icon`, `kui-tab-bar-item__name`, `kui-tab-bar-item__select`, `kui-tab-bar-item__trailing` on an element you write; render `TabBarItem` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-app-tab-attention-color`, `--kui-app-tab-color`, `--kui-app-tab-drop-indicator`, `--kui-app-tab-drop-target-background`, `--kui-app-tab-drop-target-color`, `--kui-app-tab-drop-target-ring`, `--kui-app-tab-hover-background`, `--kui-app-tab-pinned-background`, `--kui-app-tab-pinned-hover-background`, `--kui-app-tab-selected-background`, `--kui-app-tab-selected-border`, `--kui-app-tab-selected-color`, `--kui-color-brand-border-normal`, `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-color-text`, `--kui-focus-ring`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-shadow-s`, `--kui-space-2xs`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-tab-bar-item-attention-color`, `--kui-tab-bar-item-color`, `--kui-tab-bar-item-drop-indicator`, `--kui-tab-bar-item-drop-target-background`, `--kui-tab-bar-item-drop-target-color`, `--kui-tab-bar-item-drop-target-ring`, `--kui-tab-bar-item-hover-background`, `--kui-tab-bar-item-pinned-background`, `--kui-tab-bar-item-pinned-hover-background`, `--kui-tab-bar-item-selected-background`, `--kui-tab-bar-item-selected-border`, `--kui-tab-bar-item-selected-color`, `--kui-color-brand-border-normal`, `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-color-text`, `--kui-focus-ring`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-shadow-s`, `--kui-space-2xs`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 

package/ai/components/tag-field.md

@@ -0,0 +1,86 @@
+# TagField
+
+<!-- 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:tag-field` · Kerf UI · component · Controls
+
+A form field that collects short values as removable tags: SearchField's token editor in its form-field presentation, with a label, hint or error, a leading tag glyph, chips that edit or remove, a clear button, an optional max, and a hidden input per tag submitted under its name.
+
+## When to use
+
+Collect a list of short values (labels, recipients, keywords) as removable tags, each submitted as its own form value.
+
+- A form collects several short values of one kind (labels, recipients, keywords): render TagField with tags and name, wire wireTagFields with onChange, and re-render with the list it reports.
+- Values must be checked (an email shape, a known label) or capped: pass normalize and max, and show onReject's reason as the field's error.
+
+**Not when:**
+
+- Do not use it for search filters; SearchField combines free text with ordered, editable filter tokens.
+- Do not use it to pick from a short fixed set; use ChoiceChips or a multiple Select.
+- Do not use wa-tag-input.
+
+**Alternatives:**
+
+- [SearchField](./search-field.md) (nearest) — Use SearchField when the tokens are search filters rather than submitted form values.
+- [ChoiceChips](./choice-chips.md) (nearest) — Use ChoiceChips to pick several from a short known set.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/tag-field` — exports `TagField`, `TagFieldProps`.
+- CSS: the browser build of `@kerfjs/ui/tag-field` pulls its CSS automatically; import `@kerfjs/ui/tag-field.css` manually only without the `browser` export condition.
+- Wiring: `wireTagFields` from `@kerfjs/ui/wire-tag-fields` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/tag-field`](../public-api-signatures-v1.md#kerfjsuitag-field) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- labels with a hint
+- validated with max and an error
+- required
+- disabled
+- custom delimiters and duplicate policy (wireTagFields options)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [SearchField](./search-field.md), [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** the tag list (update it from onChange and re-render); validation and normalization (normalize) and showing refusals (onReject, error); the field name and form association.
+
+**Wiring:** `wireTagFields` is required.
+
+- Use wireTagFields as documented.
+
+## Geometry
+
+Margin: child · border: child · padding: child (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The SearchField form-field presentation draws the label, frame, chips, and hint; TagField adds no geometry of its own.
+
+## Accessibility
+
+- The editor is named by the visible label and described by the hint or error; each chip has an edit button (its label) and a remove button named for the tag.
+- Enter or a delimiter adds the typed text, Backspace at the start removes the last tag, ArrowLeft and ArrowRight move between chips and the editor, and Backspace or Delete on a focused chip removes it.
+
+## 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-tag-field`.
+
+Never put `kui-tag-field` on an element you write; render `TagField` 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: [SearchField](./search-field.md), [LucideIcon](./lucide-icon.md), [ChoiceChips](./choice-chips.md).
+- Docs: [`docs/tag-field.md`](../../docs/tag-field.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=tag-field`.

package/ai/components/text-field.md

@@ -0,0 +1,98 @@
+# TextField
+
+<!-- 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:text-field` · Kerf UI · component · Controls
+
+A labeled single-line input or multi-line textarea with hint and error text, an optional leading icon, clear button, and character count, at the 44px control height or compact.
+
+## When to use
+
+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.
+
+- A form or dialog collects a line of free text: label names it (or ariaLabel when nearby content already does), hint explains it, and error reports a validation problem.
+- People write a longer note or message: multiline with rows, or rows plus maxRows to grow with the content; maxLength with showCount shows the remaining budget.
+- A filter or search field needs a leading icon and a clear button: icon and clearable.
+
+**Not when:**
+
+- Do not use when only existing values are allowed; use Select.
+- Do not use when people pick among suggestions or create tags; use Combobox.
+- Do not use for search text with removable filter tokens; use SearchField.
+- Do not use for a chat-style message with a send action; use MessageComposer.
+
+**Alternatives:**
+
+- [Input](./wa-input.md) (prefer-over)
+- [Textarea](./wa-textarea.md) (prefer-over)
+- [Combobox](./combobox.md) (nearest) — Use Combobox when people pick among suggestions or create a value.
+- [MessageComposer](./message-composer.md) (nearest) — Use MessageComposer for a message with a send action.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/text-field` — exports `TextField`, `wireTextFields`.
+- CSS: the browser build of `@kerfjs/ui/text-field` pulls its CSS automatically; import `@kerfjs/ui/text-field.css` manually only without the `browser` export condition.
+- Wiring: `wireTextFields` from `@kerfjs/ui/wire-text-fields` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/text-field`](../public-api-signatures-v1.md#kerfjsuitext-field) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- visible label or ariaLabel
+- hint
+- error
+- default or compact size
+- leading icon
+- clearable
+- multiline (fixed rows or growing to maxRows)
+- maxLength with a live count
+- disabled
+- read-only
+- required
+- email, password, search, url, tel, or number type
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** value; validation and error copy; hint copy; what a cleared field means.
+
+**Wiring:** `wireTextFields` is optional.
+
+## 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.
+
+- Label, hint, and error sit on the value's text column (1px border + 8px padding); the 44px box matches Button and Select, and compact matches their compact 33px.
+
+## Accessibility
+
+- The whole field is a \<label> around a native \<input> or \<textarea>, so clicking anywhere on it focuses the field; the input is named by label (aria-label, with the visible label text hidden from assistive technology so the clear button and count stay out of the name) or by ariaLabel. Focus shows the standard focus ring around the box.
+- The hint and error are visible below the field and form the input's aria-description; an error also sets aria-invalid="true". The clear button is a native button named by clearLabel (default Clear), hidden while the field is empty, and returns focus to the field.
+- Compact text grows to 16px on coarse-pointer touch screens so iOS does not zoom on focus.
+
+## 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-text-field`, `kui-text-field__label`, `kui-text-field__required`, `kui-text-field__box`, `kui-text-field__icon`, `kui-text-field__input`, `kui-text-field__clear`, `kui-text-field__hint`, `kui-text-field__error`, `kui-text-field__footer`, `kui-text-field__count`.
+
+Never put `kui-text-field`, `kui-text-field__label`, `kui-text-field__required`, `kui-text-field__box`, `kui-text-field__icon`, `kui-text-field__input`, `kui-text-field__clear`, `kui-text-field__hint`, `kui-text-field__error`, `kui-text-field__footer`, `kui-text-field__count` on an element you write; render `TextField` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-surface`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`, `--kui-radius-circle`. 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), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Combobox](./combobox.md), [MessageComposer](./message-composer.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=text-field`.

package/ai/components/text.md

@@ -43,6 +43,7 @@ Exact prop names and types: [`@kerfjs/ui/text`](../public-api-signatures-v1.md#k
 - align start (default), center, or end for centered status copy or trailing values
 - controlMargins selects exterior 8px gutters with canonical physical Sides
 - wrap normal, anywhere, nowrap, or truncate; truncate places its ellipsis at the end, the start (keeping the tail), or the middle (keeping the last path segment or a character suffix)
+- size="medium" for a 16px heading, such as an in-list group title that wraps a long name
 
 ## Composition
 

package/ai/components/toast.md

@@ -0,0 +1,85 @@
+# Toast
+
+<!-- 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:toast` · Kerf UI · CSS composition · Feedback
+
+Styling for kerfjs/overlay's toast(): a bottom-edge region of stacked, auto-dismissing notifications on the raised surface, with info, success, and warning tones, StateBanner content, and enter and exit motion.
+
+## When to use
+
+Show a brief, non-blocking confirmation or status message that dismisses itself, without hand-written toast CSS.
+
+- A completed action needs brief, non-blocking confirmation (saved, copied, published): import @kerfjs/ui/overlay-toast.css once and call toast() from kerfjs/overlay with exitClass 'kui-toast-exit' and exitDuration 200.
+- A status message needs a tone or an icon and detail: pass variant ('info', 'success', 'warning') for a plain message, or render a StateBanner as the toast's only content.
+- A rapid sequence (repeated copy actions) should collapse to the latest message: mode 'replace'.
+
+**Not when:**
+
+- Do not use a toast for an error the person must act on or a decision; use a StateBanner in the affected surface, or a DialogSurface.
+- Do not put controls that must stay reachable in a toast that dismisses itself; set duration 0 and dismiss it from your own action, or use a StateBanner.
+- Do not hand-write toast placement, stacking, or motion CSS, and do not use wa-toast.
+
+**Alternatives:**
+
+- [StateBanner](./state-banner.md) (nearest) — Use a StateBanner in place for a persistent status or an error tied to one surface.
+
+## Imports
+
+- CSS: import `@kerfjs/ui/overlay-toast.css` once.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- plain message on the raised surface
+- info, success, or warning tone (variant)
+- StateBanner as the toast's only content, taking the banner's tone and chrome
+- replace mode collapsing a rapid sequence to the latest
+- bottom-edge region by default, or top-edge stacking on an app-owned container with data-placement="top"
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [StateBanner](./state-banner.md).
+
+## State and wiring
+
+**The app owns:** when to show a toast and its message; duration, variant, and replace mode; an app-owned container with data-placement="top" for top-edge stacking; dismissing a persistent (duration 0) toast.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The region insets 16px from the viewport edge plus the safe area and caps its width at 480px; toasts stack with an 8px gap.
+
+## Accessibility
+
+- The core region is an aria-live polite region and each toast is role status, so assistive technology announces it without moving focus.
+- Toasts dismiss themselves after four seconds by default; give longer messages a longer duration, and never rely on a toast for the only path to an action.
+- The entrance and exit only fade under prefers-reduced-motion or the static-effects switch, and forced colors draw a CanvasText border on Canvas.
+
+## 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): `kerf-toasts`, `kerf-toast`, `kui-toast-exit`.
+
+Classes an application may place on its own elements: `kerf-toasts`, `kerf-toast`, `kui-toast-exit`.
+
+Public tokens it reads: `--kui-overlay-toast-z-index`. 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: [StateBanner](./state-banner.md).
+- Docs: [`docs/overlay-toast.md`](../../docs/overlay-toast.md), [`docs/component-selection.md#web-awesome-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=toast`.