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

package/ai/components/toolbar.md

@@ -0,0 +1,103 @@
+# 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.
+- Use typed hideBelow/showBelow lengths with wireToolbarVisibility(root) for per-item toolbar priority; keep primary actions available and provide a showBelow overflow alternative.
+
+**Not when:**
+
+- Do not use it as a generic wrapper when no toolbar or heading relationship exists.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/toolbar` — exports `Toolbar`.
+- JavaScript: `@kerfjs/ui/wire-toolbar-visibility` — exports `wireToolbarVisibility`.
+- 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).
+- Wiring: `wireToolbarVisibility` from `@kerfjs/ui/wire-toolbar-visibility` (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-toolbar-visibility`](../public-api-signatures-v1.md#kerfjsuiwire-toolbar-visibility), [`@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 (by its id)
+- 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 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
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-chrome`, `page-header`, `panel-header`, `dialog-header`.
+- Children: unrestricted.
+- Built from: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [PopupMenu](./popup-menu.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 `KerfUiContent`; any number.
+- `center` — JSX prop `center`; accepts `KerfUiContent`; any number.
+- `trailing` — JSX prop `trailing`; accepts `KerfUiContent`; 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`, `wireToolbarVisibility` 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.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it.
+- `data-toolbar-width-hidden` on `ToolbarText, ToolbarControlGroup and its paired busy status` (`wireToolbarVisibility`): True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers.
+- `data-toolbar-visibility-probe` on `private aria-hidden measurement boxes under Toolbar` (`wireToolbarVisibility`): Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility.
+- `data-morph-preserve` on `private aria-hidden measurement boxes and visibility state children` (`wireToolbarVisibility`): Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them.
+- `data-toolbar-visibility-state` on `private hidden children of width-managed items and paired busy statuses` (`wireToolbarVisibility`): Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback.
+
+## 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; --kui-toolbar-inset controls outer padding and minimum height independently of --kui-toolbar-gap. 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-center-padding-inline`, `--kui-toolbar-divider-color`, `--kui-toolbar-inset`, `--kui-toolbar-leading-min-width`, `--kui-toolbar-leading-padding-inline`, `--kui-toolbar-trailing-gap`, `--kui-toolbar-trailing-justify`, `--kui-toolbar-trailing-justify-self`, `--kui-toolbar-trailing-padding-inline`, `--kui-toolbar-zone-padding-inline`. 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: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [PopupMenu](./popup-menu.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/tooltip.md

@@ -0,0 +1,81 @@
+# Tooltip
+
+<!-- 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:tooltip` · Kerf UI · CSS composition · Feedback
+
+Styling for kerfjs/overlay's tooltip(): the help tag's look (loud neutral fill, on-loud 14px text, 3px radius) for a hover and focus tooltip on any element, wrapping at 40 characters, with entrance and exit motion.
+
+## When to use
+
+Explain a control or value on hover and keyboard focus with a styled tooltip, without hand-written tooltip CSS.
+
+- A control or value needs a short explanation on hover and keyboard focus (a longer action description, a chart point, a truncated label): import @kerfjs/ui/overlay-tooltip.css once and call tooltip(anchor, content) from kerfjs/overlay with exitClass 'kui-tooltip-exit' and exitDuration 100.
+- The explanation has structure (a bold line over a detail): pass a render function; its content inherits the tooltip's colors.
+
+**Not when:**
+
+- Do not add a tooltip to an icon-only control in a ToolbarControlGroup, an icon-only Button, Select, or PopupMenu; @kerfjs/ui/help-tags-register already shows its help tag.
+- Do not put interactive content or the only copy of important information in a tooltip; use an AnchoredSurface or visible text.
+- Do not hand-write tooltip CSS or use wa-tooltip.
+
+**Alternatives:**
+
+- [AnchoredSurface](./anchored-surface.md) (nearest) — Use an AnchoredSurface for interactive or persistent help that the person opens.
+
+## Imports
+
+- CSS: import `@kerfjs/ui/overlay-tooltip.css` once.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- plain text tooltip, wrapped at 40 characters
+- structured content from a render function
+- any placement tooltip() supports (top by default)
+- native: true top-layer hosting
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** which elements get a tooltip and its content; placement, delay, and native top-layer hosting; the disposer that removes a tooltip's listeners.
+
+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.
+
+- tooltip() positions the wrapper beside its anchor; the stylesheet caps its width at 40 characters within the viewport.
+
+## Accessibility
+
+- tooltip() shows on hover and on keyboard focus, gives the wrapper role tooltip, and hides on leave or blur; keep the anchor's accessible name complete without it.
+- The loud neutral fill with on-loud text meets WCAG AA; forced colors draw CanvasText on Canvas, and the entrance is skipped under prefers-reduced-motion or the static-effects switch.
+
+## 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): `kerf-tooltip`, `kui-tooltip-exit`.
+
+Classes an application may place on its own elements: `kerf-tooltip`, `kui-tooltip-exit`.
+
+Public tokens it reads: `--kui-overlay-tooltip-z-index`. 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: [AnchoredSurface](./anchored-surface.md).
+- Docs: [`docs/overlay-tooltip.md`](../../docs/overlay-tooltip.md), [`docs/component-selection.md#web-awesome-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=tooltip`.

package/ai/components/value-table.md

@@ -0,0 +1,80 @@
+# 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.
+
+**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`.
+- 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
+- compact density
+- placeholder (loading)
+- minimum label column (labelWidth)
+- stacked presentation
+- stack below a compact or narrow table width
+
+## 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-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), [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-accordion-item.md

@@ -0,0 +1,61 @@
+# 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: avoid
+
+## When to use
+
+Ecosystem accordion item; use a Kerf Disclosure in a named group.
+
+- Experimental labeled disclosure section used by an accordion.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use Disclosure (@kerfjs/ui/disclosure), a native details element, and give Disclosures the same name for an accordion.
+
+**Alternatives:**
+
+- [Disclosure](./disclosure.md) (prefer-kerf) — Use Disclosure for show-and-hide content; Disclosures sharing a name form an accordion.
+
+## 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), [Disclosure](./disclosure.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=wa-accordion-item`.

package/ai/components/wa-accordion.md

@@ -0,0 +1,71 @@
+# 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: avoid
+
+## When to use
+
+Ecosystem accordion; use Kerf Disclosures sharing a name.
+
+- Coordinates one or more collapsible content sections.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use Disclosure (@kerfjs/ui/disclosure), a native details element, and give Disclosures the same name for an accordion.
+
+**Alternatives:**
+
+- [Disclosure](./disclosure.md) (prefer-kerf) — Use Disclosure for show-and-hide content; Disclosures sharing a name form an accordion.
+
+## 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), [Disclosure](./disclosure.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=wa-accordion`.

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

@@ -0,0 +1,56 @@
+# 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.
+- Use it only in an application that has adopted the optional Web Awesome integration (registration imports plus @kerfjs/ui/webawesome.css); a Kerf-only application uses a Kerf component or a native element instead.
+
+## 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-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=wa-animated-image`.

package/ai/components/wa-animation.md

@@ -0,0 +1,56 @@
+# Animation
+
+<!-- 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-animation` · Web Awesome · component · Helpers · recommendation: supported
+
+## When to use
+
+Declarative Web Animations API wrapper with preset effects.
+
+**Not when:**
+
+- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Use it only in an application that has adopted the optional Web Awesome integration (registration imports plus @kerfjs/ui/webawesome.css); a Kerf-only application uses a Kerf component or a native element instead.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/animation/animation.js` once (a side effect).
+- Custom element: `<wa-animation>`.
+- 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: [Select](./select.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: child · padding: child (layout role: helpers). `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: [Select](./select.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-animation`.

package/ai/components/wa-avatar.md

@@ -0,0 +1,56 @@
+# Avatar
+
+<!-- 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-avatar` · Web Awesome · component · Media · recommendation: supported
+
+## When to use
+
+Person or entity image with initials fallback.
+
+**Not when:**
+
+- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Use it only in an application that has adopted the optional Web Awesome integration (registration imports plus @kerfjs/ui/webawesome.css); a Kerf-only application uses a Kerf component or a native element instead.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/avatar/avatar.js` once (a side effect).
+- Custom element: `<wa-avatar>`.
+- 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).
+- UX catalog route: `?component=wa-avatar`.

package/ai/components/wa-badge.md

@@ -0,0 +1,62 @@
+# Badge
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:wa-badge` · Web Awesome · component · Feedback · recommendation: avoid
+
+## When to use
+
+Ecosystem badge; use Kerf Badge.
+
+- Compact status or count label with semantic variants.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use Badge for compact status, count, or category metadata.
+
+**Alternatives:**
+
+- [Badge](./badge.md) (prefer-kerf) — Use Badge for compact status, count, or category metadata.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/badge/badge.js` once (a side effect).
+- Custom element: `<wa-badge>`.
+- 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.
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · 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
+
+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-badge-accent-foreground`, `--kui-wa-badge-filled-background`, `--kui-wa-badge-filled-foreground`. Set a token only where its public contract allows; prefer a prop.
+
+## Related
+
+- Components: [Badge](./badge.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-badge`.