@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.100

package/ai/components/spacer.md

@@ -0,0 +1,86 @@
+# Spacer
+
+<!-- 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:spacer` · Kerf UI · component · Structure
+
+A decorative, non-shrinking fixed gap or flexible main-axis spacer with typed physical width and height.
+
+## When to use
+
+Express an intentional empty dimension or consume remaining flex space without application-owned spacer markup or raw CSS lengths.
+
+- Reserve a fixed empty width or height from the UI spacing scale inside a layout.
+- Push siblings to opposite ends of a Row or other flex container by passing flex.
+- Use a typed CssLength when the finite spacing scale cannot express the required dimension.
+
+**Not when:**
+
+- Do not use Spacer for ordinary rhythm between siblings; prefer Row.gap or List.gap so the parent owns repeated spacing.
+- Do not use Spacer to compensate for component-owned padding, margin, alignment, or responsive layout defects.
+- Do not pass raw CSS strings to width or height.
+
+**Alternatives:**
+
+- [Row](./row.md) (parent-spacing-alternative) — Use Row.gap when every horizontal sibling needs the same repeated separation.
+- [List](./list.md) (parent-spacing-alternative) — Use List.gap when every vertical sibling needs the same repeated separation.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/spacer` — exports `Spacer`.
+- CSS: the browser build of `@kerfjs/ui/spacer` pulls its CSS automatically; import `@kerfjs/ui/spacer.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/spacer`](../public-api-signatures-v1.md#kerfjsuispacer) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- fixed named width and/or height
+- fixed typed CssLength width and/or height
+- flexible main-axis space
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `width`: length grammar; raw values: forbid; shorthands `none`, `2xs`, `xs`, `m`, `l`; exceptional (justify) `s`, `xl`; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `width="m"`
+- `height`: length grammar; raw values: forbid; shorthands `none`, `2xs`, `xs`, `m`, `l`; exceptional (justify) `s`, `xl`; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `height="xs"`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** whether the empty space carries structural meaning; the named or typed dimensions; whether the spacer fills the flex main axis.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- A fixed Spacer does not shrink. flex changes its flex shorthand from 0 0 auto to 1 1 auto; width and height remain physical dimensions.
+
+## Accessibility
+
+- Spacer is always decorative and hidden from the accessibility tree.
+- Spacer must not contain content or become an interaction target.
+
+## 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-spacer`.
+
+Never put `kui-spacer` on an element you write; render `Spacer` 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: [Row](./row.md), [List](./list.md).
+- Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/layout.md#spacer`](../../docs/layout.md#spacer).
+- UX catalog route: `?component=spacer`.

package/ai/components/split-button.md

@@ -0,0 +1,80 @@
+# SplitButton
+
+<!-- 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:split-button` · Kerf UI · component · Controls
+
+A primary action with an attached options trigger on one loud semantic fill.
+
+## When to use
+
+Render a prominent primary action plus an options trigger (provider, model, target) as one control with a semantic tone, full-width sizing, a busy presentation, and native aria-expanded on the trigger, outside any Toolbar.
+
+- A prominent primary action has a closely related set of options chosen from an attached trigger, such as Drive with a provider menu or Deploy with targets.
+
+**Not when:**
+
+- Do not use for a plain action without options; use wa-button.
+- Do not use inside a Toolbar for a command menu; use PopupMenu in a ToolbarControlGroup.
+- Do not use wa-button-group to build one; its hosts do not forward aria-expanded or names to their inner buttons.
+
+**Alternatives:**
+
+- [Button Group](./wa-button-group.md) (prefer-over) — SplitButton's native halves expose names and aria-expanded directly.
+- [PopupMenu](./popup-menu.md) (composes-with) — Open the app's options menu from optionsAction; PopupMenu remains the command menu inside a toolbar.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/split-button` — exports `SplitButton`.
+- CSS: the browser build of `@kerfjs/ui/split-button` pulls its CSS automatically; import `@kerfjs/ui/split-button.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/split-button`](../public-api-signatures-v1.md#kerfjsuisplit-button) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- brand, neutral, success, warning, or danger tone
+- content width or fill
+- busy
+- disabled primary or options
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md), [LoadingSpinner](./loading-spinner.md).
+
+## State and wiring
+
+**The app owns:** the primary and options actions; the options menu and its open state; the running state, tone switch, and copy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Both halves are native buttons in a group; the options trigger exposes aria-haspopup, aria-expanded, and optional aria-controls, and needs optionsLabel. busy sets aria-busy on the primary.
+
+## 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-split-button`, `kui-split-button__options`, `kui-split-button__icon`, `kui-split-button__label`.
+
+Never put `kui-split-button`, `kui-split-button__options`, `kui-split-button__icon`, `kui-split-button__label` on an element you write; render `SplitButton` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-success-fill-loud`, `--kui-color-success-on-loud`, `--kui-color-warning-fill-loud`, `--kui-color-warning-on-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-focus-ring`, `--kui-font-weight-semibold`, `--kui-layout-rounded-radius`, `--kui-space-s`, `--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), [Button Group](./wa-button-group.md), [PopupMenu](./popup-menu.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=split-button`.

package/ai/components/split-view.md

@@ -0,0 +1,105 @@
+# SplitView
+
+<!-- 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:split-view` · Kerf UI · component · Structure
+
+A responsive list-detail layout that shows both panes on roomy device classes and collapses to a navigation stack on compact classes.
+
+## When to use
+
+Present a selectable list and its detail together when space permits, with a one-pane drill-down replacement on compact devices.
+
+- Selection in a primary list updates a related detail pane and both should remain visible on roomy device classes.
+- The same list-detail flow must become a navigation stack on a handset or portrait tablet.
+
+**Not when:**
+
+- Do not use SplitView for a single linear flow; use NavStack.
+- Do not use it for a complex desktop tool with multiple peripheral panels; use Workbench.
+
+**Alternatives:**
+
+- [Navigation Stack](./recipe-navigation-stack.md) (responsive-alternative) — SplitView renders the one-pane navigation-stack form on compact device classes.
+- [Workbench](./workbench.md) (nearest) — Use Workbench when a desktop-class tool needs more than the list and detail regions.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/split-view` — exports `SplitView`, `SplitViewProps`, `SplitViewResizable`, `SplitViewCompactStack`, `SplitViewCompactViewToolbars`.
+- CSS: the browser build of `@kerfjs/ui/split-view` pulls its CSS automatically; import `@kerfjs/ui/split-view.css` manually only without the `browser` export condition.
+- Wiring: `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` (optional).
+- Wiring: `wireNavStack` from `@kerfjs/ui/wire-nav-stack` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/split-view`](../public-api-signatures-v1.md#kerfjsuisplit-view), [`@kerfjs/ui/wire-resizable-regions`](../public-api-signatures-v1.md#kerfjsuiwire-resizable-regions), [`@kerfjs/ui/wire-nav-stack`](../public-api-signatures-v1.md#kerfjsuiwire-nav-stack) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- fixed roomy split with listWidth: a pixel size, optionally capped at a fraction of the split's width
+- resizable roomy split
+- collapsed resizable list with a restore control
+- compact list
+- compact detail
+- compact stack with configured toolbars
+
+## Composition
+
+- Parents: any.
+- Contexts: `list-detail`, `responsive-master-detail`.
+- Children: unrestricted.
+- Built from: [NavStack](./nav-stack.md), [ResizableRegion](./resize.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `list` — JSX prop `list`; accepts `list-region`; exactly 1.
+- `detail` — JSX prop `detail`; accepts `detail-region`; exactly 1.
+
+## State and wiring
+
+**The app owns:** device-class policy; selected item and detail-active state; list and detail content; optional list width and persistence; optional list collapse state and its restore control; compact list and detail toolbar groups, toolbar configuration, and chrome dividers; back action.
+
+**Wiring:** `wireResizableRegions`, `wireNavStack` is required.
+
+- Use wireNavStack as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-handle-inset` on `kui-resizable-region` (`wireResizableRegions`): Present while a clipping edge clamps the region: the handle and its focus ring sit inside the region instead of overhanging that edge.
+- `data-resizing` on `kui-resizable-region` (`wireResizableRegions`): "true" during an active pointer drag of the handle.
+- `data-nav-chrome-transition` on `kui-nav-stack` (`wireNavStack`): "true" while the chrome cross-fades between the outgoing and incoming view.
+- `data-nav-chrome-copy` on `kui-nav-stack__chrome-copy` (`wireNavStack`): Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade.
+- `data-nav-revealed` on `kui-nav-stack__view` (`wireNavStack`): "true" on the preserved, aria-hidden previous view while an incoming view slides over it.
+- `data-nav-exiting` on `kui-nav-stack__view` (`wireNavStack`): "true" on a popped view the helper briefly re-inserts to slide it out.
+- `data-chrome-overlay` on `kui-nav-stack` (`wireNavStack`): measured once the helper has measured the compact stack's overlay chrome (compactStack.chromePresentation: overlay) and published its border-box height on the stack root. Re-applied if a re-render drops it.
+- `data-bottom-toolbar-overlay` on `kui-nav-stack` (`wireNavStack`): measured once the helper has measured the compact stack's overlay bottom toolbar (compactStack.bottomToolbarPresentation: overlay) and published its border-box height on the stack root. 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 root owns the two-column split and the list pane owns its separator; list and detail content own their internal padding and scroll behavior.
+
+## Accessibility
+
+- Give the overall split and both meaningful panes accessible labels.
+- Wire the compact back action and optional separator keyboard behavior, and restore focus when controlled navigation replaces a view.
+
+## 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-split-view`, `kui-split-view__list`, `kui-split-view__detail`, `kui-split-view--compact`.
+
+Never put `kui-split-view`, `kui-split-view__list`, `kui-split-view__detail`, `kui-split-view--compact` on an element you write; render `SplitView` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-split-view-list-width`. 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: [NavStack](./nav-stack.md), [ResizableRegion](./resize.md), [Navigation Stack](./recipe-navigation-stack.md), [Workbench](./workbench.md).
+- Docs: [`docs/split-view.md`](../../docs/split-view.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
+- UX catalog route: `?component=split-view`.

package/ai/components/state-banner.md

@@ -0,0 +1,96 @@
+# 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)
+- [CornerStatus](./corner-status.md) (composes-with) — Host app-level progress in a viewport corner with CornerStatus instead of fixed-position CSS.
+
+## 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
+- stacked copy
+- action below
+- strip presentation
+- 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-copy-gap`, `--kui-state-banner-copy-row-gap`, `--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`, `--kui-shadow-l`. 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), [CornerStatus](./corner-status.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/summary-row.md

@@ -0,0 +1,85 @@
+# SummaryRow
+
+<!-- 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:summary-row` · Kerf UI · component · Structure
+
+A selectable, focusable summary of one item as a list row or a board card, with a state rail, a clamped title, trailing meta, and a metadata line.
+
+## When to use
+
+Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.
+
+- A list or board shows many items as dense, selectable summaries with an identifier, a title, a timestamp, and metadata.
+
+**Not when:**
+
+- Do not use for navigation rows with a single label; use ListItem.
+- Do not use for selectable tiles of free-form content; use ContentItem with selectionMode.
+- Do not hand-roll row chrome (selection fill, rail, title clamp, edge rounding) in app CSS.
+
+**Alternatives:**
+
+- [ListItem](./list-item.md) (nearest) — Use ListItem for navigation rows.
+- [ContentItem](./content-item.md) (nearest) — Use ContentItem for selectable rich tiles.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/summary-row` — exports `SummaryRow`.
+- CSS: the browser build of `@kerfjs/ui/summary-row` pulls its CSS automatically; import `@kerfjs/ui/summary-row.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/summary-row`](../public-api-signatures-v1.md#kerfjsuisummary-row) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- row
+- card
+- selected
+- dimmed
+- state rail
+- list edge start, end, or only
+- title line budget
+- deferred rendering
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the listbox container, selection set, and keyboard movement; the title, leading glyph, trailing meta, and metadata content; rail tone and dimming policy.
+
+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.
+
+- Rows sit flush in a list section and round only the corners at its edges; cards are borderless rounded cards.
+
+## Accessibility
+
+- Each SummaryRow is role=option with tabindex=0 and aria-selected; place rows in a labeled role=listbox and move focus with the arrow keys in the app. The rail is decorative; carry its meaning in text.
+
+## 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-summary-row`, `kui-summary-row__rail`, `kui-summary-row__body`, `kui-summary-row__leading`, `kui-summary-row__content`, `kui-summary-row__title`, `kui-summary-row__trailing`, `kui-summary-row__metadata`.
+
+Never put `kui-summary-row`, `kui-summary-row__rail`, `kui-summary-row__body`, `kui-summary-row__leading`, `kui-summary-row__content`, `kui-summary-row__title`, `kui-summary-row__trailing`, `kui-summary-row__metadata` on an element you write; render `SummaryRow` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-border-quiet`, `--kui-color-text`, `--kui-color-surface`, `--kui-color-brand-border-normal`, `--kui-color-text-link`, `--kui-color-brand-fill-quiet`, `--kui-color-neutral-on-quiet`, `--kui-color-brand-fill-loud`, `--kui-color-pop-fill-loud`, `--kui-color-success-fill-loud`, `--kui-color-warning-fill-loud`, `--kui-color-danger-fill-loud`, `--kui-color-text-quiet`, `--kui-font-2xs`, `--kui-font-xs`, `--kui-layout-rounded-radius`, `--kui-space-2xs`, `--kui-space-s`, `--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: [ListItem](./list-item.md), [ContentItem](./content-item.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=summary-row`.

package/ai/components/sunken-panel.md

@@ -0,0 +1,79 @@
+# SunkenPanel
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:sunken-panel` · Kerf UI · component · Structure
+
+A rounded or square-corner lowered application surface with one compact inset and a vertical content stack.
+
+## When to use
+
+Group a vertical list of application content on a visually lowered surface with one owned 8px inset and an explicit rounded or square-corner shape.
+
+- A main content region or nested work area needs a darker/lowered background and one compact inset around a vertical stack.
+- Use the default rounded shape for an inset surface; choose square for a flush or edge-to-edge application area.
+
+**Not when:**
+
+- Do not use it merely to add padding, as a substitute for Pane anatomy, or around children that already own the same outer surface.
+
+**Alternatives:**
+
+- [Application Layout](./layout.md) (composes-with) — Use layout roles for pane, toolbar, scroll, and ordinary content-stack ownership.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/sunken-panel` — exports `SunkenPanel`, `ensureSunkenTexture`.
+- CSS: the browser build of `@kerfjs/ui/sunken-panel` pulls its CSS automatically; import `@kerfjs/ui/sunken-panel.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/sunken-panel`](../public-api-signatures-v1.md#kerfjsuisunken-panel) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- rounded surface
+- square-corner surface
+- unnamed surface
+- named region
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** region semantics and accessible name; corner shape; scroll ownership; child ordering and content; optional keyboard or programmatic focus (tabIndex) and persistent outline (outlined).
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The root owns one 8px inset and vertical gap; children own their borders and internal geometry.
+
+## Accessibility
+
+- Pass ariaLabel only when the surface is a distinct named region; otherwise it remains a non-landmark grouping.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-sunken-panel`.
+
+Never put `kui-sunken-panel` on an element you write; render `SunkenPanel` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-sunken-panel-background`, `--kui-sunken-panel-foreground`, `--kui-sunken-panel-gap`, `--kui-sunken-panel-padding`, `--kui-sunken-panel-radius`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Application Layout](./layout.md).
+- Docs: [`docs/sunken-panel.md`](../../docs/sunken-panel.md), [`docs/sunken-panel.md#ownership`](../../docs/sunken-panel.md#ownership).
+- UX catalog route: `?component=sunken-panel`.

package/ai/components/surface-scaffold.md

@@ -0,0 +1,105 @@
+# 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 preferred widths and viewport bounds, presentation, and popup inset composition.
+
+## When to use
+
+Configure recurring dialog and popup geometry without consumer ::part() overrides.
+
+- A Web Awesome dialog or dropdown needs a standard size, presentation, body/footer inset, or list-compatible menu inset.
+- A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText.
+- A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions.
+- A dialog that must leave the page interactive and close on Escape or an outside press uses PopoverDialogSurface; one that fills its body with a SplitView or Pane uses height and bodyLayout="fill".
+- A chat-style dialog floats its composer over the transcript with footerPresentation="floating" and keeps a heading or notice above one scrolling transcript with bodyLayout="fill-last".
+- A dialog's title bar should float over the body on the translucent chrome material so a transcript scrolls visibly beneath both the title bar and a floating composer (headerPresentation="floating" with bodyLayout="fill" and a List or Pane that opts into scrollClearance="both").
+
+**Not when:**
+
+- Do not use it as a generic layout wrapper 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.
+- Do not put quiet secondary text of your own in a floating dialog header; it can fall below AA over the content passing beneath. A ToolbarText slotted as the dialog's label (or into header-actions) is fine: its title takes the normal text color and its description lifts halfway toward it, keeping AA.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/surface-scaffold` — exports `DialogSurface`, `PopoverDialogSurface`, `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.
+- Registration: import `@kerfjs/ui/surface-scaffold/register` once (a side effect).
+- Declared side effects: browser-condition-css, custom-element-registration.
+
+## 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
+- data-\* rootAttributes (a data-key) so sibling dialogs morph by identity
+- modal, side-sheet, or fullscreen dialog
+- typed modal preferred width, viewport gutter, and maximum height, including viewport cap
+- definite viewport-bounded modal height and a fill body layout for one child
+- fill-last body layout: fixed rows above one filling, scrolling last child
+- docked or floating footer with a typed footerOffset; the body reserves the measured footer height
+- floating footer over a filling child that opts into block-end scrollClearance: content scrolls beneath the footer through the published --kui-scroll-clearance-block-end
+- docked or floating header (headerPresentation) on the translucent chrome material; the body reserves the measured header height
+- floating header over a filling only child that opts into block-start scrollClearance: content scrolls beneath the title bar through the published --kui-scroll-clearance-block-start
+- floating header divider as scroll state: a hairline under the title bar only while the body or a filling child beneath it is scrolled away from its top
+- non-modal light-dismiss PopoverDialogSurface, overlay or embedded in flow, named by label or labelledBy and described by describedBy
+- none, compact, or comfortable body and footer inset
+- standard, compact, or zero-inset popup menu
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `preferredWidth`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `preferredWidth={remify(832)}`
+- `viewportGutter`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `viewportGutter={remify(8)}`
+- `footerOffset`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `footerOffset={remify(8)}`
+- `maxHeight`: length grammar; raw values: forbid; shorthands `viewport`; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `maxHeight="viewport"`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [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.
+- Name a PopoverDialogSurface with label or labelledBy, and describe it with describedBy (rendered as aria-describedby), usually a title ToolbarText descriptionId.
+- A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
+- Use popup surfaces only for real dropdown menus with named triggers.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-dialog-surface`, `kui-popover-dialog-surface`, `kui-popup-surface`.
+
+Never put `kui-dialog-surface` on an element you write; render `DialogSurface` instead (`KUI-L103`).
+
+Never put `kui-popover-dialog-surface` on an element you write; render `PopoverDialogSurface` instead (`KUI-L103`).
+
+Never put `kui-popup-surface` on an element you write; render `PopupSurface` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-radius-l`, `--kui-wa-container-inset`, `--kui-wa-surface-inset`, `--kui-chrome-material-raised`, `--kui-chrome-material-filter`, `--kui-scroll-clearance-block-start`, `--kui-scroll-clearance-block-end`. 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`.