@brightspot/ui 6.8.0 → 6.8.2

package/docs/components/ButtonGroup.md

@@ -1,99 +1,65 @@
-# `src/components/button-group/ButtonGroup.ts`:
-
-## class: `ButtonGroup`, `btu-button-group`
-
-### Superclass
-
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
-
-### Mixins
-
-| Name                   | Module                            | Package |
-| ---------------------- | --------------------------------- | ------- |
-| `RovingTabindexMixin`  | /src/util/RovingTabindexMixin.js  |         |
-| `ComponentStatesMixin` | /src/util/ComponentStatesMixin.js |         |
-| `EventEmitterMixin`    | /src/util/EventEmitterMixin.js    |         |
-| `OnFindMixin`          | /src/util/OnFindMixin.js          |         |
-| `ReadyMixin`           | /src/util/ReadyMixin.js           |         |
-
-### Static Fields
-
-| Name      | Privacy | Type | Default | Description | Inherited From |
-| --------- | ------- | ---- | ------- | ----------- | -------------- |
-| `tagName` |         |      |         |             |                |
-
-### Fields
-
-| Name                      | Privacy | Type                               | Default        | Description                                                                                                                                                         | Inherited From |
-| ------------------------- | ------- | ---------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `label`                   |         | `string`                           | `''`           | Accessible name for the group, announced by assistive devices via aria-label.                                                                                       |                |
-| `orientation`             |         | `'horizontal' \| 'vertical'`       | `'horizontal'` | Layout direction of the buttons.                                                                                                                                    |                |
-| `variant`                 |         | `'connected' \| 'spaced'`          | `'connected'`  | \`connected\` collapses shared borders for a joined appearance.
\`spaced\` renders buttons with a gap.                                                          |                |
-| `size`                    |         | `'sm' \| 'md' \| 'lg'`             | `'md'`         | Propagates a uniform size to all child buttons.                                                                                                                     |                |
-| `disabled`                |         | `boolean`                          | `false`        | When true, disables all child buttons as a group.                                                                                                                   |                |
-| `selection`               |         | `'none' \| 'single' \| 'multiple'` | `'none'`       | Enables toggle/selection behavior.
\`single\` allows one active button; \`multiple\` allows many.                                                               |                |
-| `value`                   |         | `string`                           | `''`           | Reflects the currently selected button value(s).
For \`single\`, the value of the active button.
For \`multiple\`, a comma-delimited list of active values. |                |
-| `name`                    |         | `string`                           | `''`           | When set, creates hidden input(s) for native form participation.                                                                                                    |                |
-| `_initialClassesCaptured` | private | `boolean`                          | `false`        |                                                                                                                                                                     |                |
-| `#stopFns`                | private | `Array<() => void>`                | `[]`           |                                                                                                                                                                     | OnFindMixin    |
-
-### Methods
-
-| 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 |
-| `onFindRegistration` |         |                                                                                                                                                                                                                                                                                    |                                                         | `OnFindRegistration \| OnFindRegistration[] \| null` | OnFindMixin       |
-| `#armFind`           | private |                                                                                                                                                                                                                                                                                    |                                                         |                                                      | OnFindMixin       |
-
-### Events
-
-| Name                      | Type                                       | Description                                               | Inherited From |
-| ------------------------- | ------------------------------------------ | --------------------------------------------------------- | -------------- |
-| `btu-button-group-ready`  | `CustomEvent`                              | Fired after first render and initialization               |                |
-| `btu-button-group-change` | `CustomEvent<{value: string}>`             | Fired when selection changes (single/multiple modes only) |                |
-| `btu-icon-button-click`   | `CustomEvent<{name: string \| undefined}>` | Bubbles from child btu-icon-button elements when clicked  |                |
-
-### Attributes
-
-| Name          | Field       | Inherited From |
-| ------------- | ----------- | -------------- |
-| `label`       | label       |                |
-| `orientation` | orientation |                |
-| `variant`     | variant     |                |
-| `size`        | size        |                |
-| `disabled`    | disabled    |                |
-| `selection`   | selection   |                |
-| `value`       | value       |                |
-| `name`        | name        |                |
-
-### CSS Properties
-
-| Name                               | Default | Description                                                                                                                                                                                                                               |
-| ---------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--button-group-gap`               |         | Space between buttons when variant="spaced" (default: spacing.sm)                                                                                                                                                                         |
-| `--button-group-border-radius`     |         | Corner radius of outer edges when variant="connected" (default: 0.5rem)                                                                                                                                                                   |
-| `--button-group-border-color`      |         | Internal divider color between connected buttons (default: gray-300)                                                                                                                                                                      |
-| `--button-group-selection-bg`      |         | Background of a toggled/selected child (default: child's --button-tint-subtle)                                                                                                                                                            |
-| `--button-group-selection-color`   |         | Text/icon color of a toggled/selected child (default: child's --button-tint-strong)                                                                                                                                                       |
-| `--button-group-shimmer-highlight` |         | Highlight color of the selection shimmer effect (default: child's --button-tint-highlight) Reads the following CSS custom properties from each child button (set by the button plugin per color variant — see tailwind-plugin-button.ts): |
-| `--button-tint-subtle`             |         | Subtle tint of the child button's color family (read-only here)                                                                                                                                                                           |
-| `--button-tint-strong`             |         | Strong tint of the child button's color family (read-only here)                                                                                                                                                                           |
-| `--button-tint-highlight`          |         | Highlight tint of the child button's color family (read-only here)                                                                                                                                                                        |
-
-### Slots
-
-| Name  | Description                                                                                                                                                                                                                                                                                                          |
-| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-|       | One or more \`\<button class="btu-button …">\` or \`\<btu-icon-button>\` elements to display in the group. The \`connected\` variant rounds the outer corners on the real \`\<button>\`, so anchors styled as \`.btu-button\` slotted directly will not get rounded corners. Use \`\<button>\` for grouped controls. |
-| `end` | Pushes the child to the end of the group via auto-margin (vertical: bottom, horizontal: right)                                                                                                                                                                                                                       |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name               | Declaration | Module                                     | Package |
-| --------------------------- | ------------------ | ----------- | ------------------------------------------ | ------- |
-| `js`                        | `default`          | ButtonGroup | src/components/button-group/ButtonGroup.ts |         |
-| `custom-element-definition` | `btu-button-group` | ButtonGroup | src/components/button-group/ButtonGroup.ts |         |
+# `<btu-button-group>`
+
+A semantic container for grouping related buttons together.
+
+Supports connected (joined) and spaced layouts, horizontal and vertical
+orientation, group-level size and disabled propagation, and optional
+toggle/selection modes (single-select or multi-select).
+
+```js
+import '@brightspot/ui/components/button-group/ButtonGroup.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-button-group--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `''` | Accessible name for the group, announced by assistive devices via aria-label. |
+| `orientation` | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction of the buttons. |
+| `variant` | `variant` | `'connected' \| 'spaced'` | `'connected'` | `connected` collapses shared borders for a joined appearance. `spaced` renders buttons with a gap. |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Propagates a uniform size to all child buttons. |
+| `disabled` | `disabled` | `boolean` | `false` | When true, disables all child buttons as a group. |
+| `selection` | `selection` | `'none' \| 'single' \| 'multiple'` | `'none'` | Enables toggle/selection behavior. `single` allows one active button; `multiple` allows many. |
+| `value` | `value` | `string` | `''` | Reflects the currently selected button value(s). For `single`, the value of the active button. For `multiple`, a comma-delimited list of active values. |
+| `name` | `name` | `string` | `''` | When set, creates hidden input(s) for native form participation. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-button-group-ready` |  | Fired after first render and initialization |
+| `btu-button-group-change` | `{value: string}` | Fired when selection changes (single/multiple modes only) |
+| `btu-icon-button-click` | `{name: string \| undefined}` | Bubbles from child btu-icon-button elements when clicked |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | One or more `<button class="btu-button …">` or `<btu-icon-button>` elements to display in the group. The `connected` variant rounds the outer corners on the real `<button>`, so anchors styled as `.btu-button` slotted directly will not get rounded corners. Use `<button>` for grouped controls. |
+| `end` | Pushes the child to the end of the group via auto-margin (vertical: bottom, horizontal: right) |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--button-group-gap` | Space between buttons when variant="spaced" (default: spacing.sm) |
+| `--button-group-border-radius` | Corner radius of outer edges when variant="connected" (default: 0.5rem) |
+| `--button-group-border-color` | Internal divider color between connected buttons (default: gray-300) |
+| `--button-group-selection-bg` | Background of a toggled/selected child (default: child's --button-tint-subtle) |
+| `--button-group-selection-color` | Text/icon color of a toggled/selected child (default: child's --button-tint-strong) |
+| `--button-group-shimmer-highlight` | Highlight color of the selection shimmer effect (default: child's --button-tint-highlight) Reads the following CSS custom properties from each child button (set by the button plugin per color variant — see tailwind-plugin-button.ts): |
+| `--button-tint-subtle` | Subtle tint of the child button's color family (read-only here) |
+| `--button-tint-strong` | Strong tint of the child button's color family (read-only here) |
+| `--button-tint-highlight` | Highlight tint of the child button's color family (read-only here) |
+
+## CSS states
+
+| State | Description |
+| --- | --- |
+| `:state(btu-connected)` | Applied when variant="connected", targetable via :state(btu-connected) |
+| `:state(btu-spaced)` | Applied when variant="spaced", targetable via :state(btu-spaced) |
+| `:state(btu-horizontal)` | Applied when orientation="horizontal", targetable via :state(btu-horizontal) |
+| `:state(btu-vertical)` | Applied when orientation="vertical", targetable via :state(btu-vertical) |
+| `:state(btu-disabled)` | Applied when the group is disabled, targetable via :state(btu-disabled) |

package/docs/components/Card.md

@@ -1,83 +1,67 @@
-# `src/components/card/Card.ts`:
-
-## class: `Card`, `btu-card`
-
-### Superclass
-
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
-
-### Mixins
-
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `OnFindMixin`       | /src/util/OnFindMixin.js       |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
-
-### Fields
-
-| Name           | Privacy | Type                  | Default | Description                                                                                                                                         | Inherited From |
-| -------------- | ------- | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `heading`      |         | `string`              | `''`    | Heading text displayed on the card.                                                                                                                 |                |
-| `headingLevel` |         | `number`              | `2`     | Heading level (1-6) for the card heading element. Drives the semantic h1–h6 tag.
Invalid values log a warning and fall back to the default (2). |                |
-| `description`  |         | `string \| undefined` |         | Supporting body text. Truncated to 3 lines via CSS.                                                                                                 |                |
-| `compact`      |         | `boolean`             | `false` | Renders the card as a compact quick-start tile.
Badge, image, fields, and secondary-action children are ignored in this case.                   |                |
-| `disabled`     |         | `boolean`             | `false` | Whether the card is disabled.                                                                                                                       |                |
-| `href`         |         | `string \| undefined` |         | Navigation URL for the entire card surface.
When set, the card renders as a link.                                                               |                |
-| `#stopFns`     | private | `Array<() => void>`   | `[]`    |                                                                                                                                                     | OnFindMixin    |
-
-### Methods
-
-| 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 |
-| `onFindRegistration` |         |                                                                                                                                                                                                                                                                                    |                                                         | `OnFindRegistration \| OnFindRegistration[] \| null` | OnFindMixin       |
-| `#armFind`           | private |                                                                                                                                                                                                                                                                                    |                                                         |                                                      | OnFindMixin       |
-
-### Events
-
-| Name             | Type          | Description                                 | Inherited From |
-| ---------------- | ------------- | ------------------------------------------- | -------------- |
-| `btu-card-ready` | `CustomEvent` | Fired after first render and initialization |                |
-
-### Attributes
-
-| Name            | Field        | Inherited From |
-| --------------- | ------------ | -------------- |
-| `heading`       | heading      |                |
-| `heading-level` | headingLevel |                |
-| `description`   | description  |                |
-| `compact`       | compact      |                |
-| `disabled`      | disabled     |                |
-| `href`          | href         |                |
-
-### CSS Properties
-
-| Name                     | Default | Description                                                                                           |
-| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
-| `--card-min-width`       |         | Minimum width of the card (default: 160px)                                                            |
-| `--card-background`      |         | Background color (default: var(--btu-theme-white))                                                    |
-| `--card-border`          |         | Border style (default: 1px solid gray-200)                                                            |
-| `--card-radius`          |         | Corner rounding (default: 8px)                                                                        |
-| `--card-img-ratio`       |         | Fixed aspect ratio for the thumbnail when an \`\<img>\` child is present (default: 16 / 9)            |
-| `--card-img-fit`         |         | Object-fit mode for the \`\<img>\` child thumbnail (default: contain)                                 |
-| `--card-icon-background` |         | Background color behind the composed icon (compact card and media-image fallback) (default: gray-100) |
-
-### Slots
-
-| Name               | Description                                                                     |
-| ------------------ | ------------------------------------------------------------------------------- |
-| `action`           | Intended for a single action in the top-right corner of the card.               |
-| `secondary-action` | Intended for a single action next to the title.                                 |
-| `fields`           | Intended for additional metadata fields displayed below the title & description |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name       | Declaration | Module                      | Package |
-| --------------------------- | ---------- | ----------- | --------------------------- | ------- |
-| `js`                        | `default`  | Card        | src/components/card/Card.ts |         |
-| `custom-element-definition` | `btu-card` | Card        | src/components/card/Card.ts |         |
+# `<btu-card>`
+
+A flexible content container for presenting and organizing information.
+
+The layout is driven by composition:
+
+- a direct `<img>` or `<btu-icon>` child renders the media layout (image area);
+  the icon shows in the image area as the fallback.
+- neither child renders a text-only card.
+- the `compact` attribute renders a quick-start tile; only a
+  featured `<btu-icon>` and the `action` slot are used.
+
+Composable children, all relocated into the layout automatically:
+- `<img>` — the thumbnail.
+- `<btu-icon>` — the featured icon (compact) or the media image fallback (shown
+  when no `<img>` is provided or it fails to load; defaults to `file-text`). The card sizes it.
+- `<btu-badge>` — a status badge.
+- `slot="action"` / `slot="secondary-action"` — a control in the top-right corner
+  or next to the title. A `<btu-checkbox>` there stays visible and toggles the
+  selected styling (listen for the bubbling `btu-checkbox-change` event); buttons
+  reveal on hover/focus.
+
+Cards are full-width by default and rely on the parent layout (grid or flex) to
+control their size.
+
+```js
+import '@brightspot/ui/components/card/Card.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-card--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `heading` | `heading` | `string` | `''` | Heading text displayed on the card. |
+| `heading-level` | `headingLevel` | `number` | `2` | Heading level (1-6) for the card heading element. Drives the semantic h1–h6 tag. Invalid values log a warning and fall back to the default (2). |
+| `description` | `description` | `string \| undefined` |  | Supporting body text. Truncated to 3 lines via CSS. |
+| `compact` | `compact` | `boolean` | `false` | Renders the card as a compact quick-start tile. Badge, image, fields, and secondary-action children are ignored in this case. |
+| `disabled` | `disabled` | `boolean` | `false` | Whether the card is disabled. |
+| `href` | `href` | `string \| undefined` |  | Navigation URL for the entire card surface. When set, the card renders as a link. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-card-ready` |  | Fired after first render and initialization |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `action` | Intended for a single action in the top-right corner of the card. |
+| `secondary-action` | Intended for a single action next to the title. |
+| `fields` | Intended for additional metadata fields displayed below the title & description |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--card-min-width` | Minimum width of the card (default: 160px) |
+| `--card-background` | Background color (default: var(--btu-theme-white)) |
+| `--card-border` | Border style (default: 1px solid gray-200) |
+| `--card-radius` | Corner rounding (default: 8px) |
+| `--card-img-ratio` | Fixed aspect ratio for the thumbnail when an `<img>` child is present (default: 16 / 9) |
+| `--card-img-fit` | Object-fit mode for the `<img>` child thumbnail (default: contain) |
+| `--card-icon-background` | Background color behind the composed icon (compact card and media-image fallback) (default: gray-100) |

package/docs/components/Checkbox.md

@@ -1,91 +1,49 @@
-# `src/components/checkbox/Checkbox.ts`:
-
-## class: `Checkbox`, `btu-checkbox`
-
-### Superclass
-
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
-
-### Mixins
-
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
-
-### Fields
-
-| Name                      | Privacy | Type                  | Default                                       | Description                                                                                                                                                                                                     | Inherited From |
-| ------------------------- | ------- | --------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `label`                   |         | `string \| undefined` |                                               | The text label displayed next to the checkbox.                                                                                                                                                                  |                |
-| `description`             |         | `string \| undefined` |                                               | Optional helper text displayed below the label.                                                                                                                                                                 |                |
-| `size`                    |         | `'sm' \| 'md'`        | `'sm'`                                        | Controls the scale of the checkbox and associated typography.                                                                                                                                                   |                |
-| `checked`                 |         | `boolean`             | `false`                                       | Whether the checkbox is currently selected.                                                                                                                                                                     |                |
-| `indeterminate`           |         | `boolean`             | `false`                                       | Whether the checkbox is in a partially selected state. Sets \`aria-checked='mixed'\`
and activates the native \`:indeterminate\` pseudo-class. Cleared automatically when
the user clicks the checkbox. |                |
-| `disabled`                |         | `boolean`             | `false`                                       | If true, the checkbox is non-interactive and visually muted.                                                                                                                                                    |                |
-| `invalid`                 |         | `boolean`             | `false`                                       | If true, displays error styling on the checkbox.                                                                                                                                                                |                |
-| `error`                   |         | `string \| undefined` |                                               | Error message text displayed below the checkbox when validation fails.
Setting this also activates error styling without needing to set invalid.                                                            |                |
-| `required`                |         | `boolean`             | `false`                                       | Marks the field as mandatory for form submission.                                                                                                                                                               |                |
-| `name`                    |         | `string \| undefined` |                                               | Name of the form control submitted with the form data.                                                                                                                                                          |                |
-| `value`                   |         | `string`              | `'on'`                                        | Value associated with the checkbox when submitted.                                                                                                                                                              |                |
-| `_userInitiated`          | private | `boolean`             | `false`                                       |                                                                                                                                                                                                                 |                |
-| `_initialClasses`         | private | `string[]`            | `[]`                                          |                                                                                                                                                                                                                 |                |
-| `_initialClassesCaptured` | private | `boolean`             | `false`                                       |                                                                                                                                                                                                                 |                |
-| `_descId`                 | private |                       | `` `checkbox-desc-${crypto.randomUUID()}` ``  |                                                                                                                                                                                                                 |                |
-| `_errorId`                | private |                       | `` `checkbox-error-${crypto.randomUUID()}` `` |                                                                                                                                                                                                                 |                |
-| `_handleClick`            | private |                       |                                               |                                                                                                                                                                                                                 |                |
-| `_describedBy`            | private | `string \| undefined` |                                               |                                                                                                                                                                                                                 |                |
-| `_iconSymbol`             | private | `'minus' \| 'check'`  |                                               |                                                                                                                                                                                                                 |                |
-
-### Methods
-
-| Name             | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `_onInputChange` | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `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 |
-
-### Events
-
-| Name                  | Type                                | Description                                                | Inherited From |
-| --------------------- | ----------------------------------- | ---------------------------------------------------------- | -------------- |
-| `btu-checkbox-ready`  | `CustomEvent`                       | Fired after the checkbox is first rendered and initialized |                |
-| `btu-checkbox-change` | `CustomEvent<{ checked: boolean }>` | Fired when the user toggles the checked state              |                |
-
-### Attributes
-
-| Name            | Field         | Inherited From |
-| --------------- | ------------- | -------------- |
-| `label`         | label         |                |
-| `description`   | description   |                |
-| `size`          | size          |                |
-| `checked`       | checked       |                |
-| `indeterminate` | indeterminate |                |
-| `disabled`      | disabled      |                |
-| `invalid`       | invalid       |                |
-| `error`         | error         |                |
-| `required`      | required      |                |
-| `name`          | name          |                |
-| `value`         | value         |                |
-
-### CSS Properties
-
-| Name                       | Default | Description                                                                                                                                                                                      |
-| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `--checkbox-color-primary` |         | Background and border color when checked or indeterminate, and tinted background/border on unchecked hover (default: oklch(var(--btu-theme-primary-700)))                                        |
-| `--checkbox-color-border`  |         | Border color in the unchecked state (default: oklch(var(--btu-theme-gray-300)))                                                                                                                  |
-| `--checkbox-color-error`   |         | Border and text color in the error state (default: oklch(var(--btu-theme-error-600)))                                                                                                            |
-| `--checkbox-border-radius` |         | Corner rounding of the checkbox square (default: 4px)                                                                                                                                            |
-| `--checkbox-label-spacing` |         | Distance between the checkbox and the label (default: 0.75rem)                                                                                                                                   |
-| `--checkbox-box-size`      |         | \[Internal] Width and height of the checkbox square, set by the size variant (sm: 1rem, md: 1.25rem). Use the \`size\` attribute instead of overriding directly — the icon must scale in tandem. |
-| `--checkbox-icon-size`     |         | \[Internal] Width and height of the icon inside the box, set by the size variant (sm: 0.75rem, md: 0.875rem). Use the \`size\` attribute instead of overriding directly.                         |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name           | Declaration | Module                              | Package |
-| --------------------------- | -------------- | ----------- | ----------------------------------- | ------- |
-| `js`                        | `default`      | Checkbox    | src/components/checkbox/Checkbox.ts |         |
-| `custom-element-definition` | `btu-checkbox` | Checkbox    | src/components/checkbox/Checkbox.ts |         |
+# `<btu-checkbox>`
+
+A checkbox component for selecting one or more options from a set.
+
+Uses a hidden native checkbox internally for accessibility and form
+participation. Styled via the `btu-checkbox` Tailwind plugin classes.
+The component manages its own `className` — do not modify it externally
+after initialization (classes present at connection time are preserved).
+
+```js
+import '@brightspot/ui/components/checkbox/Checkbox.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-checkbox--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string \| undefined` |  | The text label displayed next to the checkbox. |
+| `description` | `description` | `string \| undefined` |  | Optional helper text displayed below the label. |
+| `size` | `size` | `'sm' \| 'md'` | `'sm'` | Controls the scale of the checkbox and associated typography. |
+| `checked` | `checked` | `boolean` | `false` | Whether the checkbox is currently selected. |
+| `indeterminate` | `indeterminate` | `boolean` | `false` | Whether the checkbox is in a partially selected state. Sets `aria-checked='mixed'` and activates the native `:indeterminate` pseudo-class. Cleared automatically when the user clicks the checkbox. |
+| `disabled` | `disabled` | `boolean` | `false` | If true, the checkbox is non-interactive and visually muted. |
+| `invalid` | `invalid` | `boolean` | `false` | If true, displays error styling on the checkbox. |
+| `error` | `error` | `string \| undefined` |  | Error message text displayed below the checkbox when validation fails. Setting this also activates error styling without needing to set invalid. |
+| `required` | `required` | `boolean` | `false` | Marks the field as mandatory for form submission. |
+| `name` | `name` | `string \| undefined` |  | Name of the form control submitted with the form data. |
+| `value` | `value` | `string` | `'on'` | Value associated with the checkbox when submitted. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-checkbox-ready` |  | Fired after the checkbox is first rendered and initialized |
+| `btu-checkbox-change` | `{ checked: boolean }` | Fired when the user toggles the checked state |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--checkbox-color-primary` | Background and border color when checked or indeterminate, and tinted background/border on unchecked hover (default: oklch(var(--btu-theme-primary-700))) |
+| `--checkbox-color-border` | Border color in the unchecked state (default: oklch(var(--btu-theme-gray-300))) |
+| `--checkbox-color-error` | Border and text color in the error state (default: oklch(var(--btu-theme-error-600))) |
+| `--checkbox-border-radius` | Corner rounding of the checkbox square (default: 4px) |
+| `--checkbox-label-spacing` | Distance between the checkbox and the label (default: 0.75rem) |
+| `--checkbox-box-size` | [Internal] Width and height of the checkbox square, set by the size variant (sm: 1rem, md: 1.25rem). Use the `size` attribute instead of overriding directly — the icon must scale in tandem. |
+| `--checkbox-icon-size` | [Internal] Width and height of the icon inside the box, set by the size variant (sm: 0.75rem, md: 0.875rem). Use the `size` attribute instead of overriding directly. |