@kerfjs/ui 5.0.0-beta.94 → 5.0.0-beta.96

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

@@ -37,7 +37,7 @@ Exact prop names and types: [`@kerfjs/ui/split-view`](../public-api-signatures-v
 
 **Variants (configure, do not restyle):**
 
-- fixed roomy split
+- 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

package/ai/components/state-banner.md

@@ -22,6 +22,7 @@ Present persistent inline feedback or attractive non-status emphasis with a name
 - [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
 
@@ -46,6 +47,7 @@ Exact prop names and types: [`@kerfjs/ui/state-banner`](../public-api-signatures
 - badge
 - stacked copy
 - action below
+- strip presentation
 - placeholder (loading)
 
 ## Composition
@@ -83,12 +85,12 @@ Public class hooks (select for layout placement only, never to change the compon
 
 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`. Set a token only where its public contract allows; prefer a prop.
+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).
+- 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

@@ -23,7 +23,7 @@ Group a vertical list of application content on a visually lowered surface with
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/sunken-panel` — exports `SunkenPanel`.
+- 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.
 

package/ai/components/surface-scaffold.md

@@ -13,6 +13,7 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 - 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".
 
 **Not when:**
 
@@ -21,7 +22,7 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/surface-scaffold` — exports `DialogSurface`, `PopupSurface`.
+- 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.
@@ -33,8 +34,11 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 **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
+- non-modal light-dismiss PopoverDialogSurface, overlay or embedded in flow
 - none, compact, or comfortable body and footer inset
 - standard, compact, or zero-inset popup menu
 
@@ -70,10 +74,12 @@ Margin: parent · border: child · padding: self (layout role: structure). `self
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public class hooks (select for layout placement only, never to change the component's look): `kui-dialog-surface`, `kui-popup-surface`.
+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`. Set a token only where its public contract allows; prefer a prop.

package/ai/components/text.md

@@ -40,7 +40,9 @@ Exact prop names and types: [`@kerfjs/ui/text`](../public-api-signatures-v1.md#k
 - compact, default, large, or xlarge size
 - default or monospace font
 - flush item geometry and tight line height
+- align start (default), center, or end for centered status copy or trailing values
 - controlMargins selects exterior 8px gutters with canonical physical Sides
+- wrap normal, anywhere, nowrap, or truncate; truncate places its ellipsis at the end, the start (keeping the tail), or the middle (keeping the last path segment or a character suffix)
 
 ## Composition
 
@@ -67,6 +69,7 @@ Margin: self · border: self · padding: self (layout role: structure). `self` m
 - Ordinary global, data, and ARIA attributes pass through to the native element.
 - Choose tone, size, and font independently of the heading level so appearance does not distort the document outline.
 - FieldLabel is plain text, not a native label; give it an id and associate the preview group with aria-labelledby.
+- Start and middle truncation clip visually only: the whole value stays in the DOM in reading order, and Text shows it as the element's title unless the app supplies one.
 
 ## Styling boundary
 

package/ai/components/toolbar-control-group.md

@@ -28,6 +28,7 @@ Provide complete toolbar action geometry through configuration, including semant
 
 - [SegmentedControl](./segmented-control.md) (nearest)
 - [Button Group](./wa-button-group.md) (prefer-over)
+- [IconToggleButton](./icon-toggle-button.md) (nearest) — Outside a Toolbar, a standalone icon-only toggle is an IconToggleButton.
 
 ## Imports
 
@@ -49,7 +50,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-control-group`](../public-api-s
 - default or compact size
 - comfortable or tight density
 - icon, text, mixed, or avatar content
-- raised, filled, or outline selected chrome
+- raised, filled, outline, or no selected chrome (group-wide or one control via data-selected-chrome="none")
 - brand, neutral, or pop selected tone
 - nested dropdown trigger
 - standard, compact, or list-zero dropdown menu inset
@@ -98,6 +99,7 @@ Margin: none · border: self · padding: self (layout role: structure). `self` m
 ## Accessibility
 
 - Name the group when its relationship is not evident from context.
+- A disabled native button (disabled, or aria-disabled="true" when it must stay focusable) dims to half opacity with the not-allowed cursor and no hover surface; a disabled raw wa-button paints no hover surface either. Do not add disabled styling yourself.
 - Name an icon-only button or link with aria-label, not title. Once any help-tag installer is imported (select/register, popup-menu/register, or help-tags/register), it shows an aria-hidden Web Awesome help tag repeating that name after a 500ms hover and at once on keyboard focus, hidden on a press and on Escape, and never joins aria-labelledby. A native title keeps the browser tooltip and gets no second tag.
 
 ## Styling boundary
@@ -116,6 +118,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md), [Button Group](./wa-button-group.md).
+- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md), [Button Group](./wa-button-group.md), [IconToggleButton](./icon-toggle-button.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
 - UX catalog route: `?component=toolbar-control-group`.

package/ai/components/toolbar-text.md

@@ -43,6 +43,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures
 - small
 - xsmall
 - placeholder (loading)
+- description: quiet single-line supporting copy under a read-only title, aligned with its text, with descriptionId for aria-describedby
 - dark (loud-surface foreground)
 - typed hideBelow/showBelow thresholds at the nearest Toolbar content width
 

package/ai/components/toolbar.md

@@ -40,6 +40,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.m
 - trailing priority for an expanded trailing control at compact or narrow widths
 - trailing groups and a standalone primary wa-button wrap instead of clipping
 - outer inset independently configurable from zone gap
+- compact density: a 40px header (34px band, 3px block insets) for an embedded panel, filled with compact ToolbarControlGroups
 - app bar or bottom bar claiming its screen edges (safeAreaEdges)
 - typed hideBelow/showBelow thresholds at the nearest Toolbar content width
 

package/ai/components/value-table.md

@@ -16,6 +16,10 @@ Key/value rows with optional icons and aligned separators.
 
 - Do not use for editable fields or row/column tabular data.
 
+**Alternatives:**
+
+- [FramedList](./framed-list.md) (nearest) — Use FramedList for rows of arbitrary content (copy and controls) in the same frame.
+
 ## Imports
 
 - JavaScript: `@kerfjs/ui/value-table` — exports `ValueTable`, `ValueTableRow`.
@@ -32,6 +36,9 @@ Exact prop names and types: [`@kerfjs/ui/value-table`](../public-api-signatures-
 - iconless rows
 - compact density
 - placeholder (loading)
+- minimum label column (labelWidth)
+- stacked presentation
+- stack below a compact or narrow table width
 
 ## Composition
 
@@ -62,12 +69,12 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-value-table`, `kui-value-table__row`, `kui-value-table__icon`, `kui-value-table__label` on an element you write; render `ValueTable` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-color-surface-lowered`, `--kui-color-text`, `--kui-font-weight-semibold`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-space-2xs`, `--kui-value-table-background`, `--kui-value-table-border`, `--kui-value-table-icon-size`, `--kui-value-table-row-columns`, `--kui-value-table-row-padding-block`, `--kui-value-table-row-gap`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-color-surface-lowered`, `--kui-color-text`, `--kui-font-weight-semibold`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-space-2xs`, `--kui-value-table-background`, `--kui-value-table-border`, `--kui-value-table-icon-size`, `--kui-value-table-row-columns`, `--kui-value-table-row-gap`, `--kui-value-table-row-padding-block`. 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).
+- Components: [LucideIcon](./lucide-icon.md), [FramedList](./framed-list.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=value-table`.

package/ai/components/wa-button-group.md

@@ -15,6 +15,7 @@ Exceptional grouped actions; prefer Kerf SegmentedControl for exclusive choices.
 **Alternatives:**
 
 - [SegmentedControl](./segmented-control.md) (prefer-kerf)
+- [SplitButton](./split-button.md) (prefer-kerf) — For a primary action with an attached options trigger, use SplitButton.
 
 ## Imports
 
@@ -54,6 +55,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Button](./wa-button.md), [SegmentedControl](./segmented-control.md).
+- Components: [Button](./wa-button.md), [SegmentedControl](./segmented-control.md), [SplitButton](./split-button.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
 - UX catalog route: `?component=wa-button-group`.

package/ai/components/wa-button.md

@@ -12,6 +12,10 @@ Action control with semantic variants, appearances, loading, and icon support.
 
 - Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
 
+**Alternatives:**
+
+- [IconButton](./icon-button.md) (prefer-kerf) — For an icon-only button with a LucideIcon, use IconButton for Web Awesome's square icon-button geometry.
+
 ## Imports
 
 - Theme CSS: import `@kerfjs/ui/webawesome.css` once.
@@ -50,6 +54,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Icon](./wa-icon.md), [Spinner](./wa-spinner.md).
+- Components: [Icon](./wa-icon.md), [Spinner](./wa-spinner.md), [IconButton](./icon-button.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-button`.