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

package/ai/components/wa-tab-panel.md

@@ -0,0 +1,62 @@
+# Tab Panel
+
+<!-- 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-tab-panel` · Web Awesome · component · Navigation · recommendation: avoid
+
+## When to use
+
+Ecosystem tab panel; use Kerf TabBar with application-owned panels.
+
+- Ecosystem tab panel; prefer app-owned panels with Kerf navigation.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use TabBar; the application owns its panels.
+
+**Alternatives:**
+
+- [TabBar](./tab-bar.md) (prefer-kerf) — Use TabBar; the application owns its panels.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/tab-panel/tab-panel.js` once (a side effect).
+- Custom element: `<wa-tab-panel>`.
+- 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: conditional (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Container-mode tab panels own the themed container inset; uncontained panels do not.
+
+## 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: [TabBar](./tab-bar.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-tab-panel`.

package/ai/components/wa-tab.md

@@ -0,0 +1,61 @@
+# Tab
+
+<!-- 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-tab` · Web Awesome · component · Navigation · recommendation: avoid
+
+## When to use
+
+Ecosystem tab label; use Kerf TabBar or SegmentedControl.
+
+- Ecosystem tab label; prefer Kerf TabBar or SegmentedControl.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use TabBar for application tabs or SegmentedControl for compact local views.
+
+**Alternatives:**
+
+- [TabBar](./tab-bar.md) (prefer-kerf) — Use TabBar for application tabs or SegmentedControl for compact local views.
+- [SegmentedControl](./segmented-control.md) (prefer-kerf) — Use TabBar for application tabs or SegmentedControl for compact local views.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/tab/tab.js` once (a side effect).
+- Custom element: `<wa-tab>`.
+- 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: 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
+
+- Components: [TabBar](./tab-bar.md), [SegmentedControl](./segmented-control.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-tab`.

package/ai/components/wa-tag-input.md

@@ -0,0 +1,62 @@
+# Tag Input
+
+<!-- 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-tag-input` · Web Awesome · component · Forms · recommendation: avoid
+
+## When to use
+
+Ecosystem tag input; use the Kerf TagField.
+
+- Only inside an application that has already adopted the optional Web Awesome integration.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use TagField (@kerfjs/ui/tag-field) with wireTagFields for tags submitted as form values, or SearchField for search filters.
+
+**Alternatives:**
+
+- [TagField](./tag-field.md) (prefer-kerf) — Use TagField for a list of short values submitted as form values.
+- [SearchField](./search-field.md) (prefer-kerf) — Use SearchField when the tags are search filters.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/tag-input/tag-input.js` once (a side effect).
+- Custom element: `<wa-tag-input>`.
+- 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), [Tag](./wa-tag.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: forms). `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), [Tag](./wa-tag.md), [TagField](./tag-field.md), [SearchField](./search-field.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-tag-input`.

package/ai/components/wa-tag.md

@@ -0,0 +1,62 @@
+# Tag
+
+<!-- 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-tag` · Web Awesome · component · Feedback · recommendation: avoid
+
+## When to use
+
+Ecosystem tag; use Kerf Chip.
+
+- Compact categorization label with optional removal action.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use Chip for a removable or disabled tag.
+
+**Alternatives:**
+
+- [Chip](./chip.md) (prefer-kerf) — Use Chip for a removable or disabled tag.
+- [SearchField](./search-field.md) (prefer-kerf) — Use Chip for a removable or disabled tag.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/tag/tag.js` once (a side effect).
+- Custom element: `<wa-tag>`.
+- 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: [Button](./wa-button.md).
+
+## 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`).
+
+## Related
+
+- Components: [Button](./wa-button.md), [Chip](./chip.md), [SearchField](./search-field.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-tag`.

package/ai/components/wa-textarea.md

@@ -0,0 +1,60 @@
+# Textarea
+
+<!-- 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-textarea` · Web Awesome · component · Forms · recommendation: avoid
+
+## When to use
+
+Ecosystem multi-line input; use Kerf TextField with multiline.
+
+- Multiline text field with labels, hints, and resize behavior.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use TextField with multiline for multi-line text.
+
+**Alternatives:**
+
+- [TextField](./text-field.md) (prefer-kerf) — Use TextField with multiline for multi-line text.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/textarea/textarea.js` once (a side effect).
+- Custom element: `<wa-textarea>`.
+- 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: forms). `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: [TextField](./text-field.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-textarea`.

package/ai/components/wa-time-input.md

@@ -0,0 +1,56 @@
+# Time Input
+
+<!-- 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-time-input` · Web Awesome · component · Forms · recommendation: supported
+
+## When to use
+
+Experimental segmented time field with an optional picker.
+
+**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/time-input/time-input.js` once (a side effect).
+- Custom element: `<wa-time-input>`.
+- 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), [Popup](./wa-popup.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: forms). `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), [Popup](./wa-popup.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-time-input`.

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

@@ -0,0 +1,62 @@
+# Toast 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-toast-item` · Web Awesome · component · Feedback · recommendation: avoid
+
+## When to use
+
+Ecosystem toast item; use kerfjs/overlay toast() with @kerfjs/ui/overlay-toast.css.
+
+- One dismissible notification inside a toast stack.
+
+**Not when:**
+
+- Do not use it in Kerf UI; call toast() from kerfjs/overlay with @kerfjs/ui/overlay-toast.css imported, which styles the region, tones, StateBanner content, and motion.
+
+**Alternatives:**
+
+- [Toast](./toast.md) (prefer-kerf) — Use kerfjs/overlay toast() styled by @kerfjs/ui/overlay-toast.css for a transient notification.
+- [StateBanner](./state-banner.md) (prefer-kerf) — Use a StateBanner in place for a persistent status tied to one surface.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/toast-item/toast-item.js` once (a side effect).
+- Custom element: `<wa-toast-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), [Progress Ring](./wa-progress-ring.md).
+
+## 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`).
+
+## Related
+
+- Components: [Icon](./wa-icon.md), [Progress Ring](./wa-progress-ring.md), [Toast](./toast.md), [StateBanner](./state-banner.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-toast-item`.

package/ai/components/wa-toast.md

@@ -0,0 +1,62 @@
+# Toast
+
+<!-- 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-toast` · Web Awesome · component · Feedback · recommendation: avoid
+
+## When to use
+
+Ecosystem toast stack; use kerfjs/overlay toast() with @kerfjs/ui/overlay-toast.css.
+
+- Placement-aware stack of transient notifications.
+
+**Not when:**
+
+- Do not use it in Kerf UI; call toast() from kerfjs/overlay with @kerfjs/ui/overlay-toast.css imported, which styles the region, tones, StateBanner content, and motion.
+
+**Alternatives:**
+
+- [Toast](./toast.md) (prefer-kerf) — Use kerfjs/overlay toast() styled by @kerfjs/ui/overlay-toast.css for a transient notification.
+- [StateBanner](./state-banner.md) (prefer-kerf) — Use a StateBanner in place for a persistent status tied to one surface.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/toast/toast.js` once (a side effect).
+- Custom element: `<wa-toast>`.
+- 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: [Toast Item](./wa-toast-item.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: child · padding: child (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`).
+
+## Related
+
+- Components: [Toast Item](./wa-toast-item.md), [Toast](./toast.md), [StateBanner](./state-banner.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-toast`.

package/ai/components/wa-tooltip.md

@@ -0,0 +1,61 @@
+# 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:wa-tooltip` · Web Awesome · component · Feedback · recommendation: avoid
+
+## When to use
+
+Ecosystem tooltip; use kerfjs/overlay tooltip() with @kerfjs/ui/overlay-tooltip.css.
+
+- Brief contextual label anchored to a control.
+
+**Not when:**
+
+- Do not use it in Kerf UI; call tooltip() from kerfjs/overlay with @kerfjs/ui/overlay-tooltip.css imported. Icon-only Kerf controls already get help tags.
+
+**Alternatives:**
+
+- [Tooltip](./tooltip.md) (prefer-kerf) — Use kerfjs/overlay tooltip() styled by @kerfjs/ui/overlay-tooltip.css for a hover and focus tooltip.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/tooltip/tooltip.js` once (a side effect).
+- Custom element: `<wa-tooltip>`.
+- 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: [Popup](./wa-popup.md).
+
+## 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`).
+
+## Related
+
+- Components: [Popup](./wa-popup.md), [Tooltip](./tooltip.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-tooltip`.

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

@@ -0,0 +1,56 @@
+# Tree 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-tree-item` · Web Awesome · component · Navigation · recommendation: exceptional
+
+## When to use
+
+Specialized tree row; use only as part of a required tree.
+
+**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/tree-item/tree-item.js` once (a side effect).
+- Custom element: `<wa-tree-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: [Checkbox](./wa-checkbox.md), [Icon](./wa-icon.md), [Spinner](./wa-spinner.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (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
+
+- Components: [Checkbox](./wa-checkbox.md), [Icon](./wa-icon.md), [Spinner](./wa-spinner.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-tree-item`.

package/ai/components/wa-tree.md

@@ -0,0 +1,56 @@
+# Tree
+
+<!-- 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-tree` · Web Awesome · component · Navigation · recommendation: exceptional
+
+## When to use
+
+Specialized hierarchy; use only when the product requires tree behavior.
+
+**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/tree/tree.js` once (a side effect).
+- Custom element: `<wa-tree>`.
+- 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: [Tree Item](./wa-tree-item.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: child · padding: child (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
+
+- Components: [Tree Item](./wa-tree-item.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-tree`.