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

package/ai/components/toolbar-control-group.md

@@ -29,7 +29,7 @@ Provide complete toolbar action geometry through configuration, including semant
 
 - [SegmentedControl](./segmented-control.md) (nearest)
 - [Button Group](./wa-button-group.md) (prefer-over)
-- [IconToggleButton](./icon-toggle-button.md) (nearest) — Outside a Toolbar, a standalone icon-only toggle is an IconToggleButton.
+- [Button](./button.md) (nearest) — Outside a Toolbar, a standalone icon-only toggle is an icon-only Button with pressed.
 
 ## Imports
 
@@ -101,7 +101,7 @@ Margin: none · border: self · padding: self (layout role: structure). `self` m
 
 - Name the group when its relationship is not evident from context.
 - A disabled native button (disabled, or aria-disabled="true" when it must stay focusable) dims to half opacity with the not-allowed cursor and no hover surface; a disabled raw wa-button paints no hover surface either. Do not add disabled styling yourself.
-- Name an icon-only button or link with aria-label, not title. Once any help-tag installer is imported (select/register, popup-menu/register, or help-tags/register), it shows an aria-hidden Web Awesome help tag repeating that name after a 500ms hover and at once on keyboard focus, hidden on a press and on Escape, and never joins aria-labelledby. A native title keeps the browser tooltip and gets no second tag.
+- Name an icon-only button or link with aria-label, not title. Once any help-tag installer is imported (select/register, popup-menu/register, or help-tags/register), it shows an aria-hidden help tag repeating that name after a 500ms hover and at once on keyboard focus, hidden on a press and on Escape, and never joins aria-labelledby. A native title keeps the browser tooltip and gets no second tag.
 - In an overlay Pane header (headerPresentation="overlay"), overlay NavStack chrome (chromePresentation="overlay") or bottom toolbar (bottomToolbarPresentation="overlay"), or a DialogSurface floating header's header-actions (headerPresentation="floating"), a default-tone group (not dark-toned, not an avatar scrim) takes --kui-color-text for its controls, so they keep WCAG AA over content passing beneath the translucent chrome material.
 - A dark-toned group's hover paints a 14% surface wash over its loud fill, on one control of a group or across a lone control's whole group, so the on-loud icon keeps at least 3:1 over a light page and well above it in dark.
 
@@ -121,6 +121,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md), [Button Group](./wa-button-group.md), [IconToggleButton](./icon-toggle-button.md).
+- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md), [Button Group](./wa-button-group.md), [Button](./button.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
 - UX catalog route: `?component=toolbar-control-group`.

package/ai/components/tooltip.md

@@ -0,0 +1,81 @@
+# 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:tooltip` · Kerf UI · CSS composition · Feedback
+
+Styling for kerfjs/overlay's tooltip(): the help tag's look (loud neutral fill, on-loud 14px text, 3px radius) for a hover and focus tooltip on any element, wrapping at 40 characters, with entrance and exit motion.
+
+## When to use
+
+Explain a control or value on hover and keyboard focus with a styled tooltip, without hand-written tooltip CSS.
+
+- A control or value needs a short explanation on hover and keyboard focus (a longer action description, a chart point, a truncated label): import @kerfjs/ui/overlay-tooltip.css once and call tooltip(anchor, content) from kerfjs/overlay with exitClass 'kui-tooltip-exit' and exitDuration 100.
+- The explanation has structure (a bold line over a detail): pass a render function; its content inherits the tooltip's colors.
+
+**Not when:**
+
+- Do not add a tooltip to an icon-only control in a ToolbarControlGroup, an icon-only Button, Select, or PopupMenu; @kerfjs/ui/help-tags-register already shows its help tag.
+- Do not put interactive content or the only copy of important information in a tooltip; use an AnchoredSurface or visible text.
+- Do not hand-write tooltip CSS or use wa-tooltip.
+
+**Alternatives:**
+
+- [AnchoredSurface](./anchored-surface.md) (nearest) — Use an AnchoredSurface for interactive or persistent help that the person opens.
+
+## Imports
+
+- CSS: import `@kerfjs/ui/overlay-tooltip.css` once.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- plain text tooltip, wrapped at 40 characters
+- structured content from a render function
+- any placement tooltip() supports (top by default)
+- native: true top-layer hosting
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** which elements get a tooltip and its content; placement, delay, and native top-layer hosting; the disposer that removes a tooltip's listeners.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- tooltip() positions the wrapper beside its anchor; the stylesheet caps its width at 40 characters within the viewport.
+
+## Accessibility
+
+- tooltip() shows on hover and on keyboard focus, gives the wrapper role tooltip, and hides on leave or blur; keep the anchor's accessible name complete without it.
+- The loud neutral fill with on-loud text meets WCAG AA; forced colors draw CanvasText on Canvas, and the entrance is skipped under prefers-reduced-motion or the static-effects switch.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kerf-tooltip`, `kui-tooltip-exit`.
+
+Classes an application may place on its own elements: `kerf-tooltip`, `kui-tooltip-exit`.
+
+Public tokens it reads: `--kui-overlay-tooltip-z-index`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [AnchoredSurface](./anchored-surface.md).
+- Docs: [`docs/overlay-tooltip.md`](../../docs/overlay-tooltip.md), [`docs/component-selection.md#web-awesome-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=tooltip`.

package/ai/components/wa-accordion-item.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-accordion-item` · Web Awesome · component · Layout · recommendation: supported
+`@kerfjs/ui:wa-accordion-item` · Web Awesome · component · Layout · recommendation: avoid
 
 ## When to use
 
-Experimental labeled disclosure section used by an accordion.
+Ecosystem accordion item; use a Kerf Disclosure in a named group.
+
+- Experimental labeled disclosure section used by an accordion.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Do not use it in Kerf UI; use Disclosure (@kerfjs/ui/disclosure), a native details element, and give Disclosures the same name for an accordion.
+
+**Alternatives:**
+
+- [Disclosure](./disclosure.md) (prefer-kerf) — Use Disclosure for show-and-hide content; Disclosures sharing a name form an accordion.
 
 ## 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).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- Components: [Icon](./wa-icon.md), [Disclosure](./disclosure.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-accordion-item`.

package/ai/components/wa-accordion.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-accordion` · Web Awesome · component · Layout · recommendation: supported
+`@kerfjs/ui:wa-accordion` · Web Awesome · component · Layout · recommendation: avoid
 
 ## When to use
 
-Coordinates one or more collapsible content sections.
+Ecosystem accordion; use Kerf Disclosures sharing a name.
+
+- Coordinates one or more collapsible content sections.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Do not use it in Kerf UI; use Disclosure (@kerfjs/ui/disclosure), a native details element, and give Disclosures the same name for an accordion.
+
+**Alternatives:**
+
+- [Disclosure](./disclosure.md) (prefer-kerf) — Use Disclosure for show-and-hide content; Disclosures sharing a name form an accordion.
 
 ## Imports
 
@@ -60,6 +66,6 @@ Public tokens it reads: `--kui-wa-surface-margin`, `--kui-wa-surface-inset`, `--
 
 ## Related
 
-- Components: [Accordion Item](./wa-accordion-item.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- Components: [Accordion Item](./wa-accordion-item.md), [Disclosure](./disclosure.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-accordion`.

package/ai/components/wa-animated-image.md

@@ -11,6 +11,7 @@ Specialized animated media; use only for a concrete product requirement.
 **Not when:**
 
 - Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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
 
@@ -51,5 +52,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [Icon](./wa-icon.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- 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-animated-image`.

package/ai/components/wa-animation.md

@@ -11,6 +11,7 @@ Declarative Web Animations API wrapper with preset effects.
 **Not when:**
 
 - Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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-avatar.md

@@ -11,6 +11,7 @@ Person or entity image with initials fallback.
 **Not when:**
 
 - Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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-badge.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-badge` · Web Awesome · component · Feedback · recommendation: supported
+`@kerfjs/ui:wa-badge` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-Compact status or count label with semantic variants.
+Ecosystem badge; use Kerf Badge.
+
+- Compact status or count label with semantic variants.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Do not use it in Kerf UI; use Badge for compact status, count, or category metadata.
+
+**Alternatives:**
+
+- [Badge](./badge.md) (prefer-kerf) — Use Badge for compact status, count, or category metadata.
 
 ## Imports
 
@@ -51,5 +57,6 @@ Public tokens it reads: `--kui-wa-badge-accent-foreground`, `--kui-wa-badge-fill
 
 ## Related
 
+- Components: [Badge](./badge.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-badge`.

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

@@ -11,6 +11,7 @@ One link or current-location item in a breadcrumb.
 **Not when:**
 
 - Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- 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-breadcrumb.md

@@ -11,6 +11,7 @@ Ordered navigation trail for the current location.
 **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-button-group.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-button-group` · Web Awesome · component · Actions · recommendation: conditional
+`@kerfjs/ui:wa-button-group` · Web Awesome · component · Actions · recommendation: avoid
 
 ## When to use
 
-Exceptional grouped actions; prefer Kerf SegmentedControl for exclusive choices.
+Ecosystem button group; use Kerf ToolbarControlGroup, SplitButton, or SegmentedControl.
+
+- Exceptional grouped actions; prefer Kerf SegmentedControl for exclusive choices.
 
 **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 ToolbarControlGroup or SplitButton for grouped actions and SegmentedControl for one-of-many choices.
 
 **Alternatives:**
 
@@ -56,5 +58,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [Button](./wa-button.md), [SegmentedControl](./segmented-control.md), [SplitButton](./split-button.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-button-group`.

package/ai/components/wa-button.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-button` · Web Awesome · component · Actions · recommendation: supported
+`@kerfjs/ui:wa-button` · Web Awesome · component · Actions · recommendation: avoid
 
 ## When to use
 
-Action control with semantic variants, appearances, loading, and icon support.
+Ecosystem action button; use Kerf Button.
+
+- Action control with semantic variants, appearances, loading, and icon 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 Button for a text, text-and-icon, or icon-only action.
 
 **Alternatives:**
 
-- [IconButton](./icon-button.md) (prefer-kerf) — For an icon-only button with a LucideIcon, use IconButton for Web Awesome's square icon-button geometry.
+- [Button](./button.md) (prefer-kerf) — Use Button for a text, text-and-icon, or icon-only action.
 
 ## Imports
 
@@ -54,6 +56,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Icon](./wa-icon.md), [Spinner](./wa-spinner.md), [IconButton](./icon-button.md).
+- Components: [Icon](./wa-icon.md), [Spinner](./wa-spinner.md), [Button](./button.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-button`.

package/ai/components/wa-callout.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-callout` · Web Awesome · component · Feedback · recommendation: supported
+`@kerfjs/ui:wa-callout` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-Prominent contextual message with semantic variants.
+Ecosystem callout; use Kerf StateBanner.
+
+- Prominent contextual message with semantic variants.
 
 **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 StateBanner for a persistent inline status, alert, or emphasized message.
 
 **Alternatives:**
 
-- [StateBanner](./state-banner.md) (prefer-kerf)
+- [StateBanner](./state-banner.md) (prefer-kerf) — Use StateBanner for a persistent inline status, alert, or emphasized message.
 
 ## Imports
 
@@ -54,5 +56,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [StateBanner](./state-banner.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-callout`.

package/ai/components/wa-card.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-card` · Web Awesome · component · Layout · recommendation: supported
+`@kerfjs/ui:wa-card` · Web Awesome · component · Layout · recommendation: avoid
 
 ## When to use
 
-Groups related content and optional header, media, and footer slots.
+Ecosystem card; use Kerf ContentItem or SunkenPanel.
+
+- Groups related content and optional header, media, and footer 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 ContentItem (appearance="surface" for a raised card) to contain related content, or SunkenPanel for a lowered region.
+
+**Alternatives:**
+
+- [ContentItem](./content-item.md) (prefer-kerf) — Use ContentItem, with appearance="surface" for a raised card, to contain related content.
+- [SunkenPanel](./sunken-panel.md) (prefer-kerf) — Use SunkenPanel for a lowered region holding a content stack.
 
 ## Imports
 
@@ -55,5 +62,6 @@ Public tokens it reads: `--kui-wa-surface-margin`, `--kui-wa-surface-inset`, `--
 
 ## Related
 
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- Components: [ContentItem](./content-item.md), [SunkenPanel](./sunken-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-card`.

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

@@ -11,6 +11,7 @@ One content slide inside a carousel.
 **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-carousel.md

@@ -11,6 +11,7 @@ Navigable horizontal or vertical collection of slides.
 **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-checkbox-group.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-checkbox-group` · Web Awesome · component · Forms · recommendation: supported
+`@kerfjs/ui:wa-checkbox-group` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Labels and validates a related set of checkboxes.
+Ecosystem checkbox group; use Kerf Checkbox rows or ChoiceChips.
+
+- Labels and validates a related set of checkboxes.
 
 **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 Checkbox rows in a List, or ChoiceChips multiple for wrapping pills.
+
+**Alternatives:**
+
+- [Checkbox](./checkbox.md) (prefer-kerf) — Use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills.
+- [ChoiceChips](./choice-chips.md) (prefer-kerf) — Use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills.
 
 ## Imports
 
@@ -50,6 +57,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Checkbox](./wa-checkbox.md).
+- Components: [Checkbox](./wa-checkbox.md), [Checkbox](./checkbox.md), [ChoiceChips](./choice-chips.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-checkbox-group`.

package/ai/components/wa-checkbox.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-checkbox` · Web Awesome · component · Forms · recommendation: supported
+`@kerfjs/ui:wa-checkbox` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Binary form control with checked, indeterminate, and disabled states.
+Ecosystem checkbox; use Kerf Checkbox.
+
+- Binary form control with checked, indeterminate, and disabled states.
 
 **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 Checkbox for a submitted option.
+
+**Alternatives:**
+
+- [Checkbox](./checkbox.md) (prefer-kerf) — Use Checkbox for a submitted option.
 
 ## 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), [Checkbox](./checkbox.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-checkbox`.

package/ai/components/wa-color-picker.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-color-picker` · Web Awesome · component · Forms · recommendation: supported
+`@kerfjs/ui:wa-color-picker` · Web Awesome · component · Forms · recommendation: avoid
 
 ## When to use
 
-Color input with swatches, formats, opacity, and eyedropper support.
+Ecosystem color picker; use the Kerf ColorField or ColorPicker.
+
+- Only inside an application that has already adopted the optional Web Awesome integration.
 
 **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 ColorField (@kerfjs/ui/color-field) for a field that opens a picker, ColorPicker (@kerfjs/ui/color-picker) inline, or ColorSwatches for a fixed palette.
+
+**Alternatives:**
+
+- [ColorField](./color-field.md) (prefer-kerf) — Use ColorField for a color in a form or inspector.
+- [ColorPicker](./color-picker.md) (prefer-kerf) — Use an inline ColorPicker when the color is the view's main task.
+- [ColorSwatches](./color-swatches.md) (prefer-kerf) — Use ColorSwatches for a fixed palette.
 
 ## Imports
 
@@ -50,6 +58,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Button](./wa-button.md), [Button Group](./wa-button-group.md), [Input](./wa-input.md), [Popup](./wa-popup.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- Components: [Button](./wa-button.md), [Button Group](./wa-button-group.md), [Input](./wa-input.md), [Popup](./wa-popup.md), [ColorField](./color-field.md), [ColorPicker](./color-picker.md), [ColorSwatches](./color-swatches.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-color-picker`.

package/ai/components/wa-comparison.md

@@ -11,6 +11,7 @@ Specialized before-and-after media; use only when specifically required.
 **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
 
@@ -51,5 +52,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [Icon](./wa-icon.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- 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-comparison`.

package/ai/components/wa-copy-button.md

@@ -11,6 +11,7 @@ Copies a supplied value and announces success or failure.
 **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-details.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-details` · Web Awesome · component · Layout · recommendation: supported
+`@kerfjs/ui:wa-details` · Web Awesome · component · Layout · recommendation: avoid
 
 ## When to use
 
-Single disclosure panel for secondary information.
+Ecosystem disclosure; use the Kerf Disclosure.
+
+- Single disclosure panel for secondary information.
 
 **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 Disclosure (@kerfjs/ui/disclosure), a native details element, and give Disclosures the same name for an accordion.
+
+**Alternatives:**
+
+- [Disclosure](./disclosure.md) (prefer-kerf) — Use Disclosure for show-and-hide content; Disclosures sharing a name form an accordion.
 
 ## Imports
 
@@ -56,6 +62,6 @@ Public tokens it reads: `--kui-wa-surface-margin`, `--kui-wa-surface-inset`, `--
 
 ## Related
 
-- Components: [Icon](./wa-icon.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- Components: [Icon](./wa-icon.md), [Disclosure](./disclosure.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-details`.

package/ai/components/wa-dialog.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-dialog` · Web Awesome · component · Layout · recommendation: supported
+`@kerfjs/ui:wa-dialog` · Web Awesome · component · Layout · recommendation: avoid
 
 ## When to use
 
-Modal surface for focused tasks and confirmations.
+Ecosystem dialog; use Kerf DialogSurface with openDialog and closeDialog.
+
+- Modal surface for focused tasks and confirmations.
 
 **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 openDialog and closeDialog, or a kerfjs/overlay dialog.
+
+**Alternatives:**
+
+- [Surface Scaffolds](./surface-scaffold.md) (prefer-kerf) — Use DialogSurface with openDialog and closeDialog, or a kerfjs/overlay dialog.
 
 ## Imports
 
@@ -54,6 +60,6 @@ Classes an application may place on its own elements: `hide-actions`.
 
 ## Related
 
-- Components: [Button](./wa-button.md).
+- Components: [Button](./wa-button.md), [Surface Scaffolds](./surface-scaffold.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-dialog`.

package/ai/components/wa-divider.md

@@ -11,6 +11,7 @@ Visual separator for related groups of 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