@chromvoid/uikit 0.1.0

package/specs/components/toast.md

@@ -0,0 +1,198 @@
+# cv-toast-region
+
+Container that manages a queue of toast notifications with positioning, stacking layout, and auto-dismiss lifecycle.
+
+**Headless:** [`createToast`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/toast.md)
+
+## Anatomy
+
+```
+<cv-toast-region> (host)
+└── <section part="base" role="region" aria-live="polite" aria-atomic="false">
+    ├── <cv-toast part="item" role="status|alert" data-level="info">
+    ├── <cv-toast part="item" role="alert" data-level="error">
+    └── …
+```
+
+## Attributes
+
+| Attribute     | Type   | Default     | Description                                                                                                              |
+| ------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `position`    | String | `"top-end"` | Positioning of the region: `top-start` \| `top-center` \| `top-end` \| `bottom-start` \| `bottom-center` \| `bottom-end` |
+| `max-visible` | Number | `3`         | Maximum number of toasts displayed simultaneously                                                                        |
+
+## Slots
+
+| Slot     | Description                                                                     |
+| -------- | ------------------------------------------------------------------------------- |
+| _(none)_ | Content is rendered programmatically from the toast queue; no user-facing slots |
+
+## CSS Parts
+
+| Part   | Element     | Description                                              |
+| ------ | ----------- | -------------------------------------------------------- |
+| `base` | `<section>` | Root region element with `role="region"` and `aria-live` |
+
+## CSS Custom Properties
+
+| Property                      | Default                   | Description                       |
+| ----------------------------- | ------------------------- | --------------------------------- |
+| `--cv-toast-region-gap`       | `var(--cv-space-2, 8px)`  | Spacing between stacked toasts    |
+| `--cv-toast-region-inset`     | `var(--cv-space-4, 16px)` | Distance from viewport edges      |
+| `--cv-toast-region-z-index`   | `9999`                    | Stacking order above page content |
+| `--cv-toast-region-max-width` | `420px`                   | Maximum width of the toast region |
+
+## Visual States
+
+| Host selector                       | Description                         |
+| ----------------------------------- | ----------------------------------- |
+| `:host([position="top-start"])`     | Region fixed to top-left            |
+| `:host([position="top-center"])`    | Region fixed to top-center          |
+| `:host([position="top-end"])`       | Region fixed to top-right (default) |
+| `:host([position="bottom-start"])`  | Region fixed to bottom-left         |
+| `:host([position="bottom-center"])` | Region fixed to bottom-center       |
+| `:host([position="bottom-end"])`    | Region fixed to bottom-right        |
+
+## Events
+
+| Event      | Detail           | Description                                                                     |
+| ---------- | ---------------- | ------------------------------------------------------------------------------- |
+| `cv-close` | `{ id: string }` | Fires when a toast is removed from the queue (auto-dismiss or explicit dismiss) |
+
+## Reactive State Mapping
+
+`cv-toast-region` is a visual adapter over headless `createToast`.
+
+| UIKit Property | Direction     | Headless Binding                                                                                          |
+| -------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
+| `max-visible`  | attr → option | Passed as `maxVisible` in `createToast(options)`                                                          |
+| _(controller)_ | property      | `createToastController()` wraps `createToast()` and exposes `push`, `dismiss`, `clear`, `pause`, `resume` |
+
+| Headless State         | Direction        | DOM Reflection                                                              |
+| ---------------------- | ---------------- | --------------------------------------------------------------------------- |
+| `state.visibleItems()` | state → render   | Drives the rendered list of `cv-toast` items                                |
+| `state.isPaused()`     | state → internal | Tracked internally; toggled by `mouseenter`/`mouseleave` on `[part="base"]` |
+
+- `contracts.getRegionProps()` is spread onto the inner `[part="base"]` element to apply `id`, `role="region"`, `aria-live`, and `aria-atomic`.
+- `mouseenter` on `[part="base"]` calls `actions.pause()`; `mouseleave` calls `actions.resume()`.
+- UIKit tracks the previous set of toast IDs across renders and dispatches a `cv-close` event for each ID that disappears from the queue.
+- UIKit does not own queue logic, timer management, or visibility slicing; headless state is the source of truth.
+
+## Usage
+
+```html
+<!-- Basic usage (imperative API via controller) -->
+<cv-toast-region></cv-toast-region>
+
+<script>
+  const region = document.querySelector('cv-toast-region')
+  region.controller.push({message: 'File saved', level: 'success'})
+  region.controller.push({message: 'Connection lost', level: 'error', durationMs: 0})
+</script>
+
+<!-- Positioned bottom-center -->
+<cv-toast-region position="bottom-center"></cv-toast-region>
+```
+
+## Child Elements
+
+### cv-toast
+
+Individual toast notification item rendered within `cv-toast-region`. Displays a message with severity-based styling, an optional icon, and an optional dismiss button.
+
+#### Anatomy
+
+```
+<cv-toast> (host)
+└── <div part="base" role="status|alert" data-level="info">
+    ├── <span part="icon">
+    │   └── <slot name="icon">         ← severity icon
+    ├── <div part="content">
+    │   └── <span part="label">
+    │       └── <slot>                  ← message text
+    └── <button part="dismiss">        ← only when closable
+```
+
+#### Attributes
+
+| Attribute  | Type    | Default  | Description                                                       |
+| ---------- | ------- | -------- | ----------------------------------------------------------------- |
+| `level`    | String  | `"info"` | Severity level: `info` \| `success` \| `warning` \| `error`       |
+| `closable` | Boolean | `true`   | Whether the dismiss button is shown                               |
+| `toast-id` | String  | `""`     | Identifier for the toast, included in the `cv-close` event detail |
+
+#### Slots
+
+| Slot        | Description                                             |
+| ----------- | ------------------------------------------------------- |
+| `(default)` | Message text content                                    |
+| `icon`      | Severity icon; overrides the default icon for the level |
+
+#### CSS Parts
+
+| Part      | Element    | Description                                                  |
+| --------- | ---------- | ------------------------------------------------------------ |
+| `base`    | `<div>`    | Root wrapper for the toast item with `role` and `data-level` |
+| `icon`    | `<span>`   | Wrapper around the `icon` slot                               |
+| `content` | `<div>`    | Wrapper around the message area                              |
+| `label`   | `<span>`   | Wrapper around the default slot (message text)               |
+| `dismiss` | `<button>` | Dismiss/close button                                         |
+
+#### CSS Custom Properties
+
+| Property                    | Default                                             | Description                                       |
+| --------------------------- | --------------------------------------------------- | ------------------------------------------------- |
+| `--cv-toast-padding-inline` | `var(--cv-space-3, 12px)`                           | Horizontal padding                                |
+| `--cv-toast-padding-block`  | `var(--cv-space-2, 8px)`                            | Vertical padding                                  |
+| `--cv-toast-border-radius`  | `var(--cv-radius-md, 10px)`                         | Border radius                                     |
+| `--cv-toast-gap`            | `var(--cv-space-2, 8px)`                            | Spacing between icon, content, and dismiss button |
+| `--cv-toast-background`     | `var(--cv-color-surface-elevated, #1d2432)`         | Background color                                  |
+| `--cv-toast-border-color`   | `var(--cv-color-border, #2a3245)`                   | Default border color                              |
+| `--cv-toast-color`          | `var(--cv-color-text, #e8ecf6)`                     | Text color                                        |
+| `--cv-toast-shadow`         | `var(--cv-shadow-1, 0 2px 8px rgba(0, 0, 0, 0.24))` | Box shadow                                        |
+
+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          |
+| `--cv-color-text`             | `#e8ecf6` | Default text color                   |
+| `--cv-color-text-muted`       | `#9aa6bf` | Muted text color (dismiss button)    |
+| `--cv-color-primary`          | `#65d7ff` | Primary accent (focus ring)          |
+| `--cv-color-success`          | `#6ef7c8` | Success tint for border              |
+| `--cv-color-warning`          | `#ffd36e` | Warning tint for border              |
+| `--cv-color-danger`           | `#ff7d86` | Error/danger tint for border         |
+| `--cv-radius-md`              | `10px`    | Medium border radius                 |
+| `--cv-radius-sm`              | `6px`     | Small border radius (dismiss button) |
+| `--cv-space-2`                | `8px`     | Spacing scale                        |
+| `--cv-space-3`                | `12px`    | Spacing scale                        |
+
+#### Visual States
+
+| Host selector / Part selector | Description                                               |
+| ----------------------------- | --------------------------------------------------------- |
+| `[data-level="info"]`         | Default styling with standard border                      |
+| `[data-level="success"]`      | Border tinted with `--cv-color-success` via `color-mix()` |
+| `[data-level="warning"]`      | Border tinted with `--cv-color-warning` via `color-mix()` |
+| `[data-level="error"]`        | Border tinted with `--cv-color-danger` via `color-mix()`  |
+
+#### Events
+
+| Event      | Detail           | Description                                                       |
+| ---------- | ---------------- | ----------------------------------------------------------------- |
+| `cv-close` | `{ id: string }` | Fires when the dismiss button is clicked; bubbles and is composed |
+
+#### Reactive State Mapping
+
+Each toast item is bound to headless contracts per toast ID.
+
+| Headless Contract                     | Direction     | DOM Binding                                                                                            |
+| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
+| `contracts.getToastProps(id)`         | state → attrs | Spread onto `[part="base"]`: `id`, `role` (`status` or `alert`), `data-level`                          |
+| `contracts.getDismissButtonProps(id)` | state → attrs | Spread onto `[part="dismiss"]`: `id`, `role="button"`, `tabindex="0"`, `aria-label`, `onClick` handler |
+
+- `role` is determined by the headless contract based on level: `role="status"` for `info`/`success`, `role="alert"` for `warning`/`error`.
+- In standalone usage, `cv-toast` computes role from its `level` property matching the headless contract logic.
+- When rendered within `cv-toast-region`, the region spreads headless contract props onto each inline toast item.
+- The dismiss button `onClick` handler from `getDismissButtonProps(id)` calls `actions.dismiss(id)` internally.

package/specs/components/toolbar.md

@@ -0,0 +1,258 @@
+# cv-toolbar
+
+Container of interactive elements that provides a single tab stop and arrow-key navigation between items, with separator support and focus memory.
+
+**Headless:** [`createToolbar`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/toolbar.md)
+
+## Anatomy
+
+```
+<cv-toolbar> (host)
+└── <div part="base" role="toolbar" aria-orientation="…">
+    └── <slot>                         ← accepts <cv-toolbar-item> and <cv-toolbar-separator> children
+```
+
+## Attributes
+
+| Attribute     | Type    | Default        | Description                                                                                           |
+| ------------- | ------- | -------------- | ----------------------------------------------------------------------------------------------------- |
+| `value`       | String  | `""`           | Active item value (reflects `activeId` from headless state)                                           |
+| `orientation` | String  | `"horizontal"` | Navigation axis: `horizontal` \| `vertical`                                                           |
+| `wrap`        | Boolean | `true`         | Whether arrow navigation wraps from last to first and vice versa. When `false`, clamps at boundaries. |
+| `aria-label`  | String  | `""`           | Accessible label for the toolbar                                                                      |
+
+## Slots
+
+| Slot        | Description                                               |
+| ----------- | --------------------------------------------------------- |
+| `(default)` | `<cv-toolbar-item>` and `<cv-toolbar-separator>` children |
+
+## CSS Parts
+
+| Part   | Element | Description                                 |
+| ------ | ------- | ------------------------------------------- |
+| `base` | `<div>` | Root layout container with `role="toolbar"` |
+
+## CSS Custom Properties
+
+| Property                     | Default                     | Description                               |
+| ---------------------------- | --------------------------- | ----------------------------------------- |
+| `--cv-toolbar-gap`           | `var(--cv-space-1, 4px)`    | Spacing between toolbar children          |
+| `--cv-toolbar-padding`       | `var(--cv-space-1, 4px)`    | Internal padding of the toolbar container |
+| `--cv-toolbar-border-radius` | `var(--cv-radius-md, 10px)` | Border radius of the toolbar container    |
+
+Additionally, component styles depend on theme tokens through fallback values:
+
+| Theme Property       | Default   | Description              |
+| -------------------- | --------- | ------------------------ |
+| `--cv-color-border`  | `#2a3245` | Toolbar border color     |
+| `--cv-color-surface` | `#141923` | Toolbar background color |
+| `--cv-space-1`       | `4px`     | Gap and padding fallback |
+| `--cv-radius-md`     | `10px`    | Border radius fallback   |
+
+## Visual States
+
+| Host selector                     | Description                                                    |
+| --------------------------------- | -------------------------------------------------------------- |
+| `:host([orientation="vertical"])` | Flex direction switches to column; items stretch to fill width |
+
+## Events
+
+| Event       | Detail                       | Description                                                                                  |
+| ----------- | ---------------------------- | -------------------------------------------------------------------------------------------- |
+| `cv-input`  | `{activeId: string \| null}` | Fires on any user-driven active item change (arrow keys, click, focus)                       |
+| `cv-change` | `{activeId: string \| null}` | Fires when active item commits (same detail as `cv-input`; both fire together on navigation) |
+
+Both `cv-input` and `cv-change` fire when user interaction changes the active item. Programmatic `value` attribute changes that result in a headless state update also dispatch these events.
+
+## Reactive State Mapping
+
+`cv-toolbar` is a visual adapter over headless `createToolbar`.
+
+### UIKit Property to Headless Binding
+
+| UIKit Property | Direction      | Headless Binding                                          |
+| -------------- | -------------- | --------------------------------------------------------- |
+| `value`        | attr -> action | `actions.setActive(value)` when `value` attribute changes |
+| `orientation`  | attr -> option | passed as `orientation` in `createToolbar(options)`       |
+| `wrap`         | attr -> option | passed as `wrap` in `createToolbar(options)`              |
+| `aria-label`   | attr -> option | passed as `ariaLabel` in `createToolbar(options)`         |
+
+### Headless State to DOM Reflection
+
+| Headless State     | Direction     | DOM Reflection                                                         |
+| ------------------ | ------------- | ---------------------------------------------------------------------- |
+| `state.activeId()` | state -> attr | `cv-toolbar[value]` host attribute                                     |
+| `state.activeId()` | state -> attr | `cv-toolbar-item[active]` boolean attribute on the active item element |
+| `state.activeId()` | state -> prop | `cv-toolbar-item.tabIndex` set to `0` for active, `-1` for others      |
+
+### Headless Actions Called
+
+| Action                         | UIKit Trigger                                                                                      |
+| ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `actions.setActive(id)`        | Item receives focus or click; also called when `value` attribute changes                           |
+| `actions.handleKeyDown(event)` | `keydown` event on the toolbar root `[part="base"]`                                                |
+| `actions.handleToolbarFocus()` | `focusin` event on toolbar root when toolbar was not previously focused (re-entry detection)       |
+| `actions.handleToolbarBlur()`  | `focusout` event on toolbar root when `relatedTarget` is outside the toolbar (full blur detection) |
+
+### Headless Contracts Spread
+
+| Contract                          | UIKit Target                                                                                                                                                   |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contracts.getRootProps()`        | Spread onto the `[part="base"]` element (`id`, `role`, `aria-orientation`, `aria-label`)                                                                       |
+| `contracts.getItemProps(id)`      | Spread onto each `cv-toolbar-item` element (`id`, `tabindex`, `aria-disabled`, `data-active`). The `onFocus` callback is bound to the element's `focus` event. |
+| `contracts.getSeparatorProps(id)` | Spread onto each `cv-toolbar-separator` element (`id`, `role`, `aria-orientation`)                                                                             |
+
+### UIKit-Only Concerns (Not in Headless)
+
+- **Focus management DOM calls**: Calling `.focus()` on the DOM element matching `activeId` after keyboard navigation. Headless sets state; UIKit moves DOM focus.
+- **Focus-in/focus-out tracking**: UIKit must detect toolbar entry vs. internal focus moves (e.g., using a `hasFocus` flag updated on `focusin`/`focusout` with `relatedTarget` checks).
+- **Separator rendering**: Visual appearance of separators (line style, thickness, spacing) is a UIKit concern. Headless only provides ARIA props.
+- **Slot change handling**: Rebuilding the headless model when children are added or removed via `slotchange`.
+- **`cv-input` / `cv-change` events**: Custom DOM events dispatched by the UIKit wrapper, not part of the headless model.
+
+UIKit does not own navigation or focus-memory logic; headless state is the source of truth.
+
+## Keyboard Interaction
+
+| Key          | Horizontal            | Vertical              |
+| ------------ | --------------------- | --------------------- |
+| `ArrowRight` | Move to next item     | —                     |
+| `ArrowLeft`  | Move to previous item | —                     |
+| `ArrowDown`  | —                     | Move to next item     |
+| `ArrowUp`    | —                     | Move to previous item |
+| `Home`       | Move to first item    | Move to first item    |
+| `End`        | Move to last item     | Move to last item     |
+
+- Disabled items and separators are skipped during keyboard navigation.
+- When `wrap` is `true` (default), navigation wraps from last to first and vice versa.
+- When `wrap` is `false`, navigation clamps at boundaries (first/last item).
+- Roving tabindex: only the active item has `tabindex="0"`; all others have `tabindex="-1"`.
+- Focus memory: re-entering the toolbar via Tab restores focus to the last-active item.
+
+## Usage
+
+```html
+<cv-toolbar aria-label="Text formatting">
+  <cv-toolbar-item value="bold">Bold</cv-toolbar-item>
+  <cv-toolbar-item value="italic">Italic</cv-toolbar-item>
+  <cv-toolbar-item value="underline">Underline</cv-toolbar-item>
+</cv-toolbar>
+
+<cv-toolbar aria-label="Actions" wrap="false">
+  <cv-toolbar-item value="cut">Cut</cv-toolbar-item>
+  <cv-toolbar-item value="copy">Copy</cv-toolbar-item>
+  <cv-toolbar-separator></cv-toolbar-separator>
+  <cv-toolbar-item value="paste">Paste</cv-toolbar-item>
+</cv-toolbar>
+
+<cv-toolbar orientation="vertical" aria-label="Tools">
+  <cv-toolbar-item value="brush">Brush</cv-toolbar-item>
+  <cv-toolbar-item value="eraser">Eraser</cv-toolbar-item>
+  <cv-toolbar-separator></cv-toolbar-separator>
+  <cv-toolbar-item value="fill">Fill</cv-toolbar-item>
+  <cv-toolbar-item value="picker" disabled>Picker</cv-toolbar-item>
+</cv-toolbar>
+```
+
+## Child Elements
+
+### cv-toolbar-item
+
+Interactive element within a toolbar that participates in roving tabindex navigation.
+
+#### Anatomy
+
+```
+<cv-toolbar-item> (host)
+└── <div part="base">
+    └── <slot>
+```
+
+#### Attributes
+
+| Attribute  | Type    | Default | Description                                                              |
+| ---------- | ------- | ------- | ------------------------------------------------------------------------ |
+| `value`    | String  | `""`    | Unique identifier for this item. Auto-generated as `item-{n}` if empty.  |
+| `disabled` | Boolean | `false` | Prevents this item from receiving focus via keyboard navigation          |
+| `active`   | Boolean | `false` | Whether this item is the current roving-focus target (managed by parent) |
+
+#### Slots
+
+| Slot        | Description                                      |
+| ----------- | ------------------------------------------------ |
+| `(default)` | Item content (text, icon, or any inline content) |
+
+#### CSS Parts
+
+| Part   | Element | Description              |
+| ------ | ------- | ------------------------ |
+| `base` | `<div>` | Root interactive wrapper |
+
+#### CSS Custom Properties
+
+| Property                           | Default                    | Description                    |
+| ---------------------------------- | -------------------------- | ------------------------------ |
+| `--cv-toolbar-item-min-height`     | `32px`                     | Minimum block size of the item |
+| `--cv-toolbar-item-padding-inline` | `var(--cv-space-3, 12px)`  | Horizontal padding             |
+| `--cv-toolbar-item-border-radius`  | `var(--cv-radius-sm, 6px)` | Border radius                  |
+
+Additionally, component styles depend on theme tokens through fallback values:
+
+| Theme Property         | Default   | Description                |
+| ---------------------- | --------- | -------------------------- |
+| `--cv-color-border`    | `#2a3245` | Item border color          |
+| `--cv-color-surface`   | `#141923` | Item background color      |
+| `--cv-color-text`      | `#e8ecf6` | Item text color            |
+| `--cv-color-primary`   | `#65d7ff` | Active state accent color  |
+| `--cv-duration-fast`   | `120ms`   | Transition duration        |
+| `--cv-easing-standard` | `ease`    | Transition timing function |
+
+#### Visual States
+
+| Host selector           | Description                                                             |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `:host([active])`       | Primary-tinted border and blended background using `--cv-color-primary` |
+| `:host([disabled])`     | Reduced opacity (`0.55`)                                                |
+| `:host(:focus-visible)` | Focus ring: `2px solid var(--cv-color-primary)` with `1px` offset       |
+
+---
+
+### cv-toolbar-separator
+
+Non-interactive visual divider within a toolbar. Separators are skipped by keyboard navigation and cannot receive focus.
+
+#### Anatomy
+
+```
+<cv-toolbar-separator> (host)
+└── <div part="base" role="separator" aria-orientation="…">
+```
+
+The separator's `aria-orientation` is perpendicular to the toolbar's orientation: a horizontal toolbar renders vertical separators, and vice versa.
+
+#### Attributes
+
+| Attribute | Type   | Default | Description                                                      |
+| --------- | ------ | ------- | ---------------------------------------------------------------- |
+| `value`   | String | `""`    | Identifier used to match the separator in the headless item list |
+
+#### CSS Parts
+
+| Part   | Element | Description                                    |
+| ------ | ------- | ---------------------------------------------- |
+| `base` | `<div>` | Separator line element with `role="separator"` |
+
+#### CSS Custom Properties
+
+| Property                        | Default                           | Description                     |
+| ------------------------------- | --------------------------------- | ------------------------------- |
+| `--cv-toolbar-separator-size`   | `1px`                             | Thickness of the separator line |
+| `--cv-toolbar-separator-color`  | `var(--cv-color-border, #2a3245)` | Color of the separator line     |
+| `--cv-toolbar-separator-margin` | `var(--cv-space-1, 4px)`          | Margin around the separator     |
+
+#### Visual States
+
+| Host selector | Description                                                                                                                                                                                                                                                             |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:host`       | In a horizontal toolbar: vertical line (`height: auto`, `width: --cv-toolbar-separator-size`). In a vertical toolbar: horizontal line (`width: auto`, `height: --cv-toolbar-separator-size`). Orientation is communicated via the parent spreading `getSeparatorProps`. |

package/specs/components/tooltip.md

@@ -0,0 +1,152 @@
+# cv-tooltip
+
+Contextual information overlay that appears near a trigger element on hover, focus, click, or programmatic control.
+
+**Headless:** [`createTooltip`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/tooltip.md)
+
+## Anatomy
+
+```
+<cv-tooltip> (host)
+└── <span part="base">
+    ├── <span part="trigger">
+    │   └── <slot name="trigger">
+    └── <span part="content" role="tooltip">
+        ├── <slot name="content">
+        └── <span part="arrow">           ← only when [arrow]
+```
+
+## Attributes
+
+| Attribute    | Type    | Default         | Description                                                                |
+| ------------ | ------- | --------------- | -------------------------------------------------------------------------- |
+| `open`       | Boolean | `false`         | Reflects tooltip visibility; can be set to programmatically show or hide   |
+| `disabled`   | Boolean | `false`         | Disables all trigger interactions; removes `aria-describedby` from trigger |
+| `show-delay` | Number  | `120`           | Milliseconds to wait before showing the tooltip                            |
+| `hide-delay` | Number  | `80`            | Milliseconds to wait before hiding the tooltip                             |
+| `trigger`    | String  | `'hover focus'` | Space-separated trigger modes: `hover` \| `focus` \| `click` \| `manual`   |
+| `arrow`      | Boolean | `false`         | Renders the `part="arrow"` CSS triangle pointing toward the trigger        |
+
+## Slots
+
+| Slot      | Description                                                                  |
+| --------- | ---------------------------------------------------------------------------- |
+| `trigger` | The element that activates the tooltip (receives `aria-describedby` linkage) |
+| `content` | Rich HTML tooltip body content                                               |
+
+## CSS Parts
+
+| Part      | Element  | Description                                                          |
+| --------- | -------- | -------------------------------------------------------------------- |
+| `base`    | `<span>` | Root layout wrapper, positioned relatively                           |
+| `trigger` | `<span>` | Wrapper around the trigger slot; receives event listeners            |
+| `content` | `<span>` | Tooltip body container with `role="tooltip"`; hidden when not open   |
+| `arrow`   | `<span>` | Optional CSS triangle indicator; rendered only when `[arrow]` is set |
+
+## CSS Custom Properties
+
+Component styles depend on theme tokens through inline fallback values:
+
+> **Note:** Component-level `--cv-tooltip-*` custom property indirection is not implemented.
+> Styles reference theme tokens directly.
+
+| Theme Property                | Default                         | Description                 |
+| ----------------------------- | ------------------------------- | --------------------------- |
+| `--cv-color-surface-elevated` | `#1d2432`                       | Elevated surface background |
+| `--cv-color-border`           | `#2a3245`                       | Border color                |
+| `--cv-color-text`             | `#e8ecf6`                       | Default text color          |
+| `--cv-shadow-1`               | `0 2px 8px rgba(0, 0, 0, 0.24)` | Drop shadow                 |
+| `--cv-radius-sm`              | `6px`                           | Border radius               |
+| `--cv-space-1`                | `4px`                           | Small spacing scale         |
+| `--cv-space-2`                | `8px`                           | Medium spacing scale        |
+
+## Visual States
+
+| Host selector       | Description                                                         |
+| ------------------- | ------------------------------------------------------------------- |
+| `:host([open])`     | Tooltip content is visible; `[part="content"]` has `hidden` removed |
+| `:host([disabled])` | All trigger interactions are blocked; `aria-describedby` is removed |
+| `:host([arrow])`    | Arrow indicator (`[part="arrow"]`) is rendered and visible          |
+
+## Events
+
+| Event       | Detail              | Description                                                   |
+| ----------- | ------------------- | ------------------------------------------------------------- |
+| `cv-input`  | `{ open: boolean }` | Fires on every open/close transition triggered by interaction |
+| `cv-change` | `{ open: boolean }` | Fires when the open state commits after interaction           |
+
+Both events bubble and are composed. They are dispatched together on every transition of `isOpen`.
+
+## Reactive State Mapping
+
+`cv-tooltip` is a visual adapter over headless `createTooltip`.
+
+| UIKit Property | Direction     | Headless Binding                                                    |
+| -------------- | ------------- | ------------------------------------------------------------------- |
+| `open`         | attr → action | `actions.open()` / `actions.close()` depending on value             |
+| `disabled`     | attr → action | `actions.setDisabled(value)`                                        |
+| `show-delay`   | attr → option | passed as `showDelay` to `createTooltip(options)` (recreates model) |
+| `hide-delay`   | attr → option | passed as `hideDelay` to `createTooltip(options)` (recreates model) |
+| `trigger`      | attr → option | passed as `trigger` to `createTooltip(options)`                     |
+
+| Headless State       | Direction    | DOM Reflection              |
+| -------------------- | ------------ | --------------------------- |
+| `state.isOpen()`     | state → attr | `[open]` host attribute     |
+| `state.isDisabled()` | state → attr | `[disabled]` host attribute |
+
+- `contracts.getTriggerProps()` is spread onto `[part="trigger"]` to apply `id`, `aria-describedby`, and all active event handlers (`onPointerEnter`, `onPointerLeave`, `onFocus`, `onBlur`, `onClick`, `onKeyDown`) depending on the active `trigger` modes.
+- `contracts.getTooltipProps()` is spread onto `[part="content"]` to apply `id`, `role="tooltip"`, `tabindex="-1"`, and `hidden`.
+- `aria-describedby` is also propagated to assigned slotted trigger elements directly via `syncTriggerAria`.
+- UIKit dispatches `cv-input` and `cv-change` events by observing transitions of `isOpen` caused by interaction; programmatic `open`/`close` calls that do not change state do not re-emit.
+- UIKit does not own trigger or delay logic; headless state is the source of truth.
+- When `show-delay` or `hide-delay` changes, the model is recreated with the current `open` state preserved as `initialOpen`.
+- Public methods `show()` and `hide()` delegate to `model.actions.show()` / `model.actions.hide()` for `manual` mode consumers.
+
+## Usage
+
+```html
+<!-- Default: hover + focus triggers -->
+<cv-tooltip>
+  <button slot="trigger">Hover me</button>
+  <span slot="content">Contextual info</span>
+</cv-tooltip>
+
+<!-- Click trigger only -->
+<cv-tooltip trigger="click">
+  <button slot="trigger">Click me</button>
+  <span slot="content">Shown on click</span>
+</cv-tooltip>
+
+<!-- With arrow indicator -->
+<cv-tooltip arrow>
+  <button slot="trigger">With arrow</button>
+  <span slot="content">Tooltip with arrow</span>
+</cv-tooltip>
+
+<!-- Disabled -->
+<cv-tooltip disabled>
+  <button slot="trigger">No tooltip</button>
+  <span slot="content">Never shown</span>
+</cv-tooltip>
+
+<!-- Manual mode (programmatic control) -->
+<cv-tooltip trigger="manual" id="my-tip">
+  <button slot="trigger">Target</button>
+  <span slot="content">Shown programmatically</span>
+</cv-tooltip>
+<script>
+  document.querySelector('#my-tip').show()
+</script>
+
+<!-- Custom delays -->
+<cv-tooltip show-delay="300" hide-delay="200">
+  <button slot="trigger">Delayed</button>
+  <span slot="content">Appears after 300ms</span>
+</cv-tooltip>
+
+<!-- Rich HTML content -->
+<cv-tooltip>
+  <button slot="trigger">Rich tooltip</button>
+  <span slot="content"> <strong>Title</strong><br />Supporting text </span>
+</cv-tooltip>
+```