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

package/ai/components/sunken-panel.md

@@ -0,0 +1,79 @@
+# SunkenPanel
+
+<!-- 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:sunken-panel` · Kerf UI · component · Structure
+
+A rounded or square-corner lowered application surface with one compact inset and a vertical content stack.
+
+## When to use
+
+Group a vertical list of application content on a visually lowered surface with one owned 8px inset and an explicit rounded or square-corner shape.
+
+- A main content region or nested work area needs a darker/lowered background and one compact inset around a vertical stack.
+- Use the default rounded shape for an inset surface; choose square for a flush or edge-to-edge application area.
+
+**Not when:**
+
+- Do not use it merely to add padding, as a substitute for Pane anatomy, or around children that already own the same outer surface.
+
+**Alternatives:**
+
+- [Application Layout](./layout.md) (composes-with) — Use layout roles for pane, toolbar, scroll, and ordinary content-stack ownership.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/sunken-panel` — exports `SunkenPanel`, `ensureSunkenTexture`.
+- CSS: the browser build of `@kerfjs/ui/sunken-panel` pulls its CSS automatically; import `@kerfjs/ui/sunken-panel.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/sunken-panel`](../public-api-signatures-v1.md#kerfjsuisunken-panel) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- rounded surface
+- square-corner surface
+- unnamed surface
+- named region
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** region semantics and accessible name; corner shape; scroll ownership; child ordering and content; optional keyboard or programmatic focus (tabIndex) and persistent outline (outlined).
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The root owns one 8px inset and vertical gap; children own their borders and internal geometry.
+
+## Accessibility
+
+- Pass ariaLabel only when the surface is a distinct named region; otherwise it remains a non-landmark grouping.
+
+## 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-sunken-panel`.
+
+Never put `kui-sunken-panel` on an element you write; render `SunkenPanel` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-sunken-panel-background`, `--kui-sunken-panel-foreground`, `--kui-sunken-panel-gap`, `--kui-sunken-panel-padding`, `--kui-sunken-panel-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: [Application Layout](./layout.md).
+- Docs: [`docs/sunken-panel.md`](../../docs/sunken-panel.md), [`docs/sunken-panel.md#ownership`](../../docs/sunken-panel.md#ownership).
+- UX catalog route: `?component=sunken-panel`.

package/ai/components/surface-scaffold.md

@@ -0,0 +1,117 @@
+# Surface Scaffolds
+
+<!-- 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:surface-scaffold` · Kerf UI · component · Structure
+
+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 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".
+- A chat-style dialog floats its composer over the transcript with footerPresentation="floating" and keeps a heading or notice above one scrolling transcript with bodyLayout="fill-last".
+- A phone-first task (compose, quick edit, a picker) should rise from the bottom edge as a sheet the person can resize: presentation="bottom-sheet" with height, and resizable with minHeight / maxHeight bounds.
+- A dialog's title bar should float over the body on the translucent chrome material so a transcript scrolls visibly beneath both the title bar and a floating composer (headerPresentation="floating" with bodyLayout="fill" and a List or Pane that opts into scrollClearance="both").
+
+**Not when:**
+
+- 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 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`, `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, document-listeners.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signatures-v1.md#kerfjsuisurface-scaffold), [`@kerfjs/ui/wire-overlay-sheets`](../public-api-signatures-v1.md#kerfjsuiwire-overlay-sheets) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- small, medium, or large dialog
+- data-\* rootAttributes (a data-key) so sibling dialogs morph by identity
+- modal, side-sheet, fullscreen, or bottom-sheet dialog
+- alert dialog (alert): role="alertdialog" on the native dialog, described by its message through describedBy
+- bottom sheet attached to the bottom edge: square bottom corners, safe-area and virtual-keyboard clearance behind the panel, slide (or standard) enter and exit motion, and an optional resizable top grabber bounded by minHeight and maxHeight
+- typed modal preferred width, viewport gutter, and maximum height, including viewport cap
+- definite viewport-bounded modal height and a fill body layout for one child
+- fill-last body layout: fixed rows above one filling, scrolling last child
+- docked or floating footer with a typed footerOffset; the body reserves the measured footer height
+- floating footer over a filling child that opts into block-end scrollClearance: content scrolls beneath the footer through the published --kui-scroll-clearance-block-end
+- docked or floating header (headerPresentation) on the translucent chrome material; the body reserves the measured header height
+- floating header over a filling only child that opts into block-start scrollClearance: content scrolls beneath the title bar through the published --kui-scroll-clearance-block-start
+- floating header divider as scroll state: a hairline under the title bar only while the body or a filling child beneath it is scrolled away from its top
+- non-modal light-dismiss PopoverDialogSurface, overlay or embedded in flow, named by label or labelledBy and described by describedBy
+- none, compact, or comfortable body and footer inset
+- 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
+- accessible description by describedBy: the heading ToolbarText descriptionId or app-owned body summary copy
+- 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):
+
+- `preferredWidth`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `preferredWidth={remify(832)}`
+- `viewportGutter`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `viewportGutter={remify(8)}`
+- `footerOffset`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `footerOffset={remify(8)}`
+- `minHeight`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `minHeight={remify(200)}`
+- `maxHeight`: length grammar; raw values: forbid; shorthands `viewport`; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `maxHeight="viewport"`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md), [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md).
+
+## State and wiring
+
+**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.
+
+## Geometry
+
+Margin: parent · border: child · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- DialogSurface is a native \<dialog> opened modally (showModal): it is in the top layer, the rest of the page is inert, focus stays inside, and it returns to the opener on close. Focus starts on an autofocus element, otherwise on the panel.
+- Name it with label (also its title text) or labelledBy (the id of a heading, such as a ToolbarText). The close button is named Close (closeLabel) and Escape asks to close; the cancelable kui-request-close event reports source close-button, escape, or backdrop.
+- Name a PopoverDialogSurface with label or labelledBy. Describe either surface with describedBy (rendered as aria-describedby on the dialog root), usually the heading ToolbarText descriptionId or app-owned summary copy in the body; rootAttributes accepts only data-\* attributes, so it never sets aria-describedby.
+- A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
+- A resizable bottom sheet's grabber is a focusable horizontal separator ("Resize sheet") with aria-valuemin, aria-valuenow, and aria-valuemax in visible px; the arrow keys, Page Up/Down, Home, and End resize it, and its slide motion is skipped under prefers-reduced-motion.
+- Use popup surfaces only for real dropdown menus with named triggers.
+
+## 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-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`, `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`).
+
+Never put `kui-popup-surface` on an element you write; render `PopupSurface` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-layout-pill-radius`, `--kui-wa-container-inset`, `--kui-wa-surface-inset`, `--kui-chrome-material-raised`, `--kui-chrome-material-filter`, `--kui-scroll-clearance-block-start`, `--kui-scroll-clearance-block-end`, `--kui-safe-area-block-start`, `--kui-safe-area-block-end`. 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), [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 sits directly under the label, on its text column, like a Checkbox hint.
+
+## 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

@@ -0,0 +1,114 @@
+# TabBar
+
+<!-- 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:tab-bar` · Kerf UI · component · Navigation
+
+Controlled tab strips with typed presentation and allocation, a scroll-owning tab region, an optional adjacent trailing action, and a separately pinned far-edge end action.
+
+## When to use
+
+Controlled tab strips whose tabs shrink and scroll while fixed leading, trailing, and far-edge end actions remain visible.
+
+- Switch application tabpanels with optional overflow, closing, and reordering.
+
+**Not when:**
+
+- Do not use for a compact local toggle or a long value list.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+- [Select](./select.md) (nearest)
+- [Tab Group](./wa-tab-group.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/tab-bar` — exports `TabBar`, `wireTabBars`, `reorderTabs`.
+- CSS: the browser build of `@kerfjs/ui/tab-bar` pulls its CSS automatically; import `@kerfjs/ui/tab-bar.css` manually only without the `browser` export condition.
+- Wiring: `wireTabBars` from `@kerfjs/ui/wire-tab-bars` (required).
+- Wiring: `reorderTabs` from `@kerfjs/ui/wire-tab-bars` (optional).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/tab-bar`](../public-api-signatures-v1.md#kerfjsuitab-bar), [`@kerfjs/ui/wire-tab-bars`](../public-api-signatures-v1.md#kerfjsuiwire-tab-bars), [`@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):**
+
+- leading
+- trailing
+- overflow
+- reorderable
+- rail, segmented, and inspector presentation
+- intrinsic or fill allocation
+- separate or adjacent trailing action
+- far-edge end action
+- standalone Kerf Button or Web Awesome action in trailing or end
+- overflow dividers on each side with tabs scrolled out of view (wired by wireScrollDividers)
+
+## Composition
+
+- Parents: any.
+- Contexts: `tabpanel-navigation`.
+- Children: only `tab-bar-item` (required: `tab-bar-item`).
+- Built from: [TabBarItem](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./button.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 [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](./button.md), [Button](./wa-button.md); 0–1.
+- `end` — JSX prop `end`; accepts [ToolbarControlGroup](./toolbar-control-group.md), [Button](./button.md), [Button](./wa-button.md); 0–1.
+
+## State and wiring
+
+- selected-tab — controlled (required)
+
+**Wiring:** `wireTabBars`, `wireScrollDividers` is required.
+
+- Retain and invoke the disposer.
+- Apply onReorder to application-owned order.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `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.
+- `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: self (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- TabBar owns inline flex allocation: tabs shrink and scroll, an adjacent trailing action follows the tab strip, and the end action stays pinned at the far edge; leading, trailing, and end actions do not shrink.
+
+## Accessibility
+
+- Each tab controls a matching tabpanel.
+- Selection and focus behavior follow the configured activation mode.
+
+## 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-tab-bar`, `kui-tab-bar__leading`, `kui-tab-bar__tabs`, `kui-tab-bar__trailing`, `kui-tab-bar__end`.
+
+Never put `kui-tab-bar`, `kui-tab-bar__leading`, `kui-tab-bar__tabs`, `kui-tab-bar__trailing`, `kui-tab-bar__end` on an element you write; render `TabBar` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-tab-bar-background`, `--kui-tab-bar-border`, `--kui-tab-bar-divider-color`, `--kui-tab-bar-strip-background`, `--kui-tab-bar-strip-border-width`, `--kui-tab-bar-strip-flex`, `--kui-tab-bar-strip-gap`, `--kui-tab-bar-strip-margin-block`, `--kui-tab-bar-strip-min-height`, `--kui-tab-bar-strip-overflow-block`, `--kui-tab-bar-strip-padding`, `--kui-tab-bar-strip-radius`, `--kui-tab-bar-strip-scroll-padding-inline`, `--kui-tab-bar-trailing-flex`. 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`).
+
+## Diagnostics
+
+- `KUI-C104` (error) when wireTabBars is absent: TabBar requires wireTabBars for keyboard and reorder behavior.
+
+## Related
+
+- Components: [TabBarItem](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./button.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

@@ -0,0 +1,105 @@
+# TabNavigator
+
+<!-- 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:tab-navigator` · Kerf UI · component · Structure
+
+A controlled compact-device bottom tab navigator that keeps every destination scene mounted so its navigation and scroll state survive selection changes.
+
+## When to use
+
+Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.
+
+- A handset or portrait-tablet app has two to five co-equal top-level destinations.
+- Each destination must stay mounted so its NavStack and scroll position survive tab switches.
+
+**Not when:**
+
+- Do not use TabNavigator for document tabs or reorderable work items; use TabBar.
+- Do not retain the bottom bar on desktop when the same destinations should be promoted to a Workbench rail or sidebar.
+
+**Alternatives:**
+
+- [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
+
+- JavaScript: `@kerfjs/ui/tab-navigator` — exports `TabNavigatorTab`, `TabNavigatorProps`, `TabNavigator`.
+- CSS: the browser build of `@kerfjs/ui/tab-navigator` pulls its CSS automatically; import `@kerfjs/ui/tab-navigator.css` manually only without the `browser` export condition.
+- Wiring: `wireTabNavigator` from `@kerfjs/ui/wire-tab-navigator` (required).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signatures-v1.md#kerfjsuitab-navigator), [`@kerfjs/ui/wire-tab-navigator`](../public-api-signatures-v1.md#kerfjsuiwire-tab-navigator), [`@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):**
+
+- text-only tabs
+- icon and text tabs
+- badged tabs (count or text-free dot)
+- one NavStack per tab
+- bar divider only while the active scene continues below it (wired by wireScrollDividers)
+- permanent or no bar divider (chromeDividers always or none)
+- sunken active-scene separator (separator auto or hidden)
+- translucent tab bar laid over the active scene (barPresentation overlay, measured by wireTabNavigator)
+- app-chosen navigator or per-scene background color (background, tab.background); the overlay bar keeps the chrome material
+- scoped tint (tint)
+- clear (transparent) bars with an optional scroll-edge material (barPresentation: clear, scrollEdge: material)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Badge](./badge.md).
+
+## State and wiring
+
+**The app owns:** controlled active tab id; tab labels, icons, and content; tab badge counts or dots and their localized badgeLabel phrases; routing and persistence; responsive replacement on larger device classes; whether the bar divider follows the scroll, always shows, or never shows (chromeDividers); whether the bar's top separator follows a sunken active surface or stays hidden (separator); optional active-scene focus (tabIndex) and persistent outline (outlined); an optional app-chosen color for the navigator and its docked bar (background) and per scene (tab.background), each a typed CssColor that replaces the default or sunken fill; an optional scoped tint for the navigator (tint) or one scene (tab.tint): tint: { color, scheme } re-derives surface and text tokens from an app color with text kept at AA.
+
+**Wiring:** `wireTabNavigator`, `wireScrollDividers` is required.
+
+- Use wireTabNavigator as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-scroll-overflow` on `the active kui-tab-scaffold__scene, or what scrolls inside it (a sole NavStack's active view or a sole Pane's content)` (`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-tab-scaffold__bar` (`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: conditional · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.
+- The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it.
+- barPresentation=overlay: once wireTabNavigator has measured the live bar (data-bar-overlay=measured), the bar is absolutely positioned over the scenes on --kui-chrome-material and the scenes route its border-box height (bottom safe area included) as the block-end --kui-edge-inset-\* context, so a plain scene pads and scroll-pads by it and a sole Pane or NavStack clears it; unwired it stays docked.
+
+## Accessibility
+
+- Give the tablist an accessible label and keep exactly the active tab in the sequential focus order.
+- Wire selection through the controlled active id while leaving inactive scenes mounted and hidden.
+- A focusable scene is a tabpanel named by its tab label; optional scene tabIndex applies only while active.
+- A tab badge is aria-hidden; supply badgeLabel so the tab's accessible name becomes "\<label>, \<badgeLabel>" (it defaults to the badge text). The dot form, badge: true, has no text, so its badgeLabel is required.
+- Over the overlay bar's translucent material, unselected labels lift halfway toward --kui-color-text and the selected label mixes 40% of it into the brand color, so both keep 4.5:1 over worst-case content; the material turns opaque under reduced transparency or increased contrast and paints Canvas with a CanvasText edge in forced colors.
+- A background color is app-chosen: Keep text at WCAG AA over the color: a dark background needs dark-tone content or a scoped tint; forced colors paint Canvas instead.
+- Clear bars have no material of their own: keep their controls in glass ToolbarControlGroups; they turn opaque under reduced transparency or increased contrast and paint Canvas in forced colors.
+
+## 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-tab-scaffold`, `kui-tab-scaffold__scenes`, `kui-tab-scaffold__scene`, `kui-tab-scaffold__bar`, `kui-tab-scaffold__tab`, `kui-tab-scaffold__tab-icon`, `kui-tab-scaffold__tab-badge`, `kui-tab-scaffold__tab-label`.
+
+Never put `kui-tab-scaffold`, `kui-tab-scaffold__scenes`, `kui-tab-scaffold__scene`, `kui-tab-scaffold__bar`, `kui-tab-scaffold__tab`, `kui-tab-scaffold__tab-icon`, `kui-tab-scaffold__tab-badge`, `kui-tab-scaffold__tab-label` on an element you write; render `TabNavigator` 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: [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

@@ -0,0 +1,95 @@
+# 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`. -->
+
+`@kerfjs/ui:tabs` · Kerf UI · component · Navigation
+
+Roving-tabindex-ready tabs with typed compact, segmented, icon-only, drop-target, pinned, and name-overflow presentations.
+
+## When to use
+
+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.
+
+- Render one controlled application tab inside TabBar.
+
+**Not when:**
+
+- Do not render alone or use for a compact settings choice.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+
+## Imports
+
+- 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/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):**
+
+- selected
+- closable
+- draggable
+- leading
+- trailing
+- custom close icon
+- root metadata
+- compact size
+- segmented presentation
+- icon-only accessible presentation
+- label maximum width and ellipsis or visible name overflow
+- drop-target highlight
+- pinned leading position within a scrolling tablist
+- attention name color
+
+## Composition
+
+- Parents: only inside [TabBar](./tab-bar.md).
+- Contexts: `tabpanel-navigation`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `leading-decoration` — JSX prop `leading`; accepts `dormant-decoration`; 0–1.
+- `trailing-decoration` — JSX prop `trailing`; accepts `dormant-decoration`; 0–1.
+- `close-icon` — JSX prop `closeIcon`; accepts `dormant-decoration`; 0–1.
+
+## State and wiring
+
+**The app owns:** tab identity; selection; drop-target state; close policy; content; application data attribute values; outer placement.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Compose in a tablist and pair with an application-owned tabpanel.
+- Keep closeIcon decorative and free of interactive descendants; the owning close button supplies its accessible name and interaction.
+- Use rootAttributes only for application data-\* metadata; component-owned identity, state, action, and role semantics are protected at runtime.
+
+## 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-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-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-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`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
+- UX catalog route: `?component=tabs`.