@kerfjs/ui 5.0.0-beta.103 → 5.0.0-beta.105

package/ai/components/wa-scroller.md

@@ -2,15 +2,22 @@
 
 <!-- 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: supported
+`@kerfjs/ui:wa-scroller` · Web Awesome · component · Layout · recommendation: avoid
 
 ## When to use
 
-Overflow container with accessible scrolling affordances.
+Ecosystem scroll container; use Kerf Pane scroll edges or ColumnTrack.
+
+- Overflow container with accessible scrolling affordances.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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
 
@@ -49,5 +56,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- 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

@@ -2,19 +2,21 @@
 
 <!-- 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: underlying
+`@kerfjs/ui:wa-select` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Underlying ecosystem field; prefer Kerf Select for app UI.
+Ecosystem select field; use Kerf Select.
+
+- Underlying ecosystem field; prefer Kerf Select for app UI.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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)
+- [Select](./select.md) (prefer-kerf) — Use Select; it is a native Kerf control and needs no Web Awesome registration.
 
 ## Imports
 
@@ -59,5 +61,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## 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-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- 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

@@ -2,15 +2,21 @@
 
 <!-- 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: supported
+`@kerfjs/ui:wa-skeleton` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-Placeholder shape for content that is still loading.
+Ecosystem placeholder; use Kerf Skeleton.
+
+- Placeholder shape for content that is still loading.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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
 
@@ -49,5 +55,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## 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

@@ -2,15 +2,21 @@
 
 <!-- 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: supported
+`@kerfjs/ui:wa-slider` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Range input with markers and value tooltip support.
+Ecosystem range slider; use the Kerf Slider.
+
+- Range input with markers and value tooltip support.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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
 
@@ -50,6 +56,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Tooltip](./wa-tooltip.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- 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

@@ -2,19 +2,21 @@
 
 <!-- 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: supported
+`@kerfjs/ui:wa-spinner` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-Compact indeterminate activity indicator.
+Ecosystem spinner; use Kerf LoadingSpinner.
+
+- Compact indeterminate activity indicator.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Do not use it in Kerf UI; use LoadingSpinner for indeterminate activity.
 
 **Alternatives:**
 
-- [LoadingSpinner](./loading-spinner.md) (prefer-kerf)
+- [LoadingSpinner](./loading-spinner.md) (prefer-kerf) — Use LoadingSpinner for indeterminate activity.
 
 ## Imports
 
@@ -54,5 +56,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [LoadingSpinner](./loading-spinner.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).
+- 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

@@ -2,19 +2,21 @@
 
 <!-- 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: conditional
+`@kerfjs/ui:wa-split-panel` · Web Awesome · component · Layout · recommendation: avoid
 
 ## When to use
 
-Alternative split API; prefer Kerf ResizableRegion for application panes.
+Alternative split API; use Kerf ResizableRegion for application panes.
+
+- Alternative split API; prefer Kerf ResizableRegion for application panes.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Do not use it in Kerf UI; use ResizableRegion for application panes.
 
 **Alternatives:**
 
-- [ResizableRegion](./resize.md) (prefer-kerf)
+- [ResizableRegion](./resize.md) (prefer-kerf) — Use ResizableRegion for application panes.
 
 ## Imports
 
@@ -54,5 +56,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [ResizableRegion](./resize.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).
+- 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

@@ -2,15 +2,21 @@
 
 <!-- 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: supported
+`@kerfjs/ui:wa-switch` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Immediate on/off setting control.
+Ecosystem switch; use Kerf Switch.
+
+- Immediate on/off setting control.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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
 
@@ -49,5 +55,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## 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

@@ -2,20 +2,22 @@
 
 <!-- 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: conditional
+`@kerfjs/ui:wa-tab-group` · Web Awesome · component · Navigation · recommendation: avoid
 
 ## When to use
 
-Ecosystem tabs; prefer Kerf TabBar or SegmentedControl.
+Ecosystem tabs; use Kerf TabBar or SegmentedControl.
+
+- Ecosystem tabs; prefer Kerf TabBar or SegmentedControl.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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)
-- [SegmentedControl](./segmented-control.md) (prefer-kerf)
+- [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
 
@@ -65,5 +67,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## 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-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- 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`.

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

@@ -2,19 +2,21 @@
 
 <!-- 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: conditional
+`@kerfjs/ui:wa-tab-panel` · Web Awesome · component · Navigation · recommendation: avoid
 
 ## When to use
 
-Ecosystem tab panel; prefer app-owned panels with Kerf navigation.
+Ecosystem tab panel; use Kerf TabBar with application-owned panels.
+
+- Ecosystem tab panel; prefer app-owned panels with Kerf navigation.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Do not use it in Kerf UI; use TabBar; the application owns its panels.
 
 **Alternatives:**
 
-- [TabBar](./tab-bar.md) (prefer-kerf)
+- [TabBar](./tab-bar.md) (prefer-kerf) — Use TabBar; the application owns its panels.
 
 ## Imports
 
@@ -56,5 +58,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [TabBar](./tab-bar.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).
+- 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

@@ -2,20 +2,22 @@
 
 <!-- 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: conditional
+`@kerfjs/ui:wa-tab` · Web Awesome · component · Navigation · recommendation: avoid
 
 ## When to use
 
-Ecosystem tab label; prefer Kerf TabBar or SegmentedControl.
+Ecosystem tab label; use Kerf TabBar or SegmentedControl.
+
+- Ecosystem tab label; prefer Kerf TabBar or SegmentedControl.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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)
-- [SegmentedControl](./segmented-control.md) (prefer-kerf)
+- [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
 
@@ -55,5 +57,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## 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-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- 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

@@ -2,19 +2,22 @@
 
 <!-- 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: supported
+`@kerfjs/ui:wa-tag` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-Compact categorization label with optional removal action.
+Ecosystem tag; use Kerf Chip.
+
+- Compact categorization label with optional removal action.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Do not use it in Kerf UI; use Chip for a removable or disabled tag.
 
 **Alternatives:**
 
-- [TokenSearchField](./token-search-field.md) (prefer-kerf)
+- [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
 
@@ -54,6 +57,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Button](./wa-button.md), [TokenSearchField](./token-search-field.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).
+- 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

@@ -2,15 +2,21 @@
 
 <!-- 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: supported
+`@kerfjs/ui:wa-textarea` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Multiline text field with labels, hints, and resize behavior.
+Ecosystem multi-line input; use Kerf TextField with multiline.
+
+- Multiline text field with labels, hints, and resize behavior.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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
 
@@ -49,5 +55,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## 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

@@ -11,6 +11,7 @@ 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
 

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

@@ -2,20 +2,22 @@
 
 <!-- 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: supported
+`@kerfjs/ui:wa-toast-item` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-One dismissible notification inside a toast stack.
+Ecosystem toast item; use kerfjs/overlay toast() with @kerfjs/ui/overlay-toast.css.
+
+- One dismissible notification inside a toast stack.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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:**
 
-- [StateBanner](./state-banner.md) (prefer-kerf)
-- [EmptyState](./empty-state.md) (prefer-kerf)
+- [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
 
@@ -55,6 +57,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Icon](./wa-icon.md), [Progress Ring](./wa-progress-ring.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.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).
+- 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`.