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

package/ai/components/radio-group.md

@@ -0,0 +1,89 @@
+# RadioGroup
+
+<!-- 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:radio-group` · Kerf UI · component · Controls
+
+A native fieldset of radios, each drawn as a Kerf circle beside its label, with the group label above, per-choice hints, and hint and error text below, stacked or wrapping.
+
+## When to use
+
+Choose exactly one of a few options that should stay visible with room for a label and hint each, with native keyboard behavior and form participation.
+
+- A form asks for one of two to about six options that people should compare at a glance, each with a readable label and an optional hint.
+
+**Not when:**
+
+- Do not use for many options or a compact toolbar value; use Select.
+- Do not use to switch a view; use SegmentedControl.
+- Do not use for chip-styled or color choices; use ChoiceChips.
+
+**Alternatives:**
+
+- [Radio Group](./wa-radio-group.md) (prefer-over)
+- [Radio](./wa-radio.md) (prefer-over)
+- [Select](./select.md) (nearest) — Use Select for a long list.
+- [ChoiceChips](./choice-chips.md) (nearest) — Use ChoiceChips for wrapping pill choices.
+- [CheckboxGroup](./checkbox-group.md) (nearest) — Use CheckboxGroup when people may choose several.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/radio-group` — exports `RadioGroup`.
+- CSS: the browser build of `@kerfjs/ui/radio-group` pulls its CSS automatically; import `@kerfjs/ui/radio-group.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/radio-group`](../public-api-signatures-v1.md#kerfjsuiradio-group) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- vertical or horizontal
+- per-choice hint
+- disabled choice
+- whole group disabled
+- hint
+- error
+- required
+- default or compact size
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** value; choices and their copy; validation and error copy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The label and hint sit on the text column (1px + 8px); each choice's 20px circle (18px compact) sits on the group's inline-start edge, where a Checkbox draws its box, 8px (7px) before its label; choices stack 8px apart (--kui-space-xs), the same 28px pitch as Checkboxes in a List gap="xs", and a choice hint aligns with its label text.
+
+## Accessibility
+
+- A native \<fieldset role="radiogroup"> named by its legend (label) or ariaLabel; each choice is a native radio inside its \<label>, invisibly over the drawn circle. The browser owns the interaction: one Tab stop, arrow keys move and select, and the checked radio submits its value under name.
+- The group's hint and error form its aria-description; an error sets aria-invalid on the group and the danger border on each circle. required sets each radio's native required and aria-required on the group. A choice's hint is that radio's aria-description.
+
+## 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-radio-group`, `kui-radio-group__label`, `kui-radio-group__choices`, `kui-radio-group__choice`, `kui-radio-group__row`, `kui-radio-group__control`, `kui-radio-group__input`, `kui-radio-group__circle`, `kui-radio-group__choice-label`, `kui-radio-group__choice-hint`, `kui-radio-group__hint`, `kui-radio-group__error`.
+
+Never put `kui-radio-group`, `kui-radio-group__label`, `kui-radio-group__choices`, `kui-radio-group__choice`, `kui-radio-group__row`, `kui-radio-group__control`, `kui-radio-group__input`, `kui-radio-group__circle`, `kui-radio-group__choice-label`, `kui-radio-group__choice-hint`, `kui-radio-group__hint`, `kui-radio-group__error` on an element you write; render `RadioGroup` 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-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-color-neutral-on-quiet`, `--kui-layout-item-padding`, `--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: [Radio Group](./wa-radio-group.md), [Radio](./wa-radio.md), [Select](./select.md), [ChoiceChips](./choice-chips.md), [CheckboxGroup](./checkbox-group.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=radio-group`.

package/ai/components/recipe-app-shell.md

@@ -0,0 +1,57 @@
+# Desktop Application Shell
+
+<!-- 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:recipe-app-shell` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+App bar above a Workbench with resizable navigation and inspector rails, relocated rail toggles, narrow-container overlays, and explicit pane scroll owners.
+
+- A desktop workspace needs persistent chrome and user-adjustable navigation or inspector panes.
+
+**Not when:**
+
+- Use ordinary CSS grid when panes are static or the product does not need a user-operable separator.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Workbench](./workbench.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md).
+
+## State and wiring
+
+**The app owns:** routing; pane visibility; pane sizes and persistence; workspace data.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Each pane has one scroll owner and each resize handle keeps its separator keyboard contract.
+
+## 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: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Workbench](./workbench.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md).
+- Docs: [`docs/recipes.md#desktop-application-shell`](../../docs/recipes.md#desktop-application-shell).
+- UX catalog route: `?component=recipe-app-shell`.

package/ai/components/recipe-collapsible-sidebar.md

@@ -0,0 +1,57 @@
+# Collapsible Sidebar
+
+<!-- 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:recipe-collapsible-sidebar` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+A mini app frame whose left navigation rail and bottom activity drawer are standalone CollapsiblePanels driven by wireSidebar: per-side collapse/expand toggles, focus move-in and restore, a dismissable compact overlay, and per-panel persistence.
+
+- A rail or drawer must collapse and expand outside a full Workbench shell, keeping the app's collapsed signals, sizes, and content while the wire owns toggle, focus, the compact overlay, and persistence.
+
+**Not when:**
+
+- Use the Workbench layout when the whole screen is a three-pane shell; use an ordinary always-visible sidebar when it never collapses.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [CollapsiblePanel](./collapsible-panel.md), [Pane](./pane.md), [Row](./row.md), [List](./list.md), [Grid](./grid.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
+
+## State and wiring
+
+**The app owns:** each panel's collapsed signal; panel sizes; routing and selection; content.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Each panel is a labeled aside that is aria-hidden while collapsed; toggles carry aria-expanded and the standard per-side glyph; while compact an open panel is an overlay with a backdrop, Escape and backdrop-click dismiss, and a trapped Tab ring.
+
+## 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: [CollapsiblePanel](./collapsible-panel.md), [Pane](./pane.md), [Row](./row.md), [List](./list.md), [Grid](./grid.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
+- Docs: [`docs/recipes.md#collapsible-sidebar`](../../docs/recipes.md#collapsible-sidebar).
+- UX catalog route: `?component=recipe-collapsible-sidebar`.

package/ai/components/recipe-compact-toolbar.md

@@ -0,0 +1,57 @@
+# Compact Toolbar Choices and Actions
+
+<!-- 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:recipe-compact-toolbar` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+A compact toolbar that distinguishes grouped commands, a visible exclusive choice, a longer Select, and one ordinary action.
+
+- A dense workspace toolbar mixes a few distinct control semantics.
+
+**Not when:**
+
+- Do not group unrelated actions or use buttons to imitate selection controls.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css, individual-custom-element-registration.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [LucideIcon](./lucide-icon.md), [Grid](./grid.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md).
+
+## State and wiring
+
+**The app owns:** controlled values; actions; persistence; responsive priority.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Each control retains its own native name, pressed/value state, and keyboard contract.
+
+## 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: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [LucideIcon](./lucide-icon.md), [Grid](./grid.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md).
+- Docs: [`docs/recipes.md#compact-toolbar-choices-and-actions`](../../docs/recipes.md#compact-toolbar-choices-and-actions).
+- UX catalog route: `?component=recipe-compact-toolbar`.

package/ai/components/recipe-composer-form.md

@@ -0,0 +1,57 @@
+# Composer Form
+
+<!-- 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:recipe-composer-form` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+One visible publishing-form surface with Toolbar heading hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.
+
+- A short form needs one coherent surface, consistent field/action rhythm, and persistent validation feedback.
+
+**Not when:**
+
+- Do not turn each form section into another visible card or use the recipe as a generic form engine or transport abstraction.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css, individual-custom-element-registration.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [Row](./row.md), [Select](./select.md), [StateBanner](./state-banner.md), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Button](./wa-button.md), [Application Layout](./layout.md).
+
+## State and wiring
+
+**The app owns:** validation rules; draft persistence; permissions; transport.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The form references its ToolbarText title and supporting-summary ids; production fields own labels and help; invalid submission creates an assertive persistent StateBanner while successful submission creates a polite persistent banner.
+
+## 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: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [Row](./row.md), [Select](./select.md), [StateBanner](./state-banner.md), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Button](./wa-button.md), [Application Layout](./layout.md).
+- Docs: [`docs/recipes.md#composer-form`](../../docs/recipes.md#composer-form).
+- UX catalog route: `?component=recipe-composer-form`.

package/ai/components/recipe-list-detail-dialog.md

@@ -0,0 +1,57 @@
+# List-detail dialog
+
+<!-- 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:recipe-list-detail-dialog` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+Production ListDetailDialog: a full-height list column with its own title beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.
+
+- A focused task compares several records without leaving the current workspace.
+
+**Not when:**
+
+- Use a page when the task needs a durable route or substantially more working space.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [ListDetailDialog](./list-detail-dialog.md), [Row](./row.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Button](./button.md).
+
+## State and wiring
+
+**The app owns:** open state; selected record; pushed compact detail; dismiss policy; record actions.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- ListDetailDialog's native modal dialog owns focus, Escape, and inertness, and returns focus to the opener on close; the close control sits in the detail column (or each compact view), and the compact NavStack back control returns to the list.
+
+## 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: [ListDetailDialog](./list-detail-dialog.md), [Row](./row.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Button](./button.md).
+- Docs: [`docs/recipes.md#list-detail-dialog`](../../docs/recipes.md#list-detail-dialog).
+- UX catalog route: `?component=recipe-list-detail-dialog`.

package/ai/components/recipe-list-workspace-states.md

@@ -0,0 +1,57 @@
+# List Workspace States
+
+<!-- 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:recipe-list-workspace-states` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.
+
+- A list surface must communicate initial load, absence, background refresh, failure, and recovery.
+
+**Not when:**
+
+- Do not replace domain rows with a generic component or use transient toasts as the only error record.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListItem](./list-item.md), [Row](./row.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md), [Application Layout](./layout.md).
+
+## State and wiring
+
+**The app owns:** fetching; cache age; retry policy; domain rows.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Busy, polite, and assertive states use the appropriate production feedback semantics.
+
+## 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: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListItem](./list-item.md), [Row](./row.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md), [Application Layout](./layout.md).
+- Docs: [`docs/recipes.md#list-workspace-states`](../../docs/recipes.md#list-workspace-states).
+- UX catalog route: `?component=recipe-list-workspace-states`.

package/ai/components/recipe-loading-inspector.md

@@ -0,0 +1,57 @@
+# Loading Inspector
+
+<!-- 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:recipe-loading-inspector` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+A record inspector whose per-record values load asynchronously — every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.
+
+- A detail or inspector view must render its real chrome while its per-record values are still loading, then swap to the populated record without duplicating markup.
+
+**Not when:**
+
+- Do not hand-build a separate empty-state layout, and do not use it for known progress — use LoadingSpinner for that.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css, individual-custom-element-registration.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [List](./list.md), [ValueTable](./value-table.md), [Select](./select.md), [SegmentedControl](./segmented-control.md), [ListItem](./list-item.md), [StateBanner](./state-banner.md), [Skeleton](./skeleton.md), [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** loading lifecycle; which values are unknown; fetching, transport, and domain data.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Each component marks itself aria-busy and disables its own controls while loading; the composition keeps labels and structure stable across the transition.
+
+## 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: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [List](./list.md), [ValueTable](./value-table.md), [Select](./select.md), [SegmentedControl](./segmented-control.md), [ListItem](./list-item.md), [StateBanner](./state-banner.md), [Skeleton](./skeleton.md), [LucideIcon](./lucide-icon.md).
+- Docs: [`docs/recipes.md#loading-inspector`](../../docs/recipes.md#loading-inspector).
+- UX catalog route: `?component=recipe-loading-inspector`.

package/ai/components/recipe-media-detail.md

@@ -0,0 +1,57 @@
+# Media Detail
+
+<!-- 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:recipe-media-detail` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+An Apple-Music-style album page: clear NavStack chrome with the scroll-edge material, a scoped tint from the artwork's color, an underChrome BackdropImage with parallax and progressive blur, and glass control groups.
+
+- A detail page for media (an album, artist, film, or place) should take on its artwork's color with the artwork running beneath transparent chrome.
+
+**Not when:**
+
+- Use the Navigation Stack recipe for a plain drill-down; imagery, tint, and clear chrome are for pages whose artwork is the identity.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [NavStack](./nav-stack.md), [Pane](./pane.md), [BackdropImage](./backdrop-image.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md).
+
+## State and wiring
+
+**The app owns:** the artwork and its accessible description; the artwork's bottom color and the scheme it belongs to (the tint); the stack (a signal of views); playback; data.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Glass control groups keep every chrome control at AA over the artwork; the tint clamps text to AA over the tinted surface; parallax, blur, and the scroll-edge fade go static under reduced motion or the static-effects switch, and the chrome and fade go opaque under reduced transparency and increased contrast.
+
+## 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: [NavStack](./nav-stack.md), [Pane](./pane.md), [BackdropImage](./backdrop-image.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md).
+- Docs: [`docs/recipes.md#media-detail`](../../docs/recipes.md#media-detail).
+- UX catalog route: `?component=recipe-media-detail`.

package/ai/components/recipe-navigation-sidebar.md

@@ -0,0 +1,57 @@
+# Navigation Sidebar
+
+<!-- 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:recipe-navigation-sidebar` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.
+
+- A workspace sidebar needs the shared toolbar/content/footer pane model, 24px major section rhythm, and 44px row and utility-action targets.
+
+**Not when:**
+
+- Use ordinary links when menu selection, section, and sidebar anatomy do not apply.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Pane](./pane.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [List](./list.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
+
+## State and wiring
+
+**The app owns:** information architecture; routing; permissions; disclosure state.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Native buttons retain names, current state, sequential focus, and disclosure state; rows and standalone footer actions remain at least 44px tall.
+
+## 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: [Pane](./pane.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [List](./list.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
+- Docs: [`docs/recipes.md#navigation-sidebar`](../../docs/recipes.md#navigation-sidebar).
+- UX catalog route: `?component=recipe-navigation-sidebar`.