@chromvoid/uikit 0.1.0

package/specs/components/button.md

@@ -0,0 +1,227 @@
+# cv-button
+
+Interactive element that triggers an action or toggles a pressed state.
+
+**Headless:** [`createButton`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/button.md)
+
+## Anatomy
+
+```
+<cv-button> (host)
+└── <button part="base" type="button" role="button">
+    ├── <span part="spinner" aria-hidden="true">   ← only when [loading]
+    ├── <span part="prefix">
+    │   └── <slot name="prefix">
+    ├── <span part="label">
+    │   └── <slot>
+    └── <span part="suffix">
+        └── <slot name="suffix">
+```
+
+## Attributes
+
+| Attribute  | Type    | Default     | Description                                                   |
+| ---------- | ------- | ----------- | ------------------------------------------------------------- |
+| `disabled` | Boolean | `false`     | Prevents interaction                                          |
+| `toggle`   | Boolean | `false`     | Enables toggle (pressed) behavior                             |
+| `pressed`  | Boolean | `false`     | Pressed state (only meaningful when `toggle` is `true`)       |
+| `loading`  | Boolean | `false`     | Shows spinner and blocks interaction                          |
+| `variant`  | String  | `"default"` | Visual variant: `default` \| `primary` \| `danger` \| `ghost` |
+| `outline`  | Boolean | `false`     | Outlined appearance (transparent background, visible border)  |
+| `pill`     | Boolean | `false`     | Fully rounded edges (`border-radius: 999px`)                  |
+| `size`     | String  | `"medium"`  | Size: `small` \| `medium` \| `large`                          |
+| `type`     | String  | `"button"`  | Form action type: `button` \| `submit` \| `reset`             |
+
+## Form Behavior
+
+- `type="button"`: no form action.
+- `type="submit"`: triggers form submission for nearest form owner.
+- `type="reset"`: triggers form reset for nearest form owner.
+- Form owner resolution order:
+  1. host `[form="..."]` attribute by element id
+  2. nearest ancestor `form` via `closest('form')`
+- If `disabled` or `loading` is active, submit/reset actions are blocked.
+
+## Variants
+
+| Variant   | Description                                                     |
+| --------- | --------------------------------------------------------------- |
+| `default` | Default filled style with surface background and border         |
+| `primary` | Primary-tinted background and border using `--cv-color-primary` |
+| `danger`  | Danger-tinted background and border using `--cv-color-danger`   |
+| `ghost`   | Transparent background and border                               |
+
+The `outline` boolean modifier can be combined with any variant to produce an outlined appearance (transparent background, visible border tinted by variant color).
+
+## Sizes
+
+| Size     | `--cv-button-min-height` | `--cv-button-padding-inline` | `--cv-button-padding-block` | `--cv-button-font-size`          |
+| -------- | ------------------------ | ---------------------------- | --------------------------- | -------------------------------- |
+| `small`  | `30px`                   | `var(--cv-space-2, 8px)`     | `var(--cv-space-1, 4px)`    | `var(--cv-font-size-sm, 13px)`   |
+| `medium` | `36px`                   | `var(--cv-space-3, 12px)`    | `var(--cv-space-2, 8px)`    | `var(--cv-font-size-base, 14px)` |
+| `large`  | `42px`                   | `var(--cv-space-4, 16px)`    | `var(--cv-space-2, 8px)`    | `var(--cv-font-size-md, 16px)`   |
+
+## Slots
+
+| Slot        | Description                  |
+| ----------- | ---------------------------- |
+| `(default)` | Button label                 |
+| `prefix`    | Icon or element before label |
+| `suffix`    | Icon or element after label  |
+
+## CSS Parts
+
+| Part      | Element    | Description                                              |
+| --------- | ---------- | -------------------------------------------------------- |
+| `base`    | `<button>` | Root interactive element with `role="button"`            |
+| `label`   | `<span>`   | Wrapper around the default slot                          |
+| `prefix`  | `<span>`   | Wrapper around the `prefix` slot                         |
+| `suffix`  | `<span>`   | Wrapper around the `suffix` slot                         |
+| `spinner` | `<span>`   | Loading spinner (rendered only when `loading` is `true`) |
+
+## CSS Custom Properties
+
+| Property                     | Default                          | Description                          |
+| ---------------------------- | -------------------------------- | ------------------------------------ |
+| `--cv-button-min-height`     | `36px`                           | Minimum block size of the button     |
+| `--cv-button-padding-inline` | `var(--cv-space-3, 12px)`        | Horizontal padding                   |
+| `--cv-button-padding-block`  | `var(--cv-space-2, 8px)`         | Vertical padding                     |
+| `--cv-button-border-radius`  | `var(--cv-radius-sm, 6px)`       | Border radius for button shape       |
+| `--cv-button-gap`            | `var(--cv-space-2, 8px)`         | Spacing between button content parts |
+| `--cv-button-font-size`      | `var(--cv-font-size-base, 14px)` | Font size of button content          |
+
+Additionally, component styles depend on theme tokens through fallback values:
+
+| Theme Property         | Default   | Description                          |
+| ---------------------- | --------- | ------------------------------------ |
+| `--cv-color-border`    | `#2a3245` | Base border color                    |
+| `--cv-color-surface`   | `#141923` | Surface background color             |
+| `--cv-color-text`      | `#e8ecf6` | Default text color                   |
+| `--cv-color-primary`   | `#65d7ff` | Primary accent color                 |
+| `--cv-color-danger`    | `#ff7d86` | Danger accent color                  |
+| `--cv-duration-fast`   | `120ms`   | Transition duration                  |
+| `--cv-easing-standard` | `ease`    | Transition timing function           |
+| `--cv-radius-sm`       | `6px`     | Base radius used for button fallback |
+| `--cv-space-1`         | `4px`     | Small spacing scale fallback         |
+| `--cv-space-2`         | `8px`     | Medium spacing scale fallback        |
+| `--cv-space-3`         | `12px`    | Medium-large spacing scale fallback  |
+| `--cv-space-4`         | `16px`    | Large spacing scale fallback         |
+
+## Visual States
+
+| Host selector                | Description                                                       |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `:host([disabled])`          | Reduced opacity (`0.55`), `cursor: not-allowed`                   |
+| `:host([pressed])`           | Primary-tinted background (per variant)                           |
+| `:host([loading])`           | Shows spinner, label reduced opacity (`0.72`), `cursor: progress` |
+| `:host([variant="default"])` | Default surface background with border                            |
+| `:host([variant="primary"])` | Primary-tinted background and border                              |
+| `:host([variant="danger"])`  | Danger-tinted background and border                               |
+| `:host([variant="ghost"])`   | Transparent background and border                                 |
+| `:host([outline])`           | Transparent background, visible border (tinted by variant)        |
+| `:host([pill])`              | Fully rounded edges                                               |
+| `:host([size="small"])`      | Small size overrides                                              |
+| `:host([size="large"])`      | Large size overrides                                              |
+
+## Reactive State Mapping
+
+`cv-button` is a visual adapter over headless `createButton`.
+
+| UIKit Property | Direction     | Headless Binding                                          |
+| -------------- | ------------- | --------------------------------------------------------- |
+| `disabled`     | attr → action | `actions.setDisabled(value)`                              |
+| `loading`      | attr → action | `actions.setLoading(value)`                               |
+| `pressed`      | attr → action | `actions.setPressed(value)`                               |
+| `toggle`       | attr → option | passed as `isPressed` presence in `createButton(options)` |
+
+| Headless State       | Direction    | DOM Reflection              |
+| -------------------- | ------------ | --------------------------- |
+| `state.isDisabled()` | state → attr | `[disabled]` host attribute |
+| `state.isLoading()`  | state → attr | `[loading]` host attribute  |
+| `state.isPressed()`  | state → attr | `[pressed]` host attribute  |
+
+- `contracts.getButtonProps()` is spread onto the inner `[part="base"]` element to apply `role`, `aria-disabled`, `aria-busy`, `aria-pressed`, `tabindex`, and keyboard/click handlers.
+- UIKit dispatches `cv-input` and `cv-change` events by observing `isPressed` changes triggered by user activation (not by controlled `setPressed`).
+- UIKit does not own activation or toggle logic; headless state is the source of truth.
+
+## Events
+
+| Event       | Detail                                | Description                                           |
+| ----------- | ------------------------------------- | ----------------------------------------------------- |
+| `cv-input`  | `{pressed: boolean, toggle: boolean}` | Fires on activation in toggle mode only               |
+| `cv-change` | `{pressed: boolean}`                  | Fires when `pressed` state changes (toggle mode only) |
+
+Normal (non-toggle) buttons rely on the native `click` event.
+
+## Legacy Button Migration Mapping
+
+### Variant mapping
+
+- `brand` -> `primary`
+- `neutral` -> `default`
+- `secondary` -> `default`
+- `plain` -> `ghost`
+- `text` -> `ghost`
+- `primary` -> `primary`
+- `danger` -> `danger`
+- `ghost` -> `ghost`
+
+### Slot mapping
+
+- `slot="start"` -> `slot="prefix"`
+- `slot="end"` -> `slot="suffix"`
+
+## Usage
+
+```html
+<cv-button>Click me</cv-button>
+
+<cv-button variant="primary">Save</cv-button>
+
+<cv-button variant="danger" outline>Delete</cv-button>
+
+<cv-button variant="primary" outline size="small">Small outline</cv-button>
+
+<cv-button pill>Rounded</cv-button>
+
+<cv-button variant="danger" loading>Deleting…</cv-button>
+
+<cv-button toggle pressed>Bold</cv-button>
+
+<cv-button>
+  <svg
+    slot="prefix"
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <path d="M12 5v14"></path>
+    <path d="M5 12h14"></path>
+  </svg>
+  Add item
+</cv-button>
+
+<cv-button>
+  Settings
+  <svg
+    slot="suffix"
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <path d="m9 18 6-6-6-6"></path>
+  </svg>
+</cv-button>
+```

package/specs/components/callout.md

@@ -0,0 +1,153 @@
+# cv-callout
+
+Static supplementary content block that highlights important information using `role="note"`. Unlike `cv-alert`, a callout is not a live region and does not announce dynamically.
+
+**Headless:** [`createCallout`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/callout.md)
+
+## Anatomy
+
+```
+<cv-callout> (host)
+└── <div part="base" role="note">
+    ├── <span part="icon">
+    │   └── <slot name="icon">
+    ├── <span part="message">
+    │   └── <slot>
+    └── <button part="close-button" aria-label="Dismiss">   ← only when [closable]
+```
+
+## Attributes
+
+| Attribute  | Type    | Default  | Description                                                                         |
+| ---------- | ------- | -------- | ----------------------------------------------------------------------------------- |
+| `variant`  | String  | `"info"` | Visual variant: `"info"` \| `"success"` \| `"warning"` \| `"danger"` \| `"neutral"` |
+| `closable` | Boolean | `false`  | Renders a dismiss button and enables the `cv-close` event                           |
+| `open`     | Boolean | `true`   | Controls visibility of the callout                                                  |
+
+## Variants
+
+| Variant   | Description                                                     |
+| --------- | --------------------------------------------------------------- |
+| `info`    | Default informational style using `--cv-color-info`             |
+| `success` | Success-tinted background and border using `--cv-color-success` |
+| `warning` | Warning-tinted background and border using `--cv-color-warning` |
+| `danger`  | Danger-tinted background and border using `--cv-color-danger`   |
+| `neutral` | Muted style with surface background and border                  |
+
+## Slots
+
+| Slot        | Description                                    |
+| ----------- | ---------------------------------------------- |
+| `(default)` | Main content (projected into the message area) |
+| `icon`      | Leading icon area before the message content   |
+
+## CSS Parts
+
+| Part           | Element    | Description                                                                          |
+| -------------- | ---------- | ------------------------------------------------------------------------------------ |
+| `base`         | `<div>`    | Outer container with `role="note"`; receives headless `getCalloutProps()` attributes |
+| `icon`         | `<span>`   | Wrapper around the `icon` slot                                                       |
+| `message`      | `<span>`   | Wrapper around the default slot                                                      |
+| `close-button` | `<button>` | Dismiss button (rendered only when `closable` is `true`)                             |
+
+## CSS Custom Properties
+
+| Property                           | Default                                     | Description                                 |
+| ---------------------------------- | ------------------------------------------- | ------------------------------------------- |
+| `--cv-callout-padding-inline`      | `var(--cv-space-3, 12px)`                   | Horizontal padding                          |
+| `--cv-callout-padding-block`       | `var(--cv-space-3, 12px)`                   | Vertical padding                            |
+| `--cv-callout-gap`                 | `var(--cv-space-2, 8px)`                    | Gap between icon, message, and close button |
+| `--cv-callout-border-radius`       | `var(--cv-radius-sm, 6px)`                  | Border radius                               |
+| `--cv-callout-border-color`        | `var(--cv-color-border, #2a3245)`           | Border color (overridden per variant)       |
+| `--cv-callout-background`          | `var(--cv-color-surface-elevated, #1d2432)` | Background color (overridden per variant)   |
+| `--cv-callout-color`               | `var(--cv-color-text, #e8ecf6)`             | Text color                                  |
+| `--cv-callout-icon-color`          | `currentColor`                              | Icon slot color (overridden per variant)    |
+| `--cv-callout-font-size`           | `var(--cv-font-size-base, 14px)`            | Font size of callout content                |
+| `--cv-callout-transition-duration` | `var(--cv-duration-fast, 120ms)`            | Transition duration for show/hide           |
+| `--cv-callout-transition-easing`   | `var(--cv-easing-standard, ease)`           | Transition timing function                  |
+
+Additionally, component styles depend on theme tokens through fallback values:
+
+| Theme Property                | Default   | Description                         |
+| ----------------------------- | --------- | ----------------------------------- |
+| `--cv-color-border`           | `#2a3245` | Base border color                   |
+| `--cv-color-surface-elevated` | `#1d2432` | Elevated surface background color   |
+| `--cv-color-text`             | `#e8ecf6` | Default text color                  |
+| `--cv-color-info`             | `#65d7ff` | Info accent color                   |
+| `--cv-color-success`          | `#5beba0` | Success accent color                |
+| `--cv-color-warning`          | `#ffc857` | Warning accent color                |
+| `--cv-color-danger`           | `#ff7d86` | Danger accent color                 |
+| `--cv-duration-fast`          | `120ms`   | Transition duration                 |
+| `--cv-easing-standard`        | `ease`    | Transition timing function          |
+| `--cv-radius-sm`              | `6px`     | Base radius fallback                |
+| `--cv-space-2`                | `8px`     | Medium spacing scale fallback       |
+| `--cv-space-3`                | `12px`    | Medium-large spacing scale fallback |
+
+## Visual States
+
+| Host selector                | Description                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------ |
+| `:host([open])`              | Visible state; callout is rendered and visible                                 |
+| `:host(:not([open]))`        | Hidden state; callout is hidden (e.g., `display: none` or fade-out transition) |
+| `:host([variant="info"])`    | Info-tinted background and border (default)                                    |
+| `:host([variant="success"])` | Success-tinted background and border                                           |
+| `:host([variant="warning"])` | Warning-tinted background and border                                           |
+| `:host([variant="danger"])`  | Danger-tinted background and border                                            |
+| `:host([variant="neutral"])` | Muted surface background with border                                           |
+| `:host([closable])`          | Close button is rendered in the template                                       |
+
+## Reactive State Mapping
+
+`cv-callout` is a visual adapter over headless `createCallout`.
+
+| UIKit Property | Direction      | Headless Binding                                   |
+| -------------- | -------------- | -------------------------------------------------- |
+| `variant`      | attr -> action | `actions.setVariant(value)`                        |
+| `closable`     | attr -> action | `actions.setClosable(value)`                       |
+| `open`         | attr -> action | `actions.show()` / programmatic visibility control |
+
+| Headless State     | Direction     | DOM Reflection              |
+| ------------------ | ------------- | --------------------------- |
+| `state.variant()`  | state -> attr | `[variant]` host attribute  |
+| `state.closable()` | state -> attr | `[closable]` host attribute |
+| `state.open()`     | state -> attr | `[open]` host attribute     |
+
+- `contracts.getCalloutProps()` is spread onto the inner `[part="base"]` element to apply `id`, `role="note"`, and `data-variant`.
+- `contracts.getCloseButtonProps()` is spread onto the inner `[part="close-button"]` element to apply `id`, `role="button"`, `tabindex="0"`, `aria-label="Dismiss"`, and `onClick` handler. The close button is only rendered when `closable` is `true`.
+- UIKit dispatches `cv-close` when the headless `actions.close()` transitions `open` from `true` to `false`.
+- UIKit does not own ARIA logic or close behavior; headless state is the source of truth.
+- The callout root is not focusable; no `tabindex` is applied to the root element.
+
+## Events
+
+| Event      | Detail      | Description                                                                          |
+| ---------- | ----------- | ------------------------------------------------------------------------------------ |
+| `cv-close` | `undefined` | Fires when the callout is dismissed via the close button (`closable` must be `true`) |
+
+No `cv-input` or `cv-change` events are emitted. The callout has no user-modifiable state; closing is a one-way action.
+
+## Usage
+
+```html
+<cv-callout>This is an informational callout.</cv-callout>
+
+<cv-callout variant="success">Operation completed successfully.</cv-callout>
+
+<cv-callout variant="warning">Please review before continuing.</cv-callout>
+
+<cv-callout variant="danger">This action cannot be undone.</cv-callout>
+
+<cv-callout variant="neutral">Additional context for this section.</cv-callout>
+
+<cv-callout variant="warning" closable> This warning can be dismissed. </cv-callout>
+
+<cv-callout variant="info">
+  <icon-info slot="icon"></icon-info>
+  Callout with a leading icon.
+</cv-callout>
+
+<cv-callout variant="danger" closable>
+  <icon-alert-triangle slot="icon"></icon-alert-triangle>
+  Critical issue detected. Please take action.
+</cv-callout>
+```

package/specs/components/card.md

@@ -0,0 +1,192 @@
+# cv-card
+
+Visual container that groups related content into a cohesive unit, with an optional expandable variant that follows the disclosure pattern to show/hide body content.
+
+**Headless:** [`createCard`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/card.md)
+
+## Anatomy
+
+```
+<cv-card> (host)
+└── <div part="base">
+    ├── <div part="image">
+    │   └── <slot name="image">
+    ├── <div part="header">          ← trigger when [expandable]
+    │   ├── <slot name="header">
+    │   └── <span part="indicator">  ← only when [expandable], chevron/arrow
+    ├── <div part="body">            ← collapsible when [expandable]
+    │   └── <slot>
+    └── <div part="footer">
+        └── <slot name="footer">
+```
+
+## Attributes
+
+| Attribute    | Type    | Default      | Description                                                        |
+| ------------ | ------- | ------------ | ------------------------------------------------------------------ |
+| `variant`    | String  | `"elevated"` | Visual variant: `elevated` \| `outlined` \| `filled`               |
+| `expandable` | Boolean | `false`      | Enables disclosure behavior (expand/collapse body)                 |
+| `expanded`   | Boolean | `false`      | Expanded state (only meaningful when `expandable` is `true`)       |
+| `disabled`   | Boolean | `false`      | Prevents interaction (only meaningful when `expandable` is `true`) |
+
+## Variants
+
+| Variant    | Description                                                 |
+| ---------- | ----------------------------------------------------------- |
+| `elevated` | Default style with box shadow for a raised appearance       |
+| `outlined` | Transparent background with a visible border                |
+| `filled`   | Solid surface background without shadow or prominent border |
+
+Variants are CSS-only concerns and carry no headless state. They are mutually exclusive and selected via the `variant` attribute.
+
+## Slots
+
+| Slot        | Description                                              |
+| ----------- | -------------------------------------------------------- |
+| `image`     | Optional image or media displayed at the top of the card |
+| `header`    | Card header content (title, subtitle, actions)           |
+| `(default)` | Main body content of the card                            |
+| `footer`    | Card footer content (actions, metadata)                  |
+
+## CSS Parts
+
+| Part        | Element  | Description                                                               |
+| ----------- | -------- | ------------------------------------------------------------------------- |
+| `base`      | `<div>`  | Root wrapper element                                                      |
+| `image`     | `<div>`  | Container for the `image` slot                                            |
+| `header`    | `<div>`  | Header area; acts as the disclosure trigger when `expandable` is `true`   |
+| `indicator` | `<span>` | Expand/collapse indicator icon; rendered only when `expandable` is `true` |
+| `body`      | `<div>`  | Body content area; collapsible region when `expandable` is `true`         |
+| `footer`    | `<div>`  | Footer area                                                               |
+
+## CSS Custom Properties
+
+| Property                         | Default                                                          | Description                                            |
+| -------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
+| `--cv-card-padding`              | `var(--cv-space-4, 16px)`                                        | Inner padding for card sections (header, body, footer) |
+| `--cv-card-border-radius`        | `var(--cv-radius-md, 8px)`                                       | Border radius of the card                              |
+| `--cv-card-border-color`         | `var(--cv-color-border, #2a3245)`                                | Border color (primarily for `outlined` variant)        |
+| `--cv-card-background`           | `var(--cv-color-surface, #141923)`                               | Background color of the card                           |
+| `--cv-card-shadow`               | `0 1px 3px rgba(0, 0, 0, 0.24)`                                  | Box shadow (primarily for `elevated` variant)          |
+| `--cv-card-gap`                  | `var(--cv-space-0, 0px)`                                         | Spacing between card sections                          |
+| `--cv-card-indicator-size`       | `var(--cv-space-4, 16px)`                                        | Size of the expand/collapse indicator icon             |
+| `--cv-card-indicator-transition` | `var(--cv-duration-fast, 120ms) var(--cv-easing-standard, ease)` | Transition for indicator rotation                      |
+
+Additionally, component styles depend on theme tokens through fallback values:
+
+| Theme Property         | Default   | Description                        |
+| ---------------------- | --------- | ---------------------------------- |
+| `--cv-color-border`    | `#2a3245` | Base border color                  |
+| `--cv-color-surface`   | `#141923` | Surface background color           |
+| `--cv-color-text`      | `#e8ecf6` | Default text color                 |
+| `--cv-duration-fast`   | `120ms`   | Transition duration                |
+| `--cv-easing-standard` | `ease`    | Transition timing function         |
+| `--cv-radius-md`       | `8px`     | Base radius used for card fallback |
+| `--cv-space-0`         | `0px`     | Zero spacing scale fallback        |
+| `--cv-space-4`         | `16px`    | Large spacing scale fallback       |
+
+## Visual States
+
+| Host selector                 | Description                                                                     |
+| ----------------------------- | ------------------------------------------------------------------------------- |
+| `:host([variant="elevated"])` | Applies box shadow via `--cv-card-shadow`; no visible border                    |
+| `:host([variant="outlined"])` | Applies visible border via `--cv-card-border-color`; no shadow                  |
+| `:host([variant="filled"])`   | Solid background; no shadow, subtle or no border                                |
+| `:host([expandable])`         | Renders indicator in header; header becomes interactive trigger                 |
+| `:host([expanded])`           | Body content visible; indicator rotated to open position                        |
+| `:host([disabled])`           | Reduced opacity (`0.55`), `cursor: not-allowed` on trigger; interaction blocked |
+
+## Reactive State Mapping
+
+`cv-card` is a visual adapter over headless `createCard`.
+
+### UIKit Property -> Headless Binding (input direction)
+
+| UIKit Property | Direction      | Headless Binding                                                                                                            |
+| -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `expandable`   | attr -> option | passed as `isExpandable` in `createCard(options)`                                                                           |
+| `expanded`     | attr -> option | passed as `isExpanded` in `createCard(options)`; updates via `actions.toggle()` / `actions.expand()` / `actions.collapse()` |
+| `disabled`     | attr -> action | `actions.setDisabled(value)`                                                                                                |
+
+### Headless State -> DOM Reflection (output direction)
+
+| Headless State         | Direction     | DOM Reflection                |
+| ---------------------- | ------------- | ----------------------------- |
+| `state.isExpandable()` | state -> attr | `[expandable]` host attribute |
+| `state.isExpanded()`   | state -> attr | `[expanded]` host attribute   |
+| `state.isDisabled()`   | state -> attr | `[disabled]` host attribute   |
+
+### Contract Spreading
+
+| Contract                      | Target Element    | Notes                                                                                                                                                    |
+| ----------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contracts.getCardProps()`    | `[part="base"]`   | Spread as attributes on the card root element                                                                                                            |
+| `contracts.getTriggerProps()` | `[part="header"]` | Spread onto the header element when `isExpandable` is `true`; provides `role="button"`, `aria-expanded`, `aria-controls`, `tabindex`, and event handlers |
+| `contracts.getContentProps()` | `[part="body"]`   | Spread onto the body element when `isExpandable` is `true`; provides `id`, `role="region"`, `aria-labelledby`, `hidden`                                  |
+
+### Boundary
+
+- UIKit dispatches `cv-input` and `cv-change` events by observing `isExpanded` changes triggered by user activation (not by controlled attribute updates).
+- UIKit does not own toggle, expand/collapse, or keyboard logic; headless state is the source of truth.
+- Visual variants (`elevated`, `outlined`, `filled`) are CSS-only; no headless state involved.
+- Slot layout, image positioning, indicator rendering, and CSS transitions are UIKit rendering concerns.
+
+## Events
+
+| Event       | Detail                | Description                                                               |
+| ----------- | --------------------- | ------------------------------------------------------------------------- |
+| `cv-input`  | `{expanded: boolean}` | Fires when user toggles the expanded state (click or keyboard on trigger) |
+| `cv-change` | `{expanded: boolean}` | Fires when the expanded state commits after user interaction              |
+
+Events only fire when `expandable` is `true` and the state change is triggered by user action (not programmatic attribute changes). Normal (non-expandable) cards do not emit these events.
+
+## Usage
+
+```html
+<!-- Static elevated card (default) -->
+<cv-card>
+  <span slot="header">Card Title</span>
+  Main body content goes here.
+  <span slot="footer">Footer actions</span>
+</cv-card>
+
+<!-- Outlined card with image -->
+<cv-card variant="outlined">
+  <img slot="image" src="hero.jpg" alt="Hero image" />
+  <span slot="header">Article Title</span>
+  Article preview text.
+</cv-card>
+
+<!-- Filled card -->
+<cv-card variant="filled">
+  <span slot="header">Settings</span>
+  Configuration content.
+</cv-card>
+
+<!-- Expandable card (collapsed by default) -->
+<cv-card expandable>
+  <span slot="header">Expandable Section</span>
+  This content is hidden until the header is clicked.
+</cv-card>
+
+<!-- Expandable card (expanded by default) -->
+<cv-card expandable expanded>
+  <span slot="header">Details</span>
+  This content is visible on initial render.
+  <span slot="footer">Last updated: today</span>
+</cv-card>
+
+<!-- Expandable card (disabled) -->
+<cv-card expandable disabled>
+  <span slot="header">Locked Section</span>
+  This content cannot be toggled by the user.
+</cv-card>
+
+<!-- Expandable card with image and all slots -->
+<cv-card expandable variant="outlined">
+  <img slot="image" src="preview.jpg" alt="Preview" />
+  <span slot="header">Full Example</span>
+  Body content with detailed information.
+  <span slot="footer">Action buttons here</span>
+</cv-card>
+```