@brightspot/ui 6.8.1 → 6.8.3-rc.1

package/docs/components/DropdownMenu.md

@@ -1,81 +1,41 @@
-# `src/components/dropdown/DropdownMenu.ts`:
+# `<btu-dropdown-menu>`
 
-## class: `DropdownMenu`, `btu-dropdown-menu`
+A menu container component that provides keyboard navigation and ARIA menu semantics.
 
-### Superclass
+Contains `btu-dropdown-item` children and manages roving tabindex, typeahead search,
+and keyboard navigation following the WAI-ARIA Menu Button Pattern.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/dropdown/DropdownMenu.js'
+```
 
-### Mixins
+## Attributes
 
-| Name                  | Module                           | Package |
-| --------------------- | -------------------------------- | ------- |
-| `RovingTabindexMixin` | /src/util/RovingTabindexMixin.js |         |
-| `EventEmitterMixin`   | /src/util/EventEmitterMixin.js   |         |
-| `ReadyMixin`          | /src/util/ReadyMixin.js          |         |
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` | `string` | `''` | Accessible name for the menu, displayed in header when header is true. |
+| `header` | `header` | `boolean` | `false` | Show header bar with menu name. |
+| `checkbox` | `checkbox` | `boolean` | `false` | Enable checkbox mode for items (menuitemcheckbox role). |
+| `icon` | `icon` | `boolean` | `false` | Show icons before each item. |
+| `symbol` | `symbol` | `string` | `''` | Fallback Lucide icon symbol for items without their own. |
+| `favorites` | `favorites` | `boolean` | `false` | Show favorite toggle on each item. |
+| `shortcuts` | `shortcuts` | `boolean` | `false` | Show keyboard shortcut text on each item. |
+| `empty-message` | `emptyMessage` | `string` | `'No items available'` | Message displayed when the menu has no focusable items. |
 
-### Fields
+## Events
 
-| Name           | Privacy | Type      | Default                | Description                                                            | Inherited From |
-| -------------- | ------- | --------- | ---------------------- | ---------------------------------------------------------------------- | -------------- |
-| `name`         |         | `string`  | `''`                   | Accessible name for the menu, displayed in header when header is true. |                |
-| `header`       |         | `boolean` | `false`                | Show header bar with menu name.                                        |                |
-| `checkbox`     |         | `boolean` | `false`                | Enable checkbox mode for items (menuitemcheckbox role).                |                |
-| `icon`         |         | `boolean` | `false`                | Show icons before each item.                                           |                |
-| `symbol`       |         | `string`  | `''`                   | Fallback Lucide icon symbol for items without their own.               |                |
-| `favorites`    |         | `boolean` | `false`                | Show favorite toggle on each item.                                     |                |
-| `shortcuts`    |         | `boolean` | `false`                | Show keyboard shortcut text on each item.                              |                |
-| `emptyMessage` |         | `string`  | `'No items available'` | Message displayed when the menu has no focusable items.                |                |
-| `_isEmpty`     | private | `boolean` |                        | Check whether the menu has zero focusable items                        |                |
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-dropdown-menu-ready` |  | Fired after first render |
 
-### Methods
+## Slots
 
-| Name                 | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return           | Inherited From    |
-| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ---------------- | ----------------- |
-| `_configureItems`    | private | Configure all child items with menu-level settings                                                                                                                                                                                                                                 |                                                         | `void`           |                   |
-| `_getAllItems`       | private | Get all btu-dropdown-item children                                                                                                                                                                                                                                                 |                                                         | `DropdownItem[]` |                   |
-| `_getFocusableItems` | private | Get only focusable items (default type, skip dividers/subheads)                                                                                                                                                                                                                    |                                                         | `DropdownItem[]` |                   |
-| `_handleTypeahead`   | private | Typeahead character matching with 500ms accumulation                                                                                                                                                                                                                               | `char: string, focusable: DropdownItem[]`               | `void`           |                   |
-| `emit`               |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean`        | EventEmitterMixin |
+| Slot | Description |
+| --- | --- |
+| (default) | Menu items (`btu-dropdown-item` elements) |
 
-### Events
+## CSS custom properties
 
-| Name                      | Type          | Description              | Inherited From |
-| ------------------------- | ------------- | ------------------------ | -------------- |
-| `btu-dropdown-menu-ready` | `CustomEvent` | Fired after first render |                |
-
-### Attributes
-
-| Name            | Field        | Inherited From |
-| --------------- | ------------ | -------------- |
-| `name`          | name         |                |
-| `header`        | header       |                |
-| `checkbox`      | checkbox     |                |
-| `icon`          | icon         |                |
-| `symbol`        | symbol       |                |
-| `favorites`     | favorites    |                |
-| `shortcuts`     | shortcuts    |                |
-| `empty-message` | emptyMessage |                |
-
-### CSS Properties
-
-| Name                     | Default | Description                                |
-| ------------------------ | ------- | ------------------------------------------ |
-| `--dropdown-empty-color` |         | Empty state text color (default: gray-400) |
-
-### Slots
-
-| Name | Description                                 |
-| ---- | ------------------------------------------- |
-|      | Menu items (\`btu-dropdown-item\` elements) |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name                | Declaration  | Module                                  | Package |
-| --------------------------- | ------------------- | ------------ | --------------------------------------- | ------- |
-| `js`                        | `default`           | DropdownMenu | src/components/dropdown/DropdownMenu.ts |         |
-| `custom-element-definition` | `btu-dropdown-menu` | DropdownMenu | src/components/dropdown/DropdownMenu.ts |         |
+| Property | Description |
+| --- | --- |
+| `--dropdown-empty-color` | Empty state text color (default: gray-400) |

package/docs/components/EmptyState.md

@@ -1,79 +1,62 @@
-# `src/components/empty-state/EmptyState.ts`:
+# `<btu-empty-state>`
 
-## class: `EmptyState`, `btu-empty-state`
+An empty state component for displaying placeholder content when no data is available.
 
-### Superclass
+Supports a graphic slot for icons/images/pictures/SVGs, a heading, a description,
+and an actions slot for buttons or links. Available in three sizes (sm, md, lg)
+with semantic heading levels.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+## Architecture: Light DOM + Pseudo-Slots
 
-### Mixins
+This component uses **Light DOM** (no Shadow Root) with pseudo-slots:
+- User-provided children are physically moved into internal containers
+- Movement is based on `slot` attributes
+- The `onFind` utility detects and redistributes newly-added children (one-time per element)
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `OnFindMixin`       | /src/util/OnFindMixin.js       |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+### Node Redistribution Rules
+- `slot="graphic"` - Moved to graphic container (icon, image, picture, or SVG)
+- `slot="actions"` - Moved to an internal `btu-button-group` (variant="spaced")
 
-### Fields
+### Actions composition
 
-| Name             | Privacy | Type                   | Default | Description                                                                                                                                                                                                                                                                        | Inherited From |
-| ---------------- | ------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `heading`        |         | `string`               | `''`    | Heading text displayed in the empty state.                                                                                                                                                                                                                                         |                |
-| `description`    |         | `string \| undefined`  |         | Description text displayed below the heading.                                                                                                                                                                                                                                      |                |
-| `size`           |         | `'sm' \| 'md' \| 'lg'` | `'md'`  | Size variant of the empty state. Affects spacing, description text, graphic size,&#xA;and — when \`heading-level\` is unset — the default heading level (sm→5, md→4, lg→3).                                                                                                        |                |
-| `headingLevel`   |         | `number \| undefined`  |         | Heading level (1-6). When set to a valid integer 1-6, overrides the size-based&#xA;default and drives both the semantic h1-h6 tag and the visual heading size&#xA;(btu-heading-1 through btu-heading-6). Invalid values log a warning and fall&#xA;back to the size-based default. |                |
-| `initialClasses` | private | `string[]`             | `[]`    |                                                                                                                                                                                                                                                                                    |                |
-| `#stopFns`       | private | `Array<() => void>`    | `[]`    |                                                                                                                                                                                                                                                                                    | OnFindMixin    |
+The actions container IS a `btu-button-group` with `variant="spaced"`. Its `size`
+is mapped from the empty-state `size` prop (sm→small, md→medium, lg→large) so all
+child `btu-button` / `btu-icon-button` elements get consistent sizing and group
+semantics (`role="group"`, roving tabindex, disabled propagation) for free.
 
-### Methods
+```js
+import '@brightspot/ui/components/empty-state/EmptyState.js'
+```
 
-| Name                  | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return                                               | Inherited From    |
-| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------- | ----------------- |
-| `syncGraphicIconSize` | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`                                               |                   |
-| `resolveHeadingLevel` | private |                                                                                                                                                                                                                                                                                    |                                                         | `HeadingLevel`                                       |                   |
-| `renderHeading`       | private |                                                                                                                                                                                                                                                                                    | `level: HeadingLevel, className: string`                | `TemplateResult \| string`                           |                   |
-| `emit`                |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean`                                            | EventEmitterMixin |
-| `onFindRegistration`  |         |                                                                                                                                                                                                                                                                                    |                                                         | `OnFindRegistration \| OnFindRegistration[] \| null` | OnFindMixin       |
-| `#armFind`            | private |                                                                                                                                                                                                                                                                                    |                                                         |                                                      | OnFindMixin       |
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-empty-state--docs
 
-### Events
+## Attributes
 
-| Name                     | Type          | Description                                    | Inherited From |
-| ------------------------ | ------------- | ---------------------------------------------- | -------------- |
-| `btu-empty-state-ready`  | `CustomEvent` | Fired after first render and initialization    |                |
-| `btu-button-group-ready` | `CustomEvent` | Bubbles from the internal actions button-group |                |
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `heading` | `heading` | `string` | `''` | Heading text displayed in the empty state. |
+| `description` | `description` | `string \| undefined` |  | Description text displayed below the heading. |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant of the empty state. Affects spacing, description text, graphic size, and — when `heading-level` is unset — the default heading level (sm→5, md→4, lg→3). |
+| `heading-level` | `headingLevel` | `number \| undefined` |  | Heading level (1-6). When set to a valid integer 1-6, overrides the size-based default and drives both the semantic h1-h6 tag and the visual heading size (btu-heading-1 through btu-heading-6). Invalid values log a warning and fall back to the size-based default. |
 
-### Attributes
+## Events
 
-| Name            | Field        | Inherited From |
-| --------------- | ------------ | -------------- |
-| `heading`       | heading      |                |
-| `description`   | description  |                |
-| `size`          | size         |                |
-| `heading-level` | headingLevel |                |
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-empty-state-ready` |  | Fired after first render and initialization |
+| `btu-button-group-ready` |  | Bubbles from the internal actions button-group |
 
-### CSS Properties
+## Slots
 
-| Name                              | Default | Description                                                     |
-| --------------------------------- | ------- | --------------------------------------------------------------- |
-| `--empty-state-max-width`         |         | Maximum width of the content block (default: min(75cqw, 360px)) |
-| `--empty-state-color-heading`     |         | Heading text color (default: gray-900)                          |
-| `--empty-state-color-description` |         | Description text color (default: gray-500)                      |
+| Slot | Description |
+| --- | --- |
+| `graphic` | Pseudo-slot for icon, image, picture, or SVG graphic. When the child is a `btu-icon`, the component overrides its `size` attribute based on the empty-state `size` prop (sm→md, md→lg, lg→xl). Use an `img`, `picture`, or inline `svg` for full size control. |
+| `actions` | Pseudo-slot for action buttons. Children are moved into an internal `btu-button-group` (variant="spaced"), so size and disabled state are managed by the group. |
 
-### Slots
+## CSS custom properties
 
-| Name      | Description                                                                                                                                                                                                                                                                |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `graphic` | Pseudo-slot for icon, image, picture, or SVG graphic. When the child is a \`btu-icon\`, the component overrides its \`size\` attribute based on the empty-state \`size\` prop (sm→md, md→lg, lg→xl). Use an \`img\`, \`picture\`, or inline \`svg\` for full size control. |
-| `actions` | Pseudo-slot for action buttons. Children are moved into an internal \`btu-button-group\` (variant="spaced"), so size and disabled state are managed by the group.                                                                                                          |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name              | Declaration | Module                                   | Package |
-| --------------------------- | ----------------- | ----------- | ---------------------------------------- | ------- |
-| `js`                        | `default`         | EmptyState  | src/components/empty-state/EmptyState.ts |         |
-| `custom-element-definition` | `btu-empty-state` | EmptyState  | src/components/empty-state/EmptyState.ts |         |
+| Property | Description |
+| --- | --- |
+| `--empty-state-max-width` | Maximum width of the content block (default: min(75cqw, 360px)) |
+| `--empty-state-color-heading` | Heading text color (default: gray-900) |
+| `--empty-state-color-description` | Description text color (default: gray-500) |

package/docs/components/EscaAvatar.md

@@ -1,71 +1,40 @@
-# `src/components/esca-avatar/EscaAvatar.ts`:
+# `<btu-esca-avatar>`
 
-## class: `EscaAvatar`, `btu-esca-avatar`
+The animated avatar for the Esca AI assistant, driven entirely by its `state` attribute so the same
+element works wherever the assistant appears.
 
-### Superclass
+Accessibility: the avatar is a visual indicator, not a status channel. By default it exposes a static
+accessible name (`role="img"`, `aria-label="Esca"`) so it reads like an author/identity avatar; both
+are only set when absent, so consumers can override them.
+- When the assistant is already named in the surrounding UI (the common case in a chat), treat the
+  avatar as decorative: set `aria-hidden="true"` to avoid a redundant announcement.
+- Do NOT convey activity (thinking / done) by changing this element's ARIA per `state` — a looping
+  `search` would announce repeatedly. Surface status as text in a polite `aria-live` region owned by
+  the chat UI, which has the context to word and time announcements. This component intentionally
+  does not announce its own state.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/esca-avatar/EscaAvatar.js'
+```
 
-### Mixins
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-esca-avatar--docs
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+## Attributes
 
-### Fields
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `state` | `state` | `'idle' \| 'wave' \| 'search' \| 'complete' \| 'glow'` | `'idle'` | Animation to play; changing it swaps the clip. |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size of the avatar, mirroring `<btu-avatar>`'s scale. `--esca-avatar-size` overrides it. |
 
-| Name                    | Privacy | Type                                | Default  | Description                                                                                   | Inherited From |
-| ----------------------- | ------- | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------- | -------------- |
-| `state`                 |         | `EscaAvatarState`                   | `'idle'` | Animation to play; changing it swaps the clip.                                                |                |
-| `size`                  |         | `EscaAvatarSize`                    | `'md'`   | Size of the avatar, mirroring \`\<btu-avatar>\`'s scale. \`--esca-avatar-size\` overrides it. |                |
-| `_containerRef`         | private | `Ref<HTMLDivElement>`               |          |                                                                                               |                |
-| `_animation`            | private | `AnimationItem \| null`             | `null`   |                                                                                               |                |
-| `_rendered`             | private | `EscaAvatarState \| null`           | `null`   |                                                                                               |                |
-| `_reduceMotion`         | private | `boolean`                           | `false`  |                                                                                               |                |
-| `_loadToken`            | private | `number`                            | `0`      |                                                                                               |                |
-| `_resizeObserver`       | private | `ResizeObserver \| undefined`       |          |                                                                                               |                |
-| `_intersectionObserver` | private | `IntersectionObserver \| undefined` |          |                                                                                               |                |
-| `_motionQuery`          | private | `MediaQueryList \| undefined`       |          |                                                                                               |                |
-| `_onMotionChange`       | private |                                     |          |                                                                                               |                |
+## Events
 
-### Methods
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-esca-avatar-ready` |  | Fired after the first render |
+| `btu-esca-avatar-complete` | `{state: string}` | Fired when a non-looping animation finishes |
 
-| Name         | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `_observe`   | private |                                                                                                                                                                                                                                                                                    |                                                         |           |                   |
-| `_applySize` | private |                                                                                                                                                                                                                                                                                    |                                                         |           |                   |
-| `_play`      | private |                                                                                                                                                                                                                                                                                    |                                                         |           |                   |
-| `_destroy`   | private |                                                                                                                                                                                                                                                                                    |                                                         |           |                   |
-| `emit`       |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
+## CSS custom properties
 
-### Events
-
-| Name                       | Type                           | Description                                 | Inherited From |
-| -------------------------- | ------------------------------ | ------------------------------------------- | -------------- |
-| `btu-esca-avatar-ready`    | `CustomEvent`                  | Fired after the first render                |                |
-| `btu-esca-avatar-complete` | `CustomEvent<{state: string}>` | Fired when a non-looping animation finishes |                |
-
-### Attributes
-
-| Name    | Field | Inherited From |
-| ------- | ----- | -------------- |
-| `state` | state |                |
-| `size`  | size  |                |
-
-### CSS Properties
-
-| Name                 | Default | Description                                                                        |
-| -------------------- | ------- | ---------------------------------------------------------------------------------- |
-| `--esca-avatar-size` |         | Width and height of the avatar; overrides the \`size\` attribute (default: 2.5rem) |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name              | Declaration | Module                                   | Package |
-| --------------------------- | ----------------- | ----------- | ---------------------------------------- | ------- |
-| `js`                        | `default`         | EscaAvatar  | src/components/esca-avatar/EscaAvatar.ts |         |
-| `custom-element-definition` | `btu-esca-avatar` | EscaAvatar  | src/components/esca-avatar/EscaAvatar.ts |         |
+| Property | Description |
+| --- | --- |
+| `--esca-avatar-size` | Width and height of the avatar; overrides the `size` attribute (default: 2.5rem) |

package/docs/components/Icon.md

@@ -1,73 +1,40 @@
-# `src/components/icon/Icon.ts`:
+# `<btu-icon>`
 
-## class: `Icon`, `btu-icon`
+An icon component for displaying Lucide icons.
 
-### Superclass
+Icons inherit parent text color by default or can use gradient fills.
+All icons are from the Lucide icon library (https://lucide.dev/icons/).
+Supports both direct SVG rendering and mask-based gradient fills.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/icon/Icon.js'
+```
 
-### Mixins
+The CMS page defines this element itself, so a plugin can use it there without the import.
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-icon--docs
 
-### Static Fields
+## Attributes
 
-| Name      | Privacy | Type | Default | Description | Inherited From |
-| --------- | ------- | ---- | ------- | ----------- | -------------- |
-| `tagName` |         |      |         |             |                |
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size of the icon. - 'xs': Extra small (0.75rem) - 'sm': Small (1rem) - 'md': Medium (1.25rem, default) - 'lg': Large (1.5rem) - 'xl': Extra large (1.75rem) |
+| `symbol` | `symbol` | `string` | `'circle-dashed'` | Lucide icon name to display. See https://lucide.dev/icons/ for available icons. Lucide v1 removed all brand logos - legacy facebook/instagram/slack/twitter swap to the vendored brand marks at runtime, any other brand name falls back to circle-dashed. |
+| `brand` | `brand` | `string \| undefined` |  | Vendored brand mark to display instead of a Lucide icon (names in src/brand-icons.ts); takes precedence over `symbol`. |
+| `gradient` | `gradient` | `IconGradientColor \| undefined` |  | Theme color to use for gradient fill. When set, icon displays with gradient. When undefined, icon inherits parent text color. |
+| `emphasize` | `emphasize` | `boolean \| 'pulse' \| undefined` |  | Emphasize mode — renders a tonal circle with ring behind the icon. Colors are derived from `currentColor` via oklch relative color syntax. Defaults to primary; override with Tailwind `text-*` classes or `style="color: ..."`. Set as a boolean for the static circle, or `"pulse"` for a one-shot ring animation. Not intended for use with `gradient` — the two features target conflicting rendering modes. |
 
-### Fields
+## Events
 
-| Name                      | Privacy | Type                                   | Default           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     | Inherited From |
-| ------------------------- | ------- | -------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `size`                    |         | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'`            | Size of the icon.&#xA;- 'xs': Extra small (0.75rem)&#xA;- 'sm': Small (1rem)&#xA;- 'md': Medium (1.25rem, default)&#xA;- 'lg': Large (1.5rem)&#xA;- 'xl': Extra large (1.75rem)                                                                                                                                                                                                                                                                 |                |
-| `symbol`                  |         | `string`                               | `'circle-dashed'` | Lucide icon name to display.&#xA;See https\://lucide.dev/icons/ for available icons.&#xA;Lucide v1 removed all brand logos - legacy facebook/instagram/slack/twitter&#xA;swap to the vendored brand marks at runtime, any other brand name falls&#xA;back to circle-dashed.                                                                                                                                                                     |                |
-| `brand`                   |         | `string \| undefined`                  |                   | Vendored brand mark to display instead of a Lucide icon (names in&#xA;src/brand-icons.ts); takes precedence over \`symbol\`.                                                                                                                                                                                                                                                                                                                    |                |
-| `gradient`                |         | `IconGradientColor \| undefined`       |                   | Theme color to use for gradient fill.&#xA;When set, icon displays with gradient. When undefined, icon inherits parent text color.                                                                                                                                                                                                                                                                                                               |                |
-| `emphasize`               |         | `boolean \| 'pulse' \| undefined`      |                   | Emphasize mode — renders a tonal circle with ring behind the icon.&#xA;Colors are derived from \`currentColor\` via oklch relative color syntax.&#xA;Defaults to primary; override with Tailwind \`text-\*\` classes or \`style="color: ..."\`.&#xA;Set as a boolean for the static circle, or \`"pulse"\` for a one-shot ring animation.&#xA;Not intended for use with \`gradient\` — the two features target&#xA;conflicting rendering modes. |                |
-| `_initialClassesCaptured` | private | `boolean`                              | `false`           |                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                |
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-icon-ready` |  | Fired after first render and initialization |
 
-### Methods
+## CSS custom properties
 
-| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `emit` |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
-
-### Events
-
-| Name             | Type          | Description                                 | Inherited From |
-| ---------------- | ------------- | ------------------------------------------- | -------------- |
-| `btu-icon-ready` | `CustomEvent` | Fired after first render and initialization |                |
-
-### Attributes
-
-| Name        | Field     | Inherited From |
-| ----------- | --------- | -------------- |
-| `size`      | size      |                |
-| `symbol`    | symbol    |                |
-| `brand`     | brand     |                |
-| `gradient`  | gradient  |                |
-| `emphasize` | emphasize |                |
-
-### CSS Properties
-
-| Name                  | Default | Description                                                                                         |
-| --------------------- | ------- | --------------------------------------------------------------------------------------------------- |
-| `--icon-size`         |         | Icon size (overrides size default)                                                                  |
-| `--icon-stroke-width` |         | SVG stroke width as a unitless number in viewBox units; scales visually with icon size (default: 2) |
-| `--icon-fill`         |         | Icon fill color for filled icons (e.g., "currentColor")                                             |
-| `--icon-svg`          |         | SVG data URI for mask-based rendering                                                               |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name       | Declaration | Module                      | Package |
-| --------------------------- | ---------- | ----------- | --------------------------- | ------- |
-| `js`                        | `default`  | Icon        | src/components/icon/Icon.ts |         |
-| `custom-element-definition` | `btu-icon` | Icon        | src/components/icon/Icon.ts |         |
+| Property | Description |
+| --- | --- |
+| `--icon-size` | Icon size (overrides size default) |
+| `--icon-stroke-width` | SVG stroke width as a unitless number in viewBox units; scales visually with icon size (default: 2) |
+| `--icon-fill` | Icon fill color for filled icons (e.g., "currentColor") |
+| `--icon-svg` | SVG data URI for mask-based rendering |