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

package/ai/components/token-search-field.md

@@ -0,0 +1,101 @@
+# TokenSearchField
+
+<!-- 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:token-search-field` · Kerf UI · component · Controls
+
+## When to use
+
+Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
+
+- Combine DOM-owned free text with ordered editable/removable filter tokens in one searchbox.
+- Enable collapsible mode when an empty, unfocused search should reduce to one iconic action, standalone or inside a toolbar group.
+
+**Not when:**
+
+- Do not use for ordinary text input or separately labeled filter controls.
+
+**Alternatives:**
+
+- [Input](./wa-input.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/token-search-field` — exports `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`, `wireTokenSearchFields`.
+- CSS: the browser build of `@kerfjs/ui/token-search-field` pulls its CSS automatically; import `@kerfjs/ui/token-search-field.css` manually only without the `browser` export condition.
+- Wiring: `readTokenSearchField` from `@kerfjs/ui/token-search-field` (required).
+- Wiring: `placeTokenSearchCaret` from `@kerfjs/ui/token-search-field` (optional).
+- Wiring: `wireTokenSearchFields` from `@kerfjs/ui/wire-token-search-fields` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/token-search-field`](../public-api-signatures-v1.md#kerfjsuitoken-search-field), [`@kerfjs/ui/wire-token-search-fields`](../public-api-signatures-v1.md#kerfjsuiwire-token-search-fields) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- tokens
+- free text
+- disabled
+- collapsible standalone or toolbar composition
+
+## Composition
+
+- Parents: any.
+- Contexts: `structured-search-editor`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `leading-decoration` — JSX prop `leading`; accepts `dormant-decoration`; 0–1.
+- `trailing-control` — JSX prop `trailing`; accepts `control`; 0–1.
+
+## State and wiring
+
+- tokens — controlled (required)
+- text — component (required)
+- expanded — controlled
+
+**Wiring:** `wireTokenSearchFields` is required.
+
+- Retain and invoke the disposer.
+- Use readTokenSearchField for DOM-owned text.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-token-search-text` on `the text span inside kui-token-search__editor` (`wireTokenSearchFields`): Marks the plain-text span the helper inserts when the editor is emptied.
+- `data-empty` on `the text span inside kui-token-search__editor` (`wireTokenSearchFields`): "true" on that span while it holds no text.
+
+## 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
+
+- Announce result changes when useful and keep tokens atomic during editing.
+- Keep leading and trailing controls aligned to the first text line while content wraps. Managed Clear restores replacement focus before the next input task, preserving immediate typing and later focus handoffs without a frame delay.
+- Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion before the next keystroke. Select All deletion preserves managed open state and replacement focus; persist both edited query and tokens. Visual wrapping remains available.
+- In collapsible mode, wireTokenSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out.
+
+## 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-token-search`, `kui-token-search__clear`, `kui-token-search__editor`, `kui-token-search__expand`, `kui-token-search__leading`, `kui-token-search__token`, `kui-token-search__token-edit`, `kui-token-search__token-remove`, `kui-token-search__trailing`.
+
+Never put `kui-token-search`, `kui-token-search__clear`, `kui-token-search__editor`, `kui-token-search__expand`, `kui-token-search__leading`, `kui-token-search__token`, `kui-token-search__token-edit`, `kui-token-search__token-remove`, `kui-token-search__trailing` on an element you write; render `TokenSearchField` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-fill-normal`, `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-text-link`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-focus-ring`, `--kui-font-s`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-token-search-background`, `--kui-token-search-border`, `--kui-token-search-line-size`, `--kui-token-search-token-background`, `--kui-token-search-token-foreground`, `--kui-token-search-expanded-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`).
+
+## Diagnostics
+
+- `KUI-C105` (error) when wireTokenSearchFields is absent: TokenSearchField requires its public wiring helper for keyboard and collapsible behavior.
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [Input](./wa-input.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#tokensearchfield`](../../docs/accessibility.md#tokensearchfield).
+- UX catalog route: `?component=token-search-field`.

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

@@ -0,0 +1,102 @@
+# ToolbarControlGroup
+
+<!-- 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:toolbar-control-group` · Kerf UI · component · Structure
+
+Typed toolbar groups for buttons, semantic action links, compact mixed controls, selected states, dropdown surfaces, and avatar controls.
+
+## When to use
+
+Provide complete toolbar action geometry through configuration, including semantic anchors, overflow containment, and dropdown menu insets without application CSS.
+
+- Group related controls inside a toolbar with a supported visual treatment.
+- Use ToolbarActionLink for navigation or external resources that must retain native anchor semantics inside a group.
+- Fill it with plain \<button> controls (the group styles > button fully); use wa-button only for a Web Awesome feature. A popup menu is a PopupMenu in a single group with nestedDropdown; it renders its own trigger, so never hand-write wa-dropdown markup. Nothing wraps inside a group: an icon sits beside its label on one row and no trigger gets a fixed width.
+- For an avatar control, set content=avatar and avatarImage instead of inserting an img; one button paints the group and multiple buttons paint only the pressed highlight.
+- In a Workbench or CollapsiblePanel toolbar, mark a group relocateOnCollapse to keep it available in the work-area toolbar when the panel closes; place it directly or in an array in any toolbar zone.
+
+**Not when:**
+
+- Do not use merely to align unrelated buttons or to imitate an exclusive choice.
+- Do not reach for wa-button for an ordinary control inside the group — a plain \<button> is the default and avoids the Web Awesome dependency.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+- [Button Group](./wa-button-group.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/toolbar-control-group` — exports `ToolbarActionLink`, `ToolbarControlGroup`.
+- CSS: the browser build of `@kerfjs/ui/toolbar-control-group` pulls its CSS automatically; import `@kerfjs/ui/toolbar-control-group.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/toolbar-control-group`](../public-api-signatures-v1.md#kerfjsuitoolbar-control-group) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- contained
+- borderless
+- pressed
+- single
+- default or compact size
+- comfortable or tight density
+- icon, text, mixed, or avatar content
+- raised, filled, or outline selected chrome
+- brand, neutral, or pop selected tone
+- nested dropdown trigger
+- standard, compact, or list-zero dropdown menu inset
+- visible or horizontally scrollable overflow
+- always visible or compact-only responsive visibility
+- relocate on panel collapse
+- avatar scrim
+- contained avatar background on a single group or selected multi-button highlight
+
+## Composition
+
+- Parents: only inside [Toolbar](./toolbar.md).
+- Contexts: `toolbar-zone`.
+- Children: only `control` (required: `control`).
+- Built from: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `controls` — no declared JSX prop; accepts `control`; at least 1.
+
+## State and wiring
+
+**The app owns:** actions; link destination and copy; pressed state; expanded state; avatar image URL.
+
+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.
+
+## Accessibility
+
+- Name the group when its relationship is not evident from context.
+- 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
+
+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-toolbar-action-link`, `kui-toolbar-control-group`.
+
+Never put `kui-toolbar-action-link` on an element you write; render `ToolbarActionLink` instead (`KUI-L103`).
+
+Never put `kui-toolbar-control-group` on an element you write; render `ToolbarControlGroup` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-on-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-fill-normal`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-quiet`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-on-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-toolbar-control-background`, `--kui-toolbar-control-border`, `--kui-toolbar-control-color`, `--kui-toolbar-control-dark-border`, `--kui-toolbar-control-hover-background`, `--kui-toolbar-control-pressed-background`, `--kui-toolbar-control-pressed-border`, `--kui-toolbar-control-pressed-color`, `--kui-toolbar-control-selected-background`, `--kui-toolbar-control-selected-color`, `--kui-toolbar-control-selected-shadow`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md), [Button Group](./wa-button-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=toolbar-control-group`.

package/ai/components/toolbar-text.md

@@ -0,0 +1,76 @@
+# ToolbarText
+
+<!-- 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:toolbar-text` · Kerf UI · component · Structure
+
+## When to use
+
+Large, default, and compact toolbar identity text.
+
+- Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics.
+
+**Not when:**
+
+- Do not omit headingLevel when the text is the page or section heading.
+- Do not use a size below xlarge as a normal-color subsection title: large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section.
+
+**Alternatives:**
+
+- [Text](./text.md) (semantic-alternative) — Use Text variant h2-h6 for a normal-color subsection title in content rather than toolbar identity.
+- [ListHeader](./list-header.md) (semantic-alternative) — Use ListHeader for a list or menu section label with a count, badge, action, or disclosure.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/toolbar-text` — exports `ToolbarText`.
+- CSS: the browser build of `@kerfjs/ui/toolbar-text` pulls its CSS automatically; import `@kerfjs/ui/toolbar-text.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures-v1.md#kerfjsuitoolbar-text) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- large
+- default
+- small
+- placeholder (loading)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** text; responsive priority.
+
+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.
+
+## Accessibility
+
+- Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title.
+
+## 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-toolbar-text`.
+
+Never put `kui-toolbar-text` on an element you write; render `ToolbarText` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-on-quiet`, `--kui-color-text`, `--kui-font-2xl`, `--kui-font-l`, `--kui-font-m`, `--kui-font-s`, `--kui-font-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: [Text](./text.md), [ListHeader](./list-header.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-text`.

package/ai/components/toolbar.md

@@ -0,0 +1,95 @@
+# Toolbar
+
+<!-- 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:toolbar` · Kerf UI · component · Structure
+
+## When to use
+
+Leading, centered, and trailing toolbar composition.
+
+- Compose application chrome or a page, panel, or dialog heading with leading, center, and trailing regions.
+
+**Not when:**
+
+- Do not use it as a generic wrapper when no toolbar or heading relationship exists.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/toolbar` — exports `Toolbar`.
+- CSS: the browser build of `@kerfjs/ui/toolbar` pulls its CSS automatically; import `@kerfjs/ui/toolbar.css` manually only without the `browser` export condition.
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.md#kerfjsuitoolbar), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- no dividers (default)
+- scroll dividers when named as wireScrollDividers targets chrome
+- top/right/bottom/left divider combinations
+- centered content
+- stacked zones at compact or narrow widths
+- content-driven wrap that keeps a heading title whole
+- center priority for an expanded center control
+- trailing groups wrap instead of clipping
+- app bar or bottom bar claiming its screen edges (safeAreaEdges)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-chrome`, `page-header`, `panel-header`, `dialog-header`.
+- Children: only [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md).
+- Built from: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `leading` — JSX prop `leading`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md); any number.
+- `center` — JSX prop `center`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md); any number.
+- `trailing` — JSX prop `trailing`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md); any number.
+
+## State and wiring
+
+**The app owns:** actions; command availability; responsive relocation; which screen edges an app bar or bottom bar outside a Pane header or footer claims for device safe areas (safeAreaEdges).
+
+**Wiring:** `wireScrollDividers` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-scroll-overflow` on `the targets scroller` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
+- `data-scroll-divider` on `a Toolbar named as targets chrome` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+
+## Geometry
+
+Margin: none · border: conditional · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Padding belongs to the toolbar; dividerSides selects any canonical combination of its physical top, right, bottom, and left edges.
+- Safe areas: a Pane header or footer hands a sole Toolbar its inline edges; an app bar or bottom bar at a screen edge claims its sides with safeAreaEdges and pads each claimed side by the --kui-edge-inset-\* context or the full device inset, while its box and dividers paint through.
+
+## Accessibility
+
+- Supply a label when the toolbar needs an accessible name.
+
+## 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-toolbar`, `kui-toolbar__center`, `kui-toolbar__leading`, `kui-toolbar__trailing`.
+
+Never put `kui-toolbar`, `kui-toolbar__center`, `kui-toolbar__leading`, `kui-toolbar__trailing` on an element you write; render `Toolbar` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-font-sans`, `--kui-toolbar-divider-color`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Diagnostics
+
+- `KUI-C101` (error) when a direct zone child is neither ToolbarText nor ToolbarControlGroup: Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup are direct zone children.
+
+## Related
+
+- Components: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.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=toolbar`.

package/ai/components/value-table.md

@@ -0,0 +1,72 @@
+# ValueTable
+
+<!-- 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:value-table` · Kerf UI · component · Structure
+
+Key/value rows with optional icons.
+
+## When to use
+
+Key/value rows with optional icons and aligned separators.
+
+- Present read-only label/value facts as a semantic definition list, optionally with a 24px leading icon.
+
+**Not when:**
+
+- Do not use for editable fields or row/column tabular data.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/value-table` — exports `ValueTable`, `ValueTableRow`.
+- CSS: the browser build of `@kerfjs/ui/value-table` pulls its CSS automatically; import `@kerfjs/ui/value-table.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/value-table`](../public-api-signatures-v1.md#kerfjsuivalue-table) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- icon rows
+- iconless rows
+- placeholder (loading)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** values; formatting; empty policy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Name ValueTable with its label; ValueTableRow supplies dt/dd semantics, and row icons stay decorative unless meaning requires an accessible label.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-value-table`, `kui-value-table__row`, `kui-value-table__icon`, `kui-value-table__label`.
+
+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-color-text-quiet`, `--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`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=value-table`.

package/ai/components/wa-accordion-item.md

@@ -0,0 +1,55 @@
+# Accordion Item
+
+<!-- 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:wa-accordion-item` · Web Awesome · component · Layout · recommendation: supported
+
+## When to use
+
+Experimental labeled disclosure section used by an accordion.
+
+**Not when:**
+
+- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/accordion-item/accordion-item.js` once (a side effect).
+- Custom element: `<wa-accordion-item>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Icon](./wa-icon.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: layout). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+## Related
+
+- Components: [Icon](./wa-icon.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-accordion-item`.

package/ai/components/wa-accordion.md

@@ -0,0 +1,65 @@
+# Accordion
+
+<!-- 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:wa-accordion` · Web Awesome · component · Layout · recommendation: supported
+
+## When to use
+
+Coordinates one or more collapsible content sections.
+
+**Not when:**
+
+- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/accordion/accordion.js` once (a side effect).
+- Custom element: `<wa-accordion>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+**Variants (configure, do not restyle):**
+
+- sunken appearance
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: only [Accordion Item](./wa-accordion-item.md) (required: [Accordion Item](./wa-accordion-item.md)).
+- Built from: [Accordion Item](./wa-accordion-item.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `items` — no declared JSX prop; accepts [Accordion Item](./wa-accordion-item.md); at least 1.
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: layout). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+Public tokens it reads: `--kui-wa-surface-margin`, `--kui-wa-surface-inset`, `--kui-wa-sunken-background`, `--kui-wa-sunken-radius`. Set a token only where its public contract allows; prefer a prop.
+
+## Related
+
+- Components: [Accordion Item](./wa-accordion-item.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-accordion`.

package/ai/components/wa-animated-image.md

@@ -0,0 +1,55 @@
+# Animated Image
+
+<!-- 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:wa-animated-image` · Web Awesome · component · Media · recommendation: exceptional
+
+## When to use
+
+Specialized animated media; use only for a concrete product requirement.
+
+**Not when:**
+
+- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/animated-image/animated-image.js` once (a side effect).
+- Custom element: `<wa-animated-image>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Icon](./wa-icon.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: none (layout role: media). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+## Related
+
+- Components: [Icon](./wa-icon.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-animated-image`.