@chromvoid/uikit 0.1.0

package/specs/components/sidebar.md

@@ -0,0 +1,204 @@
+# `cv-sidebar`
+
+Persistent layout sidebar with desktop expand/collapse, mobile overlay mode, and opt-in same-page `scrollspy`.
+
+**Headless base:** [`createSidebar`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/sidebar.md)
+
+## Anatomy
+
+```text
+<cv-sidebar>
+├── <div part="overlay">
+└── <aside part="panel">
+    ├── <header part="header">
+    │   ├── <slot name="header">
+    │   └── <button part="toggle">
+    │       └── <slot name="toggle">
+    ├── <nav part="body">
+    │   └── <slot>
+    └── <footer part="footer">
+        └── <slot name="footer">
+```
+
+## Attributes
+
+| Attribute                  | Type                                  | Default                | Description                                                |
+| -------------------------- | ------------------------------------- | ---------------------- | ---------------------------------------------------------- |
+| `expanded`                 | Boolean                               | `true`                 | Desktop full-width mode                                    |
+| `collapsed`                | Boolean                               | `false`                | Desktop rail mode; inverse of `expanded`                   |
+| `mobile`                   | Boolean                               | `false`                | Mobile/overlay mode                                        |
+| `overlay-open`             | Boolean                               | `false`                | Mobile overlay visibility                                  |
+| `size`                     | `"small" \| "medium" \| "large"`      | `"medium"`             | Width preset                                               |
+| `breakpoint`               | String                                | `"768px"`              | Auto-switch breakpoint for mobile mode                     |
+| `close-on-escape`          | Boolean                               | `true`                 | Whether `Escape` closes mobile overlay                     |
+| `close-on-outside-pointer` | Boolean                               | `true`                 | Whether outside pointer closes mobile overlay              |
+| `initial-focus-id`         | String                                | ---                    | Initial focus target when overlay opens                    |
+| `aria-label`               | String                                | `"Sidebar navigation"` | Accessible label for the panel landmark/dialog             |
+| `scrollspy`                | Boolean                               | `false`                | Enables same-page hash navigation tracking                 |
+| `scrollspy-offset-top`     | Number                                | `0`                    | Top offset used when resolving the active section          |
+| `scrollspy-strategy`       | `"top-anchor" \| "viewport-dominant"` | `"top-anchor"`         | Strategy used to resolve the active section                |
+| `scrollspy-smooth-scroll`  | Boolean                               | `true`                 | Uses `scrollIntoView({behavior: "smooth"})` for hash items |
+
+## Properties
+
+| Property        | Type                                        | Default | Description                                      |
+| --------------- | ------------------------------------------- | ------- | ------------------------------------------------ |
+| `scrollspyRoot` | `Document \| ShadowRoot \| Element \| null` | `null`  | Explicit root used for resolving section targets |
+| `activeId`      | `string \| null`                            | `null`  | Readonly id of the active `scrollspy` target     |
+
+When `scrollspyRoot` is `null`, `cv-sidebar` resolves section targets in the host element root (`Document` or parent `ShadowRoot`).
+
+## Slots
+
+| Slot     | Description                                                           |
+| -------- | --------------------------------------------------------------------- |
+| default  | Navigation content, including `cv-sidebar-item` or plain hash anchors |
+| `header` | Header content                                                        |
+| `toggle` | Custom toggle icon/content                                            |
+| `footer` | Footer content                                                        |
+
+## CSS Parts
+
+| Part      | Description                       |
+| --------- | --------------------------------- |
+| `overlay` | Mobile backdrop                   |
+| `panel`   | Sidebar panel                     |
+| `header`  | Header area                       |
+| `toggle`  | Expand/collapse or overlay toggle |
+| `body`    | Main nav body                     |
+| `footer`  | Footer area                       |
+
+## CSS Custom Properties
+
+| Property                           | Default                                       |
+| ---------------------------------- | --------------------------------------------- |
+| `--cv-sidebar-inline-size`         | `280px`                                       |
+| `--cv-sidebar-rail-inline-size`    | `56px`                                        |
+| `--cv-sidebar-z-index`             | `30`                                          |
+| `--cv-sidebar-background`          | `var(--cv-color-surface, #141923)`            |
+| `--cv-sidebar-border-color`        | `var(--cv-color-border, #2a3245)`             |
+| `--cv-sidebar-padding-block`       | `var(--cv-space-3, 12px)`                     |
+| `--cv-sidebar-padding-inline`      | `var(--cv-space-3, 12px)`                     |
+| `--cv-sidebar-overlay-color`       | `color-mix(in oklab, black 56%, transparent)` |
+| `--cv-sidebar-transition-duration` | `var(--cv-duration-normal, 200ms)`            |
+| `--cv-sidebar-transition-easing`   | `var(--cv-easing-standard, ease)`             |
+
+## Events
+
+| Event                    | Detail                       | Description                               |
+| ------------------------ | ---------------------------- | ----------------------------------------- |
+| `cv-input`               | `{expanded: boolean}`        | Desktop user-driven expand/collapse       |
+| `cv-change`              | `{expanded: boolean}`        | Desktop committed expand/collapse         |
+| `cv-input`               | `{overlayOpen: boolean}`     | Mobile user-driven overlay open/close     |
+| `cv-change`              | `{overlayOpen: boolean}`     | Mobile committed overlay open/close       |
+| `cv-expand`              | ---                          | Desktop expand lifecycle start            |
+| `cv-after-expand`        | ---                          | Desktop expand lifecycle end              |
+| `cv-collapse`            | ---                          | Desktop collapse lifecycle start          |
+| `cv-after-collapse`      | ---                          | Desktop collapse lifecycle end            |
+| `cv-overlay-open`        | ---                          | Mobile overlay open lifecycle start       |
+| `cv-after-overlay-open`  | ---                          | Mobile overlay open lifecycle end         |
+| `cv-overlay-close`       | ---                          | Mobile overlay close lifecycle start      |
+| `cv-after-overlay-close` | ---                          | Mobile overlay close lifecycle end        |
+| `cv-scrollspy-change`    | `{activeId: string \| null}` | Fires when the active hash target changes |
+
+## Scrollspy behavior
+
+- `scrollspy` only manages same-page hash items (`href="#section-id"`).
+- Slotted `cv-sidebar-item` elements receive `active` state automatically.
+- Slotted plain anchors receive `aria-current="location"` automatically.
+- Same-page hash clicks are intercepted and resolved by the sidebar scrollspy controller.
+- No `scroll` listeners are used. Active state is derived from `IntersectionObserver`.
+- `top-anchor` keeps classic TOC semantics based on the section closest to the configured top anchor.
+- `viewport-dominant` resolves the active section from effective viewport dominance using visible coverage, distance to viewport center, and hysteresis.
+- In `viewport-dominant`, same-page hash clicks scroll the target to the viewport center instead of the top edge.
+- In `viewport-dominant`, same-page hash clicks do not optimistically switch `activeId`; the active item updates only after observer-driven recompute.
+
+## `cv-sidebar-item`
+
+Lightweight sidebar navigation item that adapts to expanded and collapsed rail modes.
+
+### Anatomy
+
+```text
+<cv-sidebar-item>
+└── <a part="base">
+    ├── <span part="prefix">
+    │   └── <slot name="prefix">
+    ├── <span part="label">
+    │   └── <slot>
+    └── <span part="suffix">
+        └── <slot name="suffix">
+```
+
+### Attributes
+
+| Attribute  | Type    | Default | Description          |
+| ---------- | ------- | ------- | -------------------- |
+| `href`     | String  | `""`    | Item target          |
+| `active`   | Boolean | `false` | Current/active state |
+| `disabled` | Boolean | `false` | Disables interaction |
+
+### Slots
+
+| Slot     | Description              |
+| -------- | ------------------------ |
+| default  | Label                    |
+| `prefix` | Leading icon/content     |
+| `suffix` | Trailing badge/indicator |
+
+### CSS Parts
+
+| Part     | Description    |
+| -------- | -------------- |
+| `base`   | Root anchor    |
+| `prefix` | Prefix wrapper |
+| `label`  | Label wrapper  |
+| `suffix` | Suffix wrapper |
+
+### CSS Custom Properties
+
+| Property                              | Default                               |
+| ------------------------------------- | ------------------------------------- |
+| `--cv-sidebar-item-gap`               | `var(--cv-space-2, 8px)`              |
+| `--cv-sidebar-item-min-block-size`    | `32px`                                |
+| `--cv-sidebar-item-padding-block`     | `var(--cv-space-2, 8px)`              |
+| `--cv-sidebar-item-padding-inline`    | `var(--cv-space-3, 12px)`             |
+| `--cv-sidebar-item-border-radius`     | `var(--cv-radius-sm, 6px)`            |
+| `--cv-sidebar-item-color`             | `var(--cv-color-text-muted, #9aa6bf)` |
+| `--cv-sidebar-item-color-hover`       | `var(--cv-color-text, #e8ecf6)`       |
+| `--cv-sidebar-item-color-active`      | `var(--cv-color-primary, #65d7ff)`    |
+| `--cv-sidebar-item-background`        | `transparent`                         |
+| `--cv-sidebar-item-background-hover`  | mixed surface highlight               |
+| `--cv-sidebar-item-background-active` | `transparent`                         |
+| `--cv-sidebar-item-indicator-width`   | `2px`                                 |
+| `--cv-sidebar-item-indicator-color`   | `var(--cv-color-primary, #65d7ff)`    |
+
+`cv-sidebar` propagates `collapsed` and `mobile` context to direct child `cv-sidebar-item` elements so labels and suffix content are visually hidden in desktop rail mode without consumer-specific wiring.
+
+## Usage
+
+```html
+<cv-sidebar>
+  <span slot="header">Threat Model</span>
+
+  <cv-sidebar-item href="#assets">
+    <cv-icon slot="prefix" name="database"></cv-icon>
+    Assets
+  </cv-sidebar-item>
+
+  <cv-sidebar-item href="#crypto" active>
+    <cv-icon slot="prefix" name="shield"></cv-icon>
+    Crypto
+    <cv-badge slot="suffix">Active</cv-badge>
+  </cv-sidebar-item>
+</cv-sidebar>
+```
+
+```html
+<cv-sidebar scrollspy scrollspy-offset-top="80">
+  <span slot="header">On this page</span>
+  <cv-sidebar-item href="#assets">Assets</cv-sidebar-item>
+  <cv-sidebar-item href="#trust-boundaries">Trust Boundaries</cv-sidebar-item>
+  <cv-sidebar-item href="#crypto">Crypto</cv-sidebar-item>
+</cv-sidebar>
+```

package/specs/components/spinbutton.md

@@ -0,0 +1,157 @@
+# cv-spinbutton
+
+Numeric spinbutton input with keyboard, stepper controls, form-associated behavior, and headless-driven ARIA contracts.
+
+**Headless:** [`createSpinbutton`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/spinbutton.md)
+
+## Anatomy
+
+```
+<cv-spinbutton> (host)
+└── <div part="base">
+    ├── <input part="input" role="spinbutton" inputmode="decimal">
+    └── <div part="actions">
+        ├── <button part="increment" type="button">
+        └── <button part="decrement" type="button">
+```
+
+## Attributes
+
+| Attribute          | Type    | Default | Description                                             |
+| ------------------ | ------- | ------- | ------------------------------------------------------- |
+| `name`             | String  | `""`    | Form field name for submit serialization                |
+| `value`            | Number  | `0`     | Current numeric value                                   |
+| `min`              | Number  | —       | Optional minimum boundary                               |
+| `max`              | Number  | —       | Optional maximum boundary                               |
+| `step`             | Number  | `1`     | Small increment/decrement step                          |
+| `large-step`       | Number  | `10`    | Large increment/decrement step (`PageUp`/`PageDown`)    |
+| `disabled`         | Boolean | `false` | Blocks interaction and omits value from form submission |
+| `read-only`        | Boolean | `false` | Keeps focusable/announced but blocks user mutation      |
+| `required`         | Boolean | `false` | Enables constraint-validation checks                    |
+| `aria-label`       | String  | `""`    | Accessible label                                        |
+| `aria-labelledby`  | String  | `""`    | ID reference to visible label                           |
+| `aria-describedby` | String  | `""`    | ID reference to description                             |
+
+## Slots
+
+None.
+
+## CSS Parts
+
+| Part        | Element    | Description                                       |
+| ----------- | ---------- | ------------------------------------------------- |
+| `base`      | `<div>`    | Layout container for input and actions            |
+| `input`     | `<input>`  | Focusable spinbutton control, editable text input |
+| `actions`   | `<div>`    | Wrapper for increment/decrement controls          |
+| `increment` | `<button>` | Increments value by `step`                        |
+| `decrement` | `<button>` | Decrements value by `step`                        |
+
+## CSS Custom Properties
+
+No component-scoped `--cv-spinbutton-*` properties are currently defined.
+
+Theme tokens used with fallbacks:
+
+| Theme Property                | Default   | Description               |
+| ----------------------------- | --------- | ------------------------- |
+| `--cv-space-1`                | `4px`     | Internal spacing          |
+| `--cv-radius-sm`              | `6px`     | Base radius               |
+| `--cv-color-border`           | `#2a3245` | Border color              |
+| `--cv-color-surface`          | `#141923` | Base background           |
+| `--cv-color-surface-elevated` | `#1d2432` | Stepper button background |
+| `--cv-color-text`             | `#e8ecf6` | Foreground color          |
+| `--cv-color-primary`          | `#65d7ff` | Focus ring color          |
+
+## Visual States
+
+| Host selector        | Description                                                         |
+| -------------------- | ------------------------------------------------------------------- |
+| `:host([disabled])`  | Base and controls are visually muted and non-interactive            |
+| `:host([read-only])` | Input remains focusable; stepper controls are muted/non-interactive |
+
+## Reactive State Mapping
+
+`cv-spinbutton` is a thin adapter over headless `createSpinbutton`.
+
+| UIKit Property     | Direction     | Headless Binding                      |
+| ------------------ | ------------- | ------------------------------------- |
+| `value`            | attr → action | `actions.setValue(value)`             |
+| `disabled`         | attr → action | `actions.setDisabled(value)`          |
+| `read-only`        | attr → action | `actions.setReadOnly(value)`          |
+| `min`              | attr → option | passed to `createSpinbutton(options)` |
+| `max`              | attr → option | passed to `createSpinbutton(options)` |
+| `step`             | attr → option | passed to `createSpinbutton(options)` |
+| `large-step`       | attr → option | passed to `createSpinbutton(options)` |
+| `aria-label`       | attr → option | passed as `ariaLabel`                 |
+| `aria-labelledby`  | attr → option | passed as `ariaLabelledBy`            |
+| `aria-describedby` | attr → option | passed as `ariaDescribedBy`           |
+
+| Headless State/Contract               | Direction        | DOM Reflection                                               |
+| ------------------------------------- | ---------------- | ------------------------------------------------------------ |
+| `state.value()`                       | state → value    | `[part="input"].value` and host `value` property             |
+| `contracts.getSpinbuttonProps()`      | contract → attrs | role, tabindex, and ARIA attributes on `[part="input"]`      |
+| `contracts.getIncrementButtonProps()` | contract → attrs | id/tabindex/aria-disabled/aria-label on `[part="increment"]` |
+| `contracts.getDecrementButtonProps()` | contract → attrs | id/tabindex/aria-disabled/aria-label on `[part="decrement"]` |
+
+- UIKit may hold transient draft text while editing.
+- Draft text commits to headless on `Enter` or `blur` only.
+- UIKit does not implement keyboard stepping, clamping, snapping, or ARIA computation itself.
+
+## Events
+
+| Event       | Detail            | Description                                                           |
+| ----------- | ----------------- | --------------------------------------------------------------------- |
+| `cv-input`  | `{value: number}` | Fires on each user-triggered value mutation (buttons/stepping/commit) |
+| `cv-change` | `{value: number}` | Fires together with `cv-input` for the same user-triggered mutation   |
+
+Programmatic mutations through imperative API do not emit `cv-input`/`cv-change`.
+
+## Imperative API
+
+| Method / Property            | Description                                             |
+| ---------------------------- | ------------------------------------------------------- |
+| `stepUp(times = 1)`          | Increments by `step` `times` times                      |
+| `stepDown(times = 1)`        | Decrements by `step` `times` times                      |
+| `pageUp(times = 1)`          | Increments by `largeStep` `times` times                 |
+| `pageDown(times = 1)`        | Decrements by `largeStep` `times` times                 |
+| `setValue(value)`            | Sets numeric value through headless normalization       |
+| `getValue()`                 | Returns current committed numeric value                 |
+| `setRange(min, max)`         | Updates range boundaries (`min`/`max`)                  |
+| `focus(options?)`            | Focuses inner input control                             |
+| `select()`                   | Selects text in inner input control                     |
+| `checkValidity()`            | Runs current validation checks                          |
+| `reportValidity()`           | Reports validation state to UA when supported           |
+| `setCustomValidity(message)` | Sets/clears custom validity message                     |
+| `form`                       | Form owner when form-associated internals are supported |
+| `validity`                   | Current validity state when supported                   |
+| `validationMessage`          | Current validation message                              |
+| `willValidate`               | Whether control participates in validation              |
+
+UA callbacks supported for form-associated lifecycle:
+
+- `formDisabledCallback(disabled)`
+- `formResetCallback()`
+- `formStateRestoreCallback(state)`
+
+## Form Association
+
+- Component is form-associated via `ElementInternals` when available.
+- Submit value is serialized as raw numeric string from committed `value`.
+- `disabled` state removes form value from submission.
+- Reset restores the initial `value` snapshot captured on first connection.
+
+## Usage
+
+```html
+<cv-spinbutton name="quantity" value="2" min="0" max="10" step="1"></cv-spinbutton>
+
+<cv-spinbutton value="50" min="0" max="100" step="5" large-step="25"></cv-spinbutton>
+
+<cv-spinbutton value="5" aria-label="Quantity"></cv-spinbutton>
+
+<cv-spinbutton value="3" read-only></cv-spinbutton>
+
+<form>
+  <cv-spinbutton name="items" value="1" required></cv-spinbutton>
+</form>
+```

package/specs/components/spinner.md

@@ -0,0 +1,83 @@
+# cv-spinner
+
+Indeterminate loading spinner with SVG track and indicator animation.
+
+**Headless:** [`createSpinner`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/spinner.md)
+
+## Anatomy
+
+```
+<cv-spinner> (host)
+└── <svg part="base" role="progressbar" aria-label="...">
+    ├── <circle part="track">
+    └── <circle part="indicator">
+```
+
+## Attributes
+
+| Attribute | Type   | Default     | Description                                       |
+| --------- | ------ | ----------- | ------------------------------------------------- |
+| `label`   | String | `"Loading"` | Accessible name announced by assistive technology |
+
+No `size` attribute is provided. Sizing is controlled entirely via CSS `font-size` on the host element; the SVG scales relative to `1em`.
+
+## Slots
+
+None. The spinner is purely visual with no slotted content.
+
+## CSS Parts
+
+| Part        | Element    | Description                                    |
+| ----------- | ---------- | ---------------------------------------------- |
+| `base`      | `<svg>`    | Root SVG element with ARIA attributes          |
+| `track`     | `<circle>` | Background circle (static ring)                |
+| `indicator` | `<circle>` | Animated arc indicating indeterminate progress |
+
+## CSS Custom Properties
+
+| Property                       | Default                            | Description                              |
+| ------------------------------ | ---------------------------------- | ---------------------------------------- |
+| `--cv-spinner-track-width`     | `4px`                              | Stroke width of both track and indicator |
+| `--cv-spinner-track-color`     | `var(--cv-color-border, #2a3245)`  | Color of the background track ring       |
+| `--cv-spinner-indicator-color` | `var(--cv-color-primary, #65d7ff)` | Color of the animated indicator arc      |
+| `--cv-spinner-speed`           | `600ms`                            | Duration of one full rotation cycle      |
+
+## Visual States
+
+None. The spinner is always animating when rendered; there are no conditional visual states.
+
+## Events
+
+None. The spinner is purely presentational and does not emit events.
+
+## Reactive State Mapping
+
+`cv-spinner` is a visual adapter over headless `createSpinner`.
+
+| UIKit Property | Direction      | Headless Binding          |
+| -------------- | -------------- | ------------------------- |
+| `label`        | attr -> action | `actions.setLabel(value)` |
+
+| Headless State  | Direction         | DOM Reflection                   |
+| --------------- | ----------------- | -------------------------------- |
+| `state.label()` | state -> contract | Consumed via `getSpinnerProps()` |
+
+- `contracts.getSpinnerProps()` is spread onto the inner `[part="base"]` SVG element to apply `role="progressbar"` and `aria-label`.
+- UIKit does not own ARIA semantics; headless state is the source of truth.
+- `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` are never present (indeterminate mode only).
+
+## Usage
+
+```html
+<!-- Default spinner -->
+<cv-spinner></cv-spinner>
+
+<!-- Custom accessible label -->
+<cv-spinner label="Saving changes"></cv-spinner>
+
+<!-- Sized via CSS font-size -->
+<cv-spinner style="font-size: 2rem;"></cv-spinner>
+
+<!-- Themed via custom properties -->
+<cv-spinner style="--cv-spinner-indicator-color: #ff7d86; --cv-spinner-speed: 800ms;"></cv-spinner>
+```

package/specs/components/switch.md

@@ -0,0 +1,145 @@
+# cv-switch
+
+Toggle control that represents an on/off state, visually distinct from a checkbox.
+
+**Headless:** [`createSwitch`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/switch.md)
+
+## Anatomy
+
+```
+<cv-switch> (host)
+└── <div part="base">
+    ├── <div part="control" role="switch">
+    │   ├── <span part="toggled" hidden>
+    │   │   └── <slot name="toggled">
+    │   ├── <span part="untoggled" hidden>
+    │   │   └── <slot name="untoggled">
+    │   └── <span part="thumb">
+    ├── <span part="label">
+    │   └── <slot>
+    └── <span part="help-text" id="{idBase}-help-text">
+        └── <slot name="help-text">
+```
+
+When `checked` is `true`, the `toggled` wrapper is visible and `untoggled` is hidden. When `checked` is `false`, the opposite applies. Both wrappers are always in the DOM; visibility is toggled via CSS or the `hidden` attribute.
+
+The `help-text` part is rendered only when the `help-text` attribute is set or the `help-text` slot is populated.
+
+## Attributes
+
+| Attribute   | Type    | Default    | Description                                 |
+| ----------- | ------- | ---------- | ------------------------------------------- |
+| `checked`   | Boolean | `false`    | On/off state                                |
+| `disabled`  | Boolean | `false`    | Prevents interaction                        |
+| `size`      | String  | `"medium"` | Size: `small` \| `medium` \| `large`        |
+| `help-text` | String  | `""`       | Descriptive text displayed below the switch |
+
+## Sizes
+
+| Size     | `--cv-switch-width` | `--cv-switch-height` | `--cv-switch-thumb-size` |
+| -------- | ------------------- | -------------------- | ------------------------ |
+| `small`  | `36px`              | `20px`               | `14px`                   |
+| `medium` | `44px`              | `24px`               | `18px`                   |
+| `large`  | `52px`              | `28px`               | `22px`                   |
+
+## Slots
+
+| Slot        | Description                                                            |
+| ----------- | ---------------------------------------------------------------------- |
+| `(default)` | Label text displayed beside the switch                                 |
+| `toggled`   | Content shown inside the track when checked (e.g., icon, text)         |
+| `untoggled` | Content shown inside the track when unchecked (e.g., icon, text)       |
+| `help-text` | Descriptive text below the switch; overrides the `help-text` attribute |
+
+## CSS Parts
+
+| Part        | Element  | Description                                                  |
+| ----------- | -------- | ------------------------------------------------------------ |
+| `base`      | `<div>`  | Root layout wrapper (contains control + label + help-text)   |
+| `control`   | `<div>`  | Track/oval with `role="switch"`                              |
+| `thumb`     | `<span>` | Sliding knob inside the control                              |
+| `toggled`   | `<span>` | Wrapper around the `toggled` slot (visible when checked)     |
+| `untoggled` | `<span>` | Wrapper around the `untoggled` slot (visible when unchecked) |
+| `label`     | `<span>` | Wrapper around the default slot                              |
+| `help-text` | `<span>` | Wrapper around the `help-text` slot or attribute text        |
+
+## CSS Custom Properties
+
+| Property                          | Default                               | Description                             |
+| --------------------------------- | ------------------------------------- | --------------------------------------- |
+| `--cv-switch-width`               | `44px`                                | Inline size of the control track        |
+| `--cv-switch-height`              | `24px`                                | Block size of the control track         |
+| `--cv-switch-thumb-size`          | `18px`                                | Size of the thumb knob                  |
+| `--cv-switch-gap`                 | `var(--cv-space-2, 8px)`              | Spacing between control track and label |
+| `--cv-switch-help-text-color`     | `var(--cv-color-text-muted, #9aa6bf)` | Color of the help text                  |
+| `--cv-switch-help-text-font-size` | `0.85em`                              | Font size of the help text              |
+
+## Visual States
+
+| Host selector           | Description                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- |
+| `:host([checked])`      | Primary-tinted track, thumb translated to end position; `toggled` part visible, `untoggled` part hidden |
+| `:host([disabled])`     | Reduced opacity (`0.55`), `cursor: not-allowed`                                                         |
+| `:host([size="small"])` | Small size overrides                                                                                    |
+| `:host([size="large"])` | Large size overrides                                                                                    |
+
+## Reactive State Mapping
+
+`cv-switch` is a visual adapter over headless `createSwitch`.
+
+| UIKit Property | Direction      | Headless Binding                                                                                                      |
+| -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `checked`      | attr -> action | `actions.setOn(value)`                                                                                                |
+| `disabled`     | attr -> action | `actions.setDisabled(value)`                                                                                          |
+| `help-text`    | attr -> option | When present, generates an id for the help-text element and passes it as `ariaDescribedBy` in `createSwitch(options)` |
+
+| Headless State       | Direction     | DOM Reflection              |
+| -------------------- | ------------- | --------------------------- |
+| `state.isOn()`       | state -> attr | `[checked]` host attribute  |
+| `state.isDisabled()` | state -> attr | `[disabled]` host attribute |
+
+- `contracts.getSwitchProps()` is spread onto the inner `[part="control"]` element to apply `role`, `aria-checked`, `aria-disabled`, `tabindex`, and keyboard/click handlers.
+- When help text is present (via attribute or slot), the component generates the id `{idBase}-help-text` for the help-text element and passes it as the `ariaDescribedBy` option to `createSwitch`, which produces the `aria-describedby` attribute in `getSwitchProps()`.
+- UIKit dispatches `cv-input` and `cv-change` events by observing `isOn` changes triggered by user activation (not by controlled `setOn`).
+- Toggled/untoggled slot visibility is purely visual (CSS-driven); no headless state or ARIA changes are involved.
+- UIKit does not own toggle or keyboard logic; headless state is the source of truth.
+
+## Events
+
+| Event       | Detail               | Description                      |
+| ----------- | -------------------- | -------------------------------- |
+| `cv-input`  | `{checked: boolean}` | Fires on toggle interaction      |
+| `cv-change` | `{checked: boolean}` | Fires when checked state commits |
+
+## Usage
+
+```html
+<cv-switch>Dark mode</cv-switch>
+
+<cv-switch checked>Notifications</cv-switch>
+
+<cv-switch disabled>Locked setting</cv-switch>
+
+<cv-switch size="small">Compact</cv-switch>
+
+<cv-switch size="large">Large toggle</cv-switch>
+
+<cv-switch help-text="Reduces blue light emission after sunset"> Night mode </cv-switch>
+
+<cv-switch>
+  Airplane mode
+  <span slot="help-text">Disables all wireless connections</span>
+</cv-switch>
+
+<cv-switch checked>
+  Wi-Fi
+  <cv-icon slot="toggled" name="wifi-on"></cv-icon>
+  <cv-icon slot="untoggled" name="wifi-off"></cv-icon>
+</cv-switch>
+
+<cv-switch>
+  Sound
+  <span slot="toggled">ON</span>
+  <span slot="untoggled">OFF</span>
+</cv-switch>
+```