@kerfjs/ui 5.0.0-beta.56 → 5.0.0-beta.58

package/ai/components/state-banner.md

@@ -0,0 +1,92 @@
+# StateBanner
+
+<!-- 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:state-banner` · Kerf UI · component · Feedback
+
+Polite status and assertive alert feedback with semantic tones, plus non-status pop emphasis for featured or novel content.
+
+## When to use
+
+Present persistent inline feedback or attractive non-status emphasis with a named semantic tone.
+
+- Place persistent inline semantic status beside affected work.
+
+**Not when:**
+
+- Do not use for an absent-content screen or transient confirmation.
+- Do not use pop as a substitute for success, warning, or danger.
+
+**Alternatives:**
+
+- [EmptyState](./empty-state.md) (nearest)
+- [Callout](./wa-callout.md) (prefer-over)
+- [Toast](./wa-toast.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/state-banner` — exports `StateBanner`.
+- CSS: the browser build of `@kerfjs/ui/state-banner` pulls its CSS automatically; import `@kerfjs/ui/state-banner.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/state-banner`](../public-api-signatures-v1.md#kerfjsuistate-banner) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral
+- info
+- pop
+- success
+- warning
+- danger
+- status
+- alert
+- badge
+- placeholder (loading)
+
+## Composition
+
+- Parents: any.
+- Contexts: `persistent-status`, `recoverable-error`.
+- Children: unrestricted.
+- Built from: [Badge](./badge.md), [LucideIcon](./lucide-icon.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `icon` — JSX prop `icon`; accepts `dormant-decoration`; 0–1.
+- `action` — JSX prop `action`; accepts `control`; 0–1.
+
+## State and wiring
+
+**The app owns:** badge content; state mapping; message lifetime; retry behavior; copy.
+
+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.
+
+## Accessibility
+
+- Use alert urgency only for an attention-requiring failure.
+- Keep optional badge content terse and do not rely on its tone alone for meaning.
+
+## 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-state-banner`, `kui-state-banner__action`, `kui-state-banner__copy`, `kui-state-banner__detail`, `kui-state-banner__icon`.
+
+Never put `kui-state-banner`, `kui-state-banner__action`, `kui-state-banner__copy`, `kui-state-banner__detail`, `kui-state-banner__icon` on an element you write; render `StateBanner` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-border-quiet`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-on-fill`, `--kui-color-pop-border-normal`, `--kui-color-pop-fill-quiet`, `--kui-color-pop-on-fill`, `--kui-color-danger-border-quiet`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-on-fill`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-success-border-normal`, `--kui-color-success-fill-quiet`, `--kui-color-success-on-fill`, `--kui-color-surface`, `--kui-color-text-link`, `--kui-color-warning-border-normal`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-on-fill`, `--kui-font-2xs`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-state-banner-action-background`, `--kui-state-banner-action-hover-background`, `--kui-state-banner-background`, `--kui-state-banner-border`, `--kui-state-banner-danger-background`, `--kui-state-banner-danger-border`, `--kui-state-banner-danger-foreground`, `--kui-state-banner-detail`, `--kui-state-banner-foreground`, `--kui-state-banner-info-background`, `--kui-state-banner-info-border`, `--kui-state-banner-info-foreground`, `--kui-state-banner-pop-background`, `--kui-state-banner-pop-border`, `--kui-state-banner-pop-foreground`, `--kui-state-banner-neutral-background`, `--kui-state-banner-neutral-border`, `--kui-state-banner-neutral-foreground`, `--kui-state-banner-success-background`, `--kui-state-banner-success-border`, `--kui-state-banner-success-foreground`, `--kui-state-banner-warning-background`, `--kui-state-banner-warning-border`, `--kui-state-banner-warning-foreground`. 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: [Badge](./badge.md), [LucideIcon](./lucide-icon.md), [EmptyState](./empty-state.md), [Callout](./wa-callout.md), [Toast](./wa-toast.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#ambiguous-choices`](../../docs/component-selection.md#ambiguous-choices).
+- UX catalog route: `?component=state-banner`.

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`.
+- 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.
+
+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,78 @@
+# 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
+
+Typed Web Awesome dialog and popup surface sizing, presentation, and 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 dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText.
+
+**Not when:**
+
+- Do not use it as a generic layout wrapper or to replace application-owned modal state and focus lifecycle.
+- Do not stack a dialog body inset around children that already own List or content-item geometry; use bodyInset none.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/surface-scaffold` — exports `DialogSurface`, `PopupSurface`.
+- 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.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signatures-v1.md#kerfjsuisurface-scaffold) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- small, medium, or large dialog
+- modal, side-sheet, or fullscreen dialog
+- none, compact, or comfortable body and footer inset
+- standard, compact, or zero-inset popup menu
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Dialog](./wa-dialog.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.
+
+No wiring helper.
+
+## 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
+
+- Supply the wrapped wa-dialog label and retain Web Awesome's native modal and focus behavior.
+- 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-popup-surface`.
+
+Never put `kui-dialog-surface` on an element you write; render `DialogSurface` instead (`KUI-L103`).
+
+Never put `kui-popup-surface` on an element you write; render `PopupSurface` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-radius-l`, `--kui-wa-container-inset`, `--kui-wa-surface-inset`. 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: [Dialog](./wa-dialog.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/tab-bar.md

@@ -0,0 +1,112 @@
+# 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
+- overflow dividers on each side with tabs scrolled out of view (wired by wireScrollDividers)
+
+## Composition
+
+- Parents: any.
+- Contexts: `tabpanel-navigation`.
+- Children: only `app-tab` (required: `app-tab`).
+- Built from: [AppTab](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.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.
+- `leading` — JSX prop `leading`; accepts [ToolbarControlGroup](./toolbar-control-group.md); 0–1.
+- `trailing` — JSX prop `trailing`; accepts [ToolbarControlGroup](./toolbar-control-group.md); 0–1.
+- `end` — JSX prop `end`; accepts [ToolbarControlGroup](./toolbar-control-group.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 `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-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.
+
+## 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`. 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: [AppTab](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.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-scaffold.md

@@ -0,0 +1,94 @@
+# TabScaffold
+
+<!-- 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-scaffold` · Kerf UI · component · Structure
+
+A controlled compact-device bottom tab scaffold that keeps every tab 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 TabScaffold 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:**
+
+- [AppTab](./tabs.md) (semantic-alternative) — Use TabBar and AppTab 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-scaffold` — exports `TabScaffoldTab`, `TabScaffoldProps`, `TabScaffold`.
+- CSS: the browser build of `@kerfjs/ui/tab-scaffold` pulls its CSS automatically; import `@kerfjs/ui/tab-scaffold.css` manually only without the `browser` export condition.
+- Wiring: `wireTabScaffold` from `@kerfjs/ui/wire-tab-scaffold` (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-scaffold`](../public-api-signatures-v1.md#kerfjsuitab-scaffold), [`@kerfjs/ui/wire-tab-scaffold`](../public-api-signatures-v1.md#kerfjsuiwire-tab-scaffold), [`@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)
+
+## 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).
+
+**Wiring:** `wireTabScaffold`, `wireScrollDividers` is required.
+
+- Use wireTabScaffold 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.
+
+## 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 scaffold owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.
+- The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border.
+
+## 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 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.
+
+## 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 `TabScaffold` 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), [AppTab](./tabs.md), [Workbench](./workbench.md).
+- Docs: [`docs/tab-scaffold.md`](../../docs/tab-scaffold.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
+- UX catalog route: `?component=tab-scaffold`.

package/ai/components/tabs.md

@@ -0,0 +1,90 @@
+# AppTab
+
+<!-- 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
+
+## When to use
+
+Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.
+
+- 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/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.
+- 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.
+
+**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 truncation
+
+## 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; 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-app-tab`, `kui-app-tab__close`, `kui-app-tab__close-icon`, `kui-app-tab__name`, `kui-app-tab__select`, `kui-app-tab__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`).
+
+Public tokens it reads: `--kui-app-tab-color`, `--kui-app-tab-drop-indicator`, `--kui-app-tab-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.
+
+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`.

package/ai/components/text.md

@@ -0,0 +1,82 @@
+# Text
+
+<!-- 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` · Kerf UI · component · Structure
+
+Semantic native paragraph text by default, with heading and inline-span variants plus composable semantic presentation roles.
+
+## When to use
+
+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 size, or monospace font.
+
+- Render ordinary application headings or paragraphs with native document semantics, or inline secondary text inside rows, labels, and table cells.
+
+**Not when:**
+
+- Do not use Text for toolbar identity or title content; use ToolbarText inside a Toolbar zone.
+- Do not choose a heading variant for visual size alone; preserve the document heading hierarchy.
+
+**Alternatives:**
+
+- [ToolbarText](./toolbar-text.md) (toolbar-specific)
+- [ListInsetText](./list-inset-text.md) (list-geometry-specific)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/text` — exports `Text`.
+- CSS: the browser build of `@kerfjs/ui/text` pulls its CSS automatically; import `@kerfjs/ui/text.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/text`](../public-api-signatures-v1.md#kerfjsuitext) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- p, h1 through h6, or inline span semantic variant
+- default, quiet, or danger tone
+- default or compact size
+- default or monospace font
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** semantic variant; tone; size; font; copy; document heading hierarchy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; span has no margin, border, or padding.
+
+## Accessibility
+
+- Text renders a native paragraph by default; choose an h1 through h6 variant by document outline rather than appearance, or span for inline secondary text.
+- Ordinary global, data, and ARIA attributes pass through to the native element.
+- Choose tone, size, and font independently of the heading level so appearance does not distort the document outline.
+
+## 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`.
+
+Never put `kui-text` on an element you write; render `Text` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-danger-on-quiet`, `--kui-color-text-quiet`, `--kui-font-mono`, `--kui-font-xs`, `--kui-layout-item-padding`. 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: [ToolbarText](./toolbar-text.md), [ListInsetText](./list-inset-text.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`.