@kerfjs/ui 5.0.0-beta.9 → 5.0.0-beta.90

package/ai/components/toolbar-text.md

@@ -0,0 +1,98 @@
+# 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
+
+Extra-large through extra-small toolbar identity text.
+
+- Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics.
+- Use action for an editable toolbar title: it renders a native button that shrinks and ellipsizes beside sibling status chips.
+- Use tone=dark for title or filename text on a loud toolbar surface, matching dark ToolbarControlGroups.
+- 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 omit headingLevel when the text is the page or section heading.
+- Large, default, and small are intentionally quiet toolbar identity text in default tone. Use xlarge-fixed for a normal-color toolbar heading at the fixed font-l step; 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.
+- Wiring: `wireToolbarVisibility` from `@kerfjs/ui/wire-toolbar-visibility` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures-v1.md#kerfjsuitoolbar-text), [`@kerfjs/ui/wire-toolbar-visibility`](../public-api-signatures-v1.md#kerfjsuiwire-toolbar-visibility) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- xlarge
+- xlarge-fixed (fixed font-l heading)
+- large
+- default
+- small
+- xsmall
+- placeholder (loading)
+- dark (loud-surface foreground)
+- typed hideBelow/showBelow thresholds at the nearest Toolbar content width
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `hideBelow`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `hideBelow={px(416)}`
+- `showBelow`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `showBelow={px(416)}`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** text; responsive priority; the delegated action handler and display-to-input editing swap.
+
+**Wiring:** `wireToolbarVisibility` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `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: 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.
+- Actionable text is a native button with its full text as its accessible name; action cannot be combined with headingLevel, placeholder, or wrap.
+
+## 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-2xs`, `--kui-font-2xl`, `--kui-font-l`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-color-neutral-on-loud`. 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,101 @@
+# 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
+- 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
+- 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-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/value-table.md

@@ -0,0 +1,73 @@
+# 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
+- compact density
+- 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-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.
+
+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`.

package/ai/components/wa-animation.md

@@ -0,0 +1,55 @@
+# 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.
+
+## 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,55 @@
+# 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.
+
+## 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,55 @@
+# 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: supported
+
+## When to use
+
+Compact status or count label with semantic variants.
+
+**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/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
+
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-badge`.

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

@@ -0,0 +1,53 @@
+# Breadcrumb 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-breadcrumb-item` · Web Awesome · component · Navigation · recommendation: supported
+
+## When to use
+
+One link or current-location item in a breadcrumb.
+
+**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/breadcrumb-item/breadcrumb-item.js` once (a side effect).
+- Custom element: `<wa-breadcrumb-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.
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: navigation). `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
+
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-breadcrumb-item`.