@kerfjs/ui 5.0.0-beta.8 → 5.0.0-beta.80

package/ai/components/badge.md

@@ -0,0 +1,72 @@
+# Badge
+
+<!-- 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:badge` · Kerf UI · component · Foundation
+
+Self-styled, non-interactive status, count, and category metadata configured through semantic tone, appearance, shape, and size props.
+
+## When to use
+
+Present compact metadata without application-authored badge CSS or consumer styling of component internals.
+
+- Show a short status, count, category, or metadata label whose presentation should be configured rather than restyled.
+
+**Not when:**
+
+- Do not use Badge as a button, link, or removable chip; choose an interactive control with the correct native semantics.
+- Do not rely on tone alone to communicate meaning.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/badge` — exports `Badge`.
+- CSS: the browser build of `@kerfjs/ui/badge` pulls its CSS automatically; import `@kerfjs/ui/badge.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/badge`](../public-api-signatures-v1.md#kerfjsuibadge) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, info, pop, success, warning, or danger tone
+- quiet, solid, or outline appearance
+- pill or rounded shape
+- compact or default size, or a text-free dot (size: 'dot')
+- labeled or decorative duplicate
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** metadata text; semantic tone mapping; accessible label for abbreviated content.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Badge is non-interactive. Supply label when visible content is abbreviated, and ariaHidden when it repeats an accessible name owned by the surrounding component. A text-free dot must take either label (exposed as an image) or ariaHidden, which the types enforce.
+- Keep meaningful text visible because tone is supplementary.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-badge`.
+
+Never put `kui-badge` on an element you write; render `Badge` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=badge`.

package/ai/components/chip.md

@@ -0,0 +1,72 @@
+# Chip
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:chip` · Kerf UI · component · Foundation
+
+A short tag with semantic tone and an optional accessible remove button, including compact and disabled variants.
+
+## When to use
+
+Render removable tags without application rules on Web Awesome internals.
+
+- Show a short tag that the application can remove through a delegated action, including a compact or disabled tag.
+
+**Not when:**
+
+- Use Badge for non-interactive status and count metadata.
+- Do not use the remove button without a specific accessible name.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/chip` — exports `Chip`.
+- CSS: the browser build of `@kerfjs/ui/chip` pulls its CSS automatically; import `@kerfjs/ui/chip.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#kerfjsuichip) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, info, pop, success, warning, or danger tone
+- quiet, solid, or outline appearance
+- pill or rounded shape
+- compact or default size
+- removable or plain, enabled or disabled
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** tag text and identity; remove action and list update; disabled policy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.
+- Keep meaningful tag text visible because tone is supplementary.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-chip`.
+
+Never put `kui-chip` on an element you write; render `Chip` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=chip`.

package/ai/components/collapsible-panel.md

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

package/ai/components/content-item.md

@@ -0,0 +1,96 @@
+# ContentItem
+
+<!-- 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:content-item` · Kerf UI · component · Structure
+
+One self-contained content child with shared geometry plus typed transparent, surface, or semantic appearance, frame, and shape choices.
+
+## When to use
+
+Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.
+
+- An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.
+- A content item marks a real distinction and must read as visibly bounded: pass frame="framed" (the border is always reserved, so geometry does not change).
+- A content item needs the base surface or a coordinated semantic status treatment: pass appearance="surface" or a semantic appearance such as success or danger.
+- A content item should follow a pill control's 22px radius: pass shape="pill".
+- A selectable rich card needs nested controls: use selectionMode="multiple" inside a labeled List multi-select grid.
+
+**Not when:**
+
+- Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.
+- Do not frame an item only to make it look contained; hierarchy comes from alignment, spacing, and type first.
+- Do not use its surface appearance for a lowered inset panel around a stack; use SunkenPanel for that structure.
+- Do not use it for bare text alone; use ListInsetText, which adds the same inset without claiming a surface.
+
+**Alternatives:**
+
+- [ListInsetText](./list-inset-text.md) (nearest) — Use ListInsetText when bare text only needs to align with neighboring content items.
+- [SunkenPanel](./sunken-panel.md) (nearest) — Use SunkenPanel for a lowered, filled surface around a vertical stack.
+- [Application layout](./layout.md) (composes-with) — Place ContentItem children in a Pane or .kui-content stack, which owns the 24px major rhythm.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/content-item` — exports `ContentItem`.
+- CSS: the browser build of `@kerfjs/ui/content-item` pulls its CSS automatically; import `@kerfjs/ui/content-item.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures-v1.md#kerfjsuicontent-item) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- unframed rounded item
+- framed rounded item
+- pill item
+- framed pill item
+- base surface item
+- neutral, info, pop, success, warning, or danger semantic item
+- named focus-target region
+- multi-select rich grid row
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; whether the item needs a surface or semantic appearance; corner shape; region semantics and accessible name; whether the item is a programmatic focus target; optional static-item Tab stop and persistent focus outline; the selection set and Shift/Cmd extension for multi-select rich cards.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The 1px border is always reserved; transparent items paint it only when frame="framed", while surface and semantic appearances coordinate its color with their background and foreground.
+
+## Accessibility
+
+- An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role="region").
+- focusTarget makes the item a programmatic focus target (tabindex="-1", never a tab stop), such as a NavStack view's data-nav-focus target.
+- The frame is decorative and never the only signal of state.
+- selectionMode="multiple" renders a focusable row with aria-selected and a gridcell for nested controls; place it in a labeled List selectionMode="multiple" grid. wireContentItems moves focus among rows with Up/Down and Home/End while nested controls retain those keys. Guard the app's delegated card action with isContentItemActivation so a nested control does not select the row.
+
+## 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-content-item`, `kui-content-item--pill`, `kui-content-item--framed`.
+
+Classes an application may place on its own elements: `kui-content-item`, `kui-content-item--pill`, `kui-content-item--framed`.
+
+A plain `<div>` carrying them is exactly what `ContentItem` renders: render `ContentItem` instead (`KUI-L103`), and place the classes only on another carrier element.
+
+Public tokens it reads: `--kui-content-item-border`, `--kui-content-item-radius`, `--kui-content-item-background`. 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: [ListInsetText](./list-inset-text.md), [SunkenPanel](./sunken-panel.md), [Application layout](./layout.md).
+- Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/layout.md#content-items`](../../docs/layout.md#content-items).
+- UX catalog route: `?component=content-item`.

package/ai/components/disclosure-arrow.md

@@ -0,0 +1,77 @@
+# DisclosureArrow
+
+<!-- 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:disclosure-arrow` · Kerf UI · component · Foundation
+
+Root-scaled 18px animated open and closed disclosure indicator with configurable directions, shortest-path rotation, and right-oriented replacement icon content.
+
+## When to use
+
+Indicate whether a disclosure control is open with an overridable 18px root-scaled visual and shortest-path rotation behavior.
+
+- Add a shortest-path rotating indicator to a control that owns open and closed state; author replacement icon content facing right before direction transforms are applied.
+
+**Not when:**
+
+- Do not use the arrow as the interactive control or accessible name by itself.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/disclosure-arrow` — exports `DisclosureArrow`.
+- CSS: the browser build of `@kerfjs/ui/disclosure-arrow` pulls its CSS automatically; import `@kerfjs/ui/disclosure-arrow.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/disclosure-arrow`](../public-api-signatures-v1.md#kerfjsuidisclosure-arrow) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- open
+- closed
+- custom directions
+- replacement icon
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `size`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `size={remify(24)}`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** open state; interaction; accessible control label.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The arrow is decorative; expose expanded state through aria-expanded on its owning control and keep that control's accessible name stable.
+
+## 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-disclosure-arrow`.
+
+Never put `kui-disclosure-arrow` on an element you write; render `DisclosureArrow` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-disclosure-arrow-duration`, `--kui-disclosure-arrow-size`. 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).
+- 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=disclosure-arrow`.

package/ai/components/document-baseline.md

@@ -0,0 +1,75 @@
+# Document baseline
+
+<!-- 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:document-baseline` · Kerf UI · CSS composition · Foundation
+
+Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, link color, and the html → body → .kui-app-root full-height chain.
+
+## When to use
+
+Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.
+
+- An application wants Kerf UI to own document-level box sizing, body typography, native table-cell and form-control font metrics, surface, and link color.
+- A full-height shell (Workbench, SplitView, NavStack, or TabNavigator) mounts into one direct container: put .kui-app-root on that container.
+
+**Not when:**
+
+- Do not put .kui-app-root on several sibling containers; each requests the full available document height.
+- Do not import it where the host page already owns document-level defaults it would override.
+
+**Alternatives:**
+
+- [Foundation tokens](./foundation.md) (composes-with) — Import the foundation tokens the baseline reads; the baseline itself adds only global document selectors.
+
+## Imports
+
+- CSS: import `@kerfjs/ui/document.css` once.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- document-flow page (no .kui-app-root)
+- full-height application root
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the one direct mount container; application overrides loaded after the baseline.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The body margin is removed; .kui-app-root only sets height: 100% and owns no inset.
+
+## Accessibility
+
+- Links keep the semantic link color at zero specificity so application focus and link styles still apply.
+
+## 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-root`.
+
+Classes an application may place on its own elements: `kui-app-root`.
+
+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: [Foundation tokens](./foundation.md).
+- Docs: [`docs/document-baseline.md`](../../docs/document-baseline.md).
+- UX catalog route: `?component=document-baseline`.

package/ai/components/empty-state.md

@@ -0,0 +1,80 @@
+# EmptyState
+
+<!-- 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:empty-state` · Kerf UI · component · Feedback
+
+## When to use
+
+Actionable empty and busy content states.
+
+- Explain absent or busy content and offer an optional recovery action.
+
+**Not when:**
+
+- Do not use for an inline update or transient success.
+
+**Alternatives:**
+
+- [StateBanner](./state-banner.md) (nearest)
+- [Toast](./wa-toast.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/empty-state` — exports `EmptyState`.
+- CSS: the browser build of `@kerfjs/ui/empty-state` pulls its CSS automatically; import `@kerfjs/ui/empty-state.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/empty-state`](../public-api-signatures-v1.md#kerfjsuiempty-state) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- actionable
+- busy
+- illustrated
+
+## Composition
+
+- Parents: any.
+- Contexts: `empty-content`, `busy-content`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md), [LoadingSpinner](./loading-spinner.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:** empty/busy policy; recovery action; 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
+
+- Busy state uses aria-busy; the illustration never supplies the only label.
+
+## 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-empty-state`, `kui-empty-state__action`, `kui-empty-state__icon`.
+
+Never put `kui-empty-state`, `kui-empty-state__action`, `kui-empty-state__icon` on an element you write; render `EmptyState` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-on-quiet`, `--kui-color-text`, `--kui-empty-state-foreground`, `--kui-empty-state-title`, `--kui-font-l`, `--kui-font-s`, `--kui-space-xl`, `--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), [LoadingSpinner](./loading-spinner.md), [StateBanner](./state-banner.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=empty-state`.

package/ai/components/feedback.md

@@ -0,0 +1,71 @@
+# Feedback
+
+<!-- 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:feedback` · Kerf UI · CSS composition · Feedback
+
+## When to use
+
+Banners, empty states, and labeled progress.
+
+- Compose persistent status, empty/busy content, and compact loading feedback.
+
+**Not when:**
+
+- Do not collapse different message lifetimes or urgency into one visual treatment.
+
+**Alternatives:**
+
+- [StateBanner](./state-banner.md) (nearest)
+- [EmptyState](./empty-state.md) (nearest)
+- [Callout](./wa-callout.md) (prefer-over)
+- [Toast](./wa-toast.md) (prefer-over)
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- banner
+- empty
+- busy
+- spinner
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md).
+
+## State and wiring
+
+**The app owns:** state mapping; message lifetime; recovery policy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: child · border: child · padding: child (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Choose polite status versus assertive alert deliberately.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+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), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.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=feedback`.