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

package/ai/components/wa-drawer.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-drawer` · Web Awesome · component · Layout · recommendation: supported
+`@kerfjs/ui:wa-drawer` · Web Awesome · component · Layout · recommendation: avoid
 
 ## When to use
 
-Edge-anchored modal surface for navigation or secondary tasks.
+Ecosystem drawer; use Kerf DialogSurface sheets or CollapsiblePanel.
+
+- Edge-anchored modal surface for navigation or secondary tasks.
 
 **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 DialogSurface with presentation="side-sheet" or "bottom-sheet" for a modal edge surface, or CollapsiblePanel for a rail that becomes an overlay on compact devices.
+
+**Alternatives:**
+
+- [Surface Scaffolds](./surface-scaffold.md) (prefer-kerf) — Use DialogSurface with presentation="side-sheet" or "bottom-sheet" for a modal edge surface.
+- [CollapsiblePanel](./collapsible-panel.md) (prefer-kerf) — Use CollapsiblePanel for a collapsible rail or drawer that overlays content on compact devices.
 
 ## Imports
 
@@ -50,6 +57,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Button](./wa-button.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- Components: [Button](./wa-button.md), [Surface Scaffolds](./surface-scaffold.md), [CollapsiblePanel](./collapsible-panel.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-drawer`.

package/ai/components/wa-dropdown-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-dropdown-item` · Web Awesome · component · Actions · recommendation: conditional
+`@kerfjs/ui:wa-dropdown-item` · Web Awesome · component · Actions · recommendation: avoid
 
 ## When to use
 
-Action-menu row; prefer Kerf Select options for value selection.
+Ecosystem action-menu row; use Kerf PopupMenu items or Select choices.
+
+- Action-menu row; prefer Kerf Select options for value selection.
 
 **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 PopupMenu items for commands and Select choices for values.
 
 **Alternatives:**
 
-- [PopupMenu](./popup-menu.md) (prefer-kerf)
-- [Select](./select.md) (prefer-kerf)
+- [PopupMenu](./popup-menu.md) (prefer-kerf) — Use PopupMenu items for commands and Select choices for values.
+- [Select](./select.md) (prefer-kerf) — Use PopupMenu items for commands and Select choices for values.
 
 ## Imports
 
@@ -56,5 +58,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [Icon](./wa-icon.md), [PopupMenu](./popup-menu.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-dropdown-item`.

package/ai/components/wa-dropdown.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-dropdown` · Web Awesome · component · Actions · recommendation: conditional
+`@kerfjs/ui:wa-dropdown` · Web Awesome · component · Actions · recommendation: avoid
 
 ## When to use
 
-Action-menu primitive; prefer Kerf Select when choosing a value.
+Ecosystem action menu; use Kerf PopupMenu, or Select when choosing a value.
+
+- Action-menu primitive; prefer Kerf Select when choosing a value.
 
 **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 PopupMenu for a command menu and Select for a value.
 
 **Alternatives:**
 
-- [PopupMenu](./popup-menu.md) (prefer-kerf)
-- [Select](./select.md) (prefer-kerf)
+- [PopupMenu](./popup-menu.md) (prefer-kerf) — Use PopupMenu for a command menu and Select for a value.
+- [Select](./select.md) (prefer-kerf) — Use PopupMenu for a command menu and Select for a value.
 
 ## Imports
 
@@ -56,5 +58,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [Dropdown Item](./wa-dropdown-item.md), [Popup](./wa-popup.md), [PopupMenu](./popup-menu.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-dropdown`.

package/ai/components/wa-format-bytes.md

@@ -11,6 +11,7 @@ Locale-aware byte and bit value formatter.
 **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-format-date.md

@@ -11,6 +11,7 @@ Locale-aware date and time formatter.
 **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-format-number.md

@@ -11,6 +11,7 @@ Locale-aware number, currency, unit, and percentage formatter.
 **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-icon.md

@@ -11,6 +11,7 @@ Ecosystem icon renderer; use Kerf LucideIcon in application UI.
 **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.
 
 **Alternatives:**
 
@@ -54,5 +55,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [LucideIcon](./lucide-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).
+- 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-icon`.

package/ai/components/wa-include.md

@@ -2,15 +2,17 @@
 
 <!-- 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-include` · Web Awesome · component · Helpers · recommendation: supported
+`@kerfjs/ui:wa-include` · Web Awesome · component · Helpers · recommendation: avoid
 
 ## When to use
 
-Loads and injects an external HTML fragment.
+Ecosystem remote HTML include; fetch with kerfjs/async and render Kerf content.
+
+- Loads and injects an external HTML fragment.
 
 **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: it injects fetched markup outside kerf's SafeHtml escaping. Fetch with resource() from kerfjs/async and render the result as Kerf content.
 
 ## Imports
 
@@ -49,5 +51,5 @@ 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).
+- 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-include`.

package/ai/components/wa-input.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-input` · Web Awesome · component · Forms · recommendation: supported
+`@kerfjs/ui:wa-input` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Text input with labels, hints, clear controls, and semantic appearances.
+Ecosystem text input; use Kerf TextField.
+
+- Text input with labels, hints, clear controls, and semantic appearances.
 
 **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 for free text; use SearchField only when text and ordered filter tokens form one editor.
 
 **Alternatives:**
 
-- [TokenSearchField](./token-search-field.md) (prefer-kerf)
+- [TextField](./text-field.md) (prefer-kerf) — Use TextField for free text; use SearchField only when text and ordered filter tokens form one editor.
+- [SearchField](./search-field.md) (prefer-kerf) — Use TextField for free text; use SearchField only when text and ordered filter tokens form one editor.
 
 ## Imports
 
@@ -54,6 +57,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Icon](./wa-icon.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: [Icon](./wa-icon.md), [TextField](./text-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-input`.

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

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

package/ai/components/wa-known-date.md

@@ -11,6 +11,7 @@ Experimental segmented field for partially or fully known dates.
 **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-markdown.md

@@ -11,6 +11,7 @@ Experimental renderer for trusted Markdown 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
 

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

@@ -11,6 +11,7 @@ Declaratively emits DOM mutation records 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
 

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

@@ -11,6 +11,7 @@ Numeric input with keyboard and stepper controls.
 **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-option.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-option` · Web Awesome · component · Forms · recommendation: underlying
+`@kerfjs/ui:wa-option` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Underlying ecosystem option; prefer choices passed to Kerf Select.
+Ecosystem select option; use Kerf Select choices.
+
+- Underlying ecosystem option; prefer choices passed to Kerf Select.
 
 **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; pass choices to Select.
 
 **Alternatives:**
 
-- [Select](./select.md) (prefer-kerf)
+- [Select](./select.md) (prefer-kerf) — Pass choices to Select.
 
 ## Imports
 
@@ -55,5 +57,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [Icon](./wa-icon.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-option`.

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

@@ -11,6 +11,7 @@ Experimental segmented one-time-password input.
 **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-page.md

@@ -2,15 +2,23 @@
 
 <!-- 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-page` · Web Awesome · component · Layout · recommendation: supported
+`@kerfjs/ui:wa-page` · Web Awesome · component · Layout · recommendation: avoid
 
 ## When to use
 
-Responsive application shell with navigation, banner, and main slots.
+Ecosystem page shell; use the Kerf app layouts.
+
+- Responsive application shell with navigation, banner, and main slots.
 
 **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 Workbench, SplitView, NavStack, or TabNavigator for the application shell.
+
+**Alternatives:**
+
+- [Workbench](./workbench.md) (prefer-kerf) — Use Workbench for a desktop-class workspace with collapsible rails.
+- [SplitView](./split-view.md) (prefer-kerf) — Use SplitView for a responsive list-detail shell.
+- [NavStack](./nav-stack.md) (prefer-kerf) — Use NavStack for a one-pane push and pop shell.
 
 ## Imports
 
@@ -49,5 +57,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: [Workbench](./workbench.md), [SplitView](./split-view.md), [NavStack](./nav-stack.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-page`.

package/ai/components/wa-pagination.md

@@ -11,6 +11,7 @@ Experimental page navigation for a bounded result set.
 **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-popover.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-popover` · Web Awesome · component · Helpers · recommendation: supported
+`@kerfjs/ui:wa-popover` · Web Awesome · component · Helpers · recommendation: avoid
 
 ## When to use
 
-Anchored non-modal surface built on popup positioning.
+Ecosystem popover; use Kerf AnchoredSurface.
+
+- Anchored non-modal surface built on popup positioning.
 
 **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 AnchoredSurface (openAnchoredSurface or openAnchoredSurfaceAt) for interactive help or popup content beside a control.
+
+**Alternatives:**
+
+- [AnchoredSurface](./anchored-surface.md) (prefer-kerf) — Use AnchoredSurface for a styled non-modal surface anchored to a control or the pointer.
 
 ## Imports
 
@@ -50,6 +56,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Popup](./wa-popup.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- Components: [Popup](./wa-popup.md), [AnchoredSurface](./anchored-surface.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-popover`.

package/ai/components/wa-popup.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-popup` · Web Awesome · component · Helpers · recommendation: conditional
+`@kerfjs/ui:wa-popup` · Web Awesome · component · Helpers · recommendation: avoid
 
 ## When to use
 
-Preferred low-level anchored positioning when Tooltip or Popover do not fit.
+Ecosystem positioning primitive; use Kerf AnchoredSurface or kerfjs/overlay positioning.
+
+- Preferred low-level anchored positioning when Tooltip or Popover do not fit.
 
 **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 AnchoredSurface for an anchored surface, or positionAnchored and autoReposition from kerfjs/overlay to place an application-owned element.
+
+**Alternatives:**
+
+- [AnchoredSurface](./anchored-surface.md) (prefer-kerf) — Use AnchoredSurface for an anchored surface; use positionAnchored or autoReposition from kerfjs/overlay for bare positioning.
 
 ## Imports
 
@@ -49,5 +55,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), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- Components: [AnchoredSurface](./anchored-surface.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-popup`.

package/ai/components/wa-progress-bar.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-progress-bar` · Web Awesome · component · Feedback · recommendation: supported
+`@kerfjs/ui:wa-progress-bar` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-Linear indicator for determinate or indeterminate progress.
+Ecosystem progress bar; use the Kerf ProgressBar.
+
+- Linear indicator for determinate or indeterminate progress.
 
 **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 ProgressBar (@kerfjs/ui/progress-bar).
+
+**Alternatives:**
+
+- [ProgressBar](./progress-bar.md) (prefer-kerf) — Use the Kerf component for determinate or indeterminate progress.
 
 ## Imports
 
@@ -49,5 +55,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: [ProgressBar](./progress-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-progress-bar`.

package/ai/components/wa-progress-ring.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-progress-ring` · Web Awesome · component · Feedback · recommendation: supported
+`@kerfjs/ui:wa-progress-ring` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-Circular indicator for determinate or indeterminate progress.
+Ecosystem progress ring; use the Kerf ProgressRing.
+
+- Circular indicator for determinate or indeterminate progress.
 
 **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 ProgressRing (@kerfjs/ui/progress-ring).
+
+**Alternatives:**
+
+- [ProgressRing](./progress-ring.md) (prefer-kerf) — Use the Kerf component for determinate or indeterminate progress.
 
 ## Imports
 
@@ -49,5 +55,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: [ProgressRing](./progress-ring.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-progress-ring`.

package/ai/components/wa-qr-code.md

@@ -11,6 +11,7 @@ Scannable QR representation of a supplied value.
 **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-radio-group.md

@@ -2,15 +2,23 @@
 
 <!-- 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-radio-group` · Web Awesome · component · Forms · recommendation: supported
+`@kerfjs/ui:wa-radio-group` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Labels and manages a mutually exclusive set of radios.
+Ecosystem radio group; use Kerf RadioGroup, ChoiceChips, or SegmentedControl.
+
+- Labels and manages a mutually exclusive set of radios.
 
 **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 RadioGroup for a few labeled options, ChoiceChips for wrapping pills, and SegmentedControl for a view switch.
+
+**Alternatives:**
+
+- [RadioGroup](./radio-group.md) (prefer-kerf) — Use RadioGroup for a few labeled options, ChoiceChips for wrapping pills, and SegmentedControl for a view switch.
+- [ChoiceChips](./choice-chips.md) (prefer-kerf) — Use RadioGroup for a few labeled options, ChoiceChips for wrapping pills, and SegmentedControl for a view switch.
+- [SegmentedControl](./segmented-control.md) (prefer-kerf) — Use RadioGroup for a few labeled options, ChoiceChips for wrapping pills, and SegmentedControl for a view switch.
 
 ## Imports
 
@@ -54,6 +62,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Radio](./wa-radio.md).
+- Components: [Radio](./wa-radio.md), [RadioGroup](./radio-group.md), [ChoiceChips](./choice-chips.md), [SegmentedControl](./segmented-control.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-radio-group`.

package/ai/components/wa-radio.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-radio` · Web Awesome · component · Forms · recommendation: supported
+`@kerfjs/ui:wa-radio` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Single-choice control used inside a radio group.
+Ecosystem radio; use Kerf RadioGroup choices.
+
+- Single-choice control used inside a radio group.
 
 **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 RadioGroup with a choices array.
+
+**Alternatives:**
+
+- [RadioGroup](./radio-group.md) (prefer-kerf) — Use RadioGroup with a choices array.
 
 ## Imports
 
@@ -50,6 +56,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Icon](./wa-icon.md).
+- Components: [Icon](./wa-icon.md), [RadioGroup](./radio-group.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-radio`.

package/ai/components/wa-random-content.md

@@ -11,6 +11,7 @@ Experimental helper that selects one slotted item at random.
 **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-rating.md

@@ -11,6 +11,7 @@ Interactive rating control with accessible labeling.
 **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-relative-time.md

@@ -11,6 +11,7 @@ Locale-aware human description of a date relative to now.
 **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-resize-observer.md

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