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

package/ai/components/wa-resize-observer.md

@@ -0,0 +1,54 @@
+# Resize Observer
+
+<!-- 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-resize-observer` · Web Awesome · component · Helpers · recommendation: supported
+
+## When to use
+
+Declaratively emits size changes for slotted content.
+
+**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/resize-observer/resize-observer.js` once (a side effect).
+- Custom element: `<wa-resize-observer>`.
+- 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: 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
+
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-resize-observer`.

package/ai/components/wa-scroller.md

@@ -0,0 +1,61 @@
+# Scroller
+
+<!-- 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-scroller` · Web Awesome · component · Layout · recommendation: avoid
+
+## When to use
+
+Ecosystem scroll container; use Kerf Pane scroll edges or ColumnTrack.
+
+- Overflow container with accessible scrolling affordances.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use a Pane's scroll edges (or wireScrollDividers) for vertical overflow and ColumnTrack for a horizontal track.
+
+**Alternatives:**
+
+- [Pane](./pane.md) (prefer-kerf) — Use a Pane's scrollEdge and wireScrollDividers to signal vertical overflow.
+- [ColumnTrack](./column-track.md) (prefer-kerf) — Use ColumnTrack for a horizontally scrolling track of columns.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/scroller/scroller.js` once (a side effect).
+- Custom element: `<wa-scroller>`.
+- 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: child · padding: child (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: [Pane](./pane.md), [ColumnTrack](./column-track.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-scroller`.

package/ai/components/wa-select.md

@@ -0,0 +1,65 @@
+# Select
+
+<!-- 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-select` · Web Awesome · component · Forms · recommendation: avoid
+
+## When to use
+
+Ecosystem select field; use Kerf Select.
+
+- Underlying ecosystem field; prefer Kerf Select for app UI.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use Select; it is a native Kerf control and needs no Web Awesome registration.
+
+**Alternatives:**
+
+- [Select](./select.md) (prefer-kerf) — Use Select; it is a native Kerf control and needs no Web Awesome registration.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/select/select.js` once (a side effect).
+- Custom element: `<wa-select>`.
+- 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: only [Option](./wa-option.md) (required: [Option](./wa-option.md)).
+- Built from: [Icon](./wa-icon.md), [Popup](./wa-popup.md), [Tag](./wa-tag.md), [Option](./wa-option.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `options` — no declared JSX prop; accepts [Option](./wa-option.md); at least 1.
+
+## 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), [Tag](./wa-tag.md), [Option](./wa-option.md), [Select](./select.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-select`.

package/ai/components/wa-skeleton.md

@@ -0,0 +1,60 @@
+# Skeleton
+
+<!-- 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-skeleton` · Web Awesome · component · Feedback · recommendation: avoid
+
+## When to use
+
+Ecosystem placeholder; use Kerf Skeleton.
+
+- Placeholder shape for content that is still loading.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use Skeleton for a loading placeholder.
+
+**Alternatives:**
+
+- [Skeleton](./skeleton.md) (prefer-kerf) — Use Skeleton for a loading placeholder.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/skeleton/skeleton.js` once (a side effect).
+- Custom element: `<wa-skeleton>`.
+- 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: 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: [Skeleton](./skeleton.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-skeleton`.

package/ai/components/wa-slider.md

@@ -0,0 +1,61 @@
+# Slider
+
+<!-- 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-slider` · Web Awesome · component · Forms · recommendation: avoid
+
+## When to use
+
+Ecosystem range slider; use the Kerf Slider.
+
+- Range input with markers and value tooltip support.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use Slider (@kerfjs/ui/slider), a native range input, with wireSliders for the live readout.
+
+**Alternatives:**
+
+- [Slider](./slider.md) (prefer-kerf) — Use the Kerf Slider for a value on a range.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/slider/slider.js` once (a side effect).
+- Custom element: `<wa-slider>`.
+- 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: [Tooltip](./wa-tooltip.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: none · padding: child (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: [Tooltip](./wa-tooltip.md), [Slider](./slider.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-slider`.

package/ai/components/wa-spinner.md

@@ -0,0 +1,60 @@
+# Spinner
+
+<!-- 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-spinner` · Web Awesome · component · Feedback · recommendation: avoid
+
+## When to use
+
+Ecosystem spinner; use Kerf LoadingSpinner.
+
+- Compact indeterminate activity indicator.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use LoadingSpinner for indeterminate activity.
+
+**Alternatives:**
+
+- [LoadingSpinner](./loading-spinner.md) (prefer-kerf) — Use LoadingSpinner for indeterminate activity.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/spinner/spinner.js` once (a side effect).
+- Custom element: `<wa-spinner>`.
+- 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: 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: [LoadingSpinner](./loading-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-spinner`.

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

@@ -0,0 +1,60 @@
+# Split 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-split-panel` · Web Awesome · component · Layout · recommendation: avoid
+
+## When to use
+
+Alternative split API; use Kerf ResizableRegion for application panes.
+
+- Alternative split API; prefer Kerf ResizableRegion for application panes.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use ResizableRegion for application panes.
+
+**Alternatives:**
+
+- [ResizableRegion](./resize.md) (prefer-kerf) — Use ResizableRegion for application panes.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/split-panel/split-panel.js` once (a side effect).
+- Custom element: `<wa-split-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: child · padding: child (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: [ResizableRegion](./resize.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-split-panel`.

package/ai/components/wa-step.md

@@ -0,0 +1,56 @@
+# Step
+
+<!-- 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-step` · Web Awesome · component · Navigation · recommendation: supported
+
+## When to use
+
+Marker and label for one stage of a wa-stepper process, with completed, loading, disabled, and semantic-color states.
+
+**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/step/step.js` once (a side effect).
+- Custom element: `<wa-step>`.
+- 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), [Spinner](./wa-spinner.md).
+
+## 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
+
+- Components: [Icon](./wa-icon.md), [Spinner](./wa-spinner.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-step`.

package/ai/components/wa-stepper.md

@@ -0,0 +1,56 @@
+# Stepper
+
+<!-- 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-stepper` · Web Awesome · component · Navigation · recommendation: supported
+
+## When to use
+
+Ordered indicator for a multi-step process, such as checkout or setup, with optional step-by-step navigation.
+
+**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/stepper/stepper.js` once (a side effect).
+- Custom element: `<wa-stepper>`.
+- 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: [Step](./wa-step.md).
+
+## 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
+
+- Components: [Step](./wa-step.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-stepper`.

package/ai/components/wa-switch.md

@@ -0,0 +1,60 @@
+# Switch
+
+<!-- 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-switch` · Web Awesome · component · Forms · recommendation: avoid
+
+## When to use
+
+Ecosystem switch; use Kerf Switch.
+
+- Immediate on/off setting control.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use Switch for a setting that applies immediately.
+
+**Alternatives:**
+
+- [Switch](./switch.md) (prefer-kerf) — Use Switch for a setting that applies immediately.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/switch/switch.js` once (a side effect).
+- Custom element: `<wa-switch>`.
+- 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: [Switch](./switch.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-switch`.

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

@@ -0,0 +1,71 @@
+# Tab Group
+
+<!-- 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-group` · Web Awesome · component · Navigation · recommendation: avoid
+
+## When to use
+
+Ecosystem tabs; use Kerf TabBar or SegmentedControl.
+
+- Ecosystem tabs; 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-group/tab-group.js` once (a side effect).
+- Custom element: `<wa-tab-group>`.
+- 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: only [Tab](./wa-tab.md), [Tab Panel](./wa-tab-panel.md) (required: [Tab](./wa-tab.md), [Tab Panel](./wa-tab-panel.md)).
+- Built from: [Button](./wa-button.md), [Tab](./wa-tab.md), [Tab Panel](./wa-tab-panel.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `tabs` — no declared JSX prop; accepts [Tab](./wa-tab.md); at least 1.
+- `panels` — no declared JSX prop; accepts [Tab Panel](./wa-tab-panel.md); at least 1.
+
+## 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`).
+
+## Diagnostics
+
+- `KUI-C108` (error) when tab and panel name sets differ: Every wa-tab must identify a matching wa-tab-panel and vice versa.
+
+## Related
+
+- Components: [Button](./wa-button.md), [Tab](./wa-tab.md), [Tab Panel](./wa-tab-panel.md), [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-group`.