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

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

@@ -0,0 +1,54 @@
+# Breadcrumb Item
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:wa-breadcrumb-item` · Web Awesome · component · Navigation · recommendation: supported
+
+## When to use
+
+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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/breadcrumb-item/breadcrumb-item.js` once (a side effect).
+- Custom element: `<wa-breadcrumb-item>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## 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
+
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-breadcrumb-item`.

package/ai/components/wa-breadcrumb.md

@@ -0,0 +1,56 @@
+# Breadcrumb
+
+<!-- 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-breadcrumb` · Web Awesome · component · Navigation · recommendation: supported
+
+## When to use
+
+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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/breadcrumb/breadcrumb.js` once (a side effect).
+- Custom element: `<wa-breadcrumb>`.
+- 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), [Breadcrumb Item](./wa-breadcrumb-item.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: child · padding: child (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+## Related
+
+- Components: [Icon](./wa-icon.md), [Breadcrumb Item](./wa-breadcrumb-item.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-breadcrumb`.

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

@@ -0,0 +1,62 @@
+# Button Group
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:wa-button-group` · Web Awesome · component · Actions · recommendation: avoid
+
+## When to use
+
+Ecosystem button group; use Kerf ToolbarControlGroup, SplitButton, or SegmentedControl.
+
+- Exceptional grouped actions; prefer Kerf SegmentedControl for exclusive choices.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use ToolbarControlGroup or SplitButton for grouped actions and SegmentedControl for one-of-many choices.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (prefer-kerf)
+- [SplitButton](./split-button.md) (prefer-kerf) — For a primary action with an attached options trigger, use SplitButton.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/button-group/button-group.js` once (a side effect).
+- Custom element: `<wa-button-group>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Button](./wa-button.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: child · padding: child (layout role: actions). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+## Related
+
+- Components: [Button](./wa-button.md), [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-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=wa-button-group`.

package/ai/components/wa-button.md

@@ -0,0 +1,61 @@
+# Button
+
+<!-- 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: avoid
+
+## When to use
+
+Ecosystem action button; use Kerf Button.
+
+- Action control with semantic variants, appearances, loading, and icon support.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use Button for a text, text-and-icon, or icon-only action.
+
+**Alternatives:**
+
+- [Button](./button.md) (prefer-kerf) — Use Button for a text, text-and-icon, or icon-only action.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/button/button.js` once (a side effect).
+- Custom element: `<wa-button>`.
+- 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: self · padding: self (layout role: actions). `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), [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

@@ -0,0 +1,60 @@
+# Callout
+
+<!-- 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: avoid
+
+## When to use
+
+Ecosystem callout; use Kerf StateBanner.
+
+- Prominent contextual message with semantic variants.
+
+**Not when:**
+
+- 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) — Use StateBanner for a persistent inline status, alert, or emphasized message.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/callout/callout.js` once (a side effect).
+- Custom element: `<wa-callout>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: 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.
+
+## 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: [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-callout`.

package/ai/components/wa-card.md

@@ -0,0 +1,67 @@
+# Card
+
+<!-- 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: avoid
+
+## When to use
+
+Ecosystem card; use Kerf ContentItem or SunkenPanel.
+
+- Groups related content and optional header, media, and footer slots.
+
+**Not when:**
+
+- 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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/card/card.js` once (a side effect).
+- Custom element: `<wa-card>`.
+- 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.
+
+**Variants (configure, do not restyle):**
+
+- sunken appearance
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: layout). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+Public tokens it reads: `--kui-wa-surface-margin`, `--kui-wa-surface-inset`, `--kui-wa-sunken-background`, `--kui-wa-sunken-radius`. Set a token only where its public contract allows; prefer a prop.
+
+## Related
+
+- 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

@@ -0,0 +1,54 @@
+# Carousel Item
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:wa-carousel-item` · Web Awesome · component · Media · recommendation: supported
+
+## When to use
+
+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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/carousel-item/carousel-item.js` once (a side effect).
+- Custom element: `<wa-carousel-item>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: media). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+## Related
+
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-carousel-item`.

package/ai/components/wa-carousel.md

@@ -0,0 +1,56 @@
+# Carousel
+
+<!-- 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-carousel` · Web Awesome · component · Media · recommendation: supported
+
+## When to use
+
+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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/carousel/carousel.js` once (a side effect).
+- Custom element: `<wa-carousel>`.
+- 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), [Carousel Item](./wa-carousel-item.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: child (layout role: media). `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), [Carousel Item](./wa-carousel-item.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-carousel`.

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

@@ -0,0 +1,62 @@
+# Checkbox Group
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:wa-checkbox-group` · Web Awesome · component · Forms · recommendation: avoid
+
+## When to use
+
+Ecosystem checkbox group; use Kerf CheckboxGroup or ChoiceChips.
+
+- Labels and validates a related set of checkboxes.
+
+**Not when:**
+
+- Do not use it in Kerf UI; use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills.
+
+**Alternatives:**
+
+- [CheckboxGroup](./checkbox-group.md) (prefer-kerf) — Use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills.
+- [ChoiceChips](./choice-chips.md) (prefer-kerf) — Use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/checkbox-group/checkbox-group.js` once (a side effect).
+- Custom element: `<wa-checkbox-group>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Checkbox](./wa-checkbox.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: child · padding: child (layout role: forms). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+## Related
+
+- Components: [Checkbox](./wa-checkbox.md), [CheckboxGroup](./checkbox-group.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

@@ -0,0 +1,61 @@
+# Checkbox
+
+<!-- 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: avoid
+
+## When to use
+
+Ecosystem checkbox; use Kerf Checkbox.
+
+- Binary form control with checked, indeterminate, and disabled states.
+
+**Not when:**
+
+- 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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/checkbox/checkbox.js` once (a side effect).
+- Custom element: `<wa-checkbox>`.
+- 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).
+
+## 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), [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

@@ -0,0 +1,63 @@
+# Color Picker
+
+<!-- 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: avoid
+
+## When to use
+
+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 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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/color-picker/color-picker.js` once (a side effect).
+- Custom element: `<wa-color-picker>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Button](./wa-button.md), [Button Group](./wa-button-group.md), [Input](./wa-input.md), [Popup](./wa-popup.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: forms). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+## Related
+
+- Components: [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`.