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

package/ai/components/wa-comparison.md

@@ -0,0 +1,56 @@
+# Comparison
+
+<!-- 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-comparison` · Web Awesome · component · Media · recommendation: exceptional
+
+## When to use
+
+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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/comparison/comparison.js` once (a side effect).
+- Custom element: `<wa-comparison>`.
+- 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: 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).
+- 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

@@ -0,0 +1,56 @@
+# Copy 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-copy-button` · Web Awesome · component · Actions · recommendation: supported
+
+## When to use
+
+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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/copy-button/copy-button.js` once (a side effect).
+- Custom element: `<wa-copy-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), [Tooltip](./wa-tooltip.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), [Tooltip](./wa-tooltip.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- UX catalog route: `?component=wa-copy-button`.

package/ai/components/wa-details.md

@@ -0,0 +1,67 @@
+# Details
+
+<!-- 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: avoid
+
+## When to use
+
+Ecosystem disclosure; use the Kerf Disclosure.
+
+- Single disclosure panel for secondary information.
+
+**Not when:**
+
+- 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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/details/details.js` once (a side effect).
+- Custom element: `<wa-details>`.
+- 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.
+- Built from: [Icon](./wa-icon.md).
+
+## 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: [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

@@ -0,0 +1,65 @@
+# Dialog
+
+<!-- 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: avoid
+
+## When to use
+
+Ecosystem dialog; use Kerf DialogSurface with openDialog and closeDialog.
+
+- Modal surface for focused tasks and confirmations.
+
+**Not when:**
+
+- 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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/dialog/dialog.js` once (a side effect).
+- Custom element: `<wa-dialog>`.
+- 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: 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 class hooks (select for layout placement only, never to change the component's look): `hide-actions`.
+
+Classes an application may place on its own elements: `hide-actions`.
+
+## Related
+
+- 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

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

package/ai/components/wa-drawer.md

@@ -0,0 +1,62 @@
+# Drawer
+
+<!-- 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: avoid
+
+## When to use
+
+Ecosystem drawer; use Kerf DialogSurface sheets or CollapsiblePanel.
+
+- Edge-anchored modal surface for navigation or secondary tasks.
+
+**Not when:**
+
+- 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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/drawer/drawer.js` once (a side effect).
+- Custom element: `<wa-drawer>`.
+- 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: layout). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+## Related
+
+- Components: [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

@@ -0,0 +1,62 @@
+# Dropdown 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-dropdown-item` · Web Awesome · component · Actions · recommendation: avoid
+
+## When to use
+
+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 use it in Kerf UI; use PopupMenu items for commands and Select choices for values.
+
+**Alternatives:**
+
+- [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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js` once (a side effect).
+- Custom element: `<wa-dropdown-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.
+- Built from: [Icon](./wa-icon.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), [PopupMenu](./popup-menu.md), [Select](./select.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=wa-dropdown-item`.

package/ai/components/wa-dropdown.md

@@ -0,0 +1,62 @@
+# Dropdown
+
+<!-- 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: avoid
+
+## When to use
+
+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 use it in Kerf UI; use PopupMenu for a command menu and Select for a value.
+
+**Alternatives:**
+
+- [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
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/dropdown/dropdown.js` once (a side effect).
+- Custom element: `<wa-dropdown>`.
+- 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: [Dropdown Item](./wa-dropdown-item.md), [Popup](./wa-popup.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: [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-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=wa-dropdown`.

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

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

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

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

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

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