@chromvoid/uikit 0.1.0

package/specs/components/accordion.md

@@ -0,0 +1,207 @@
+# cv-accordion
+
+Vertically stacked set of interactive sections that expand or collapse to reveal content.
+
+**Headless:** [`createAccordion`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/accordion.md)
+
+## Anatomy
+
+```
+<cv-accordion> (host)
+└── <section part="base" aria-label="…">
+    └── <slot>                                     ← cv-accordion-item elements
+```
+
+## Attributes
+
+| Attribute             | Type    | Default | Description                                                                                  |
+| --------------------- | ------- | ------- | -------------------------------------------------------------------------------------------- |
+| `value`               | String  | `""`    | Expanded section value (single mode). Reflects the first expanded item's `value`.            |
+| `allow-multiple`      | Boolean | `false` | Allow multiple sections expanded simultaneously                                              |
+| `allow-zero-expanded` | Boolean | `true`  | Allow all sections to be collapsed. When `false`, at least one section must remain expanded. |
+| `heading-level`       | Number  | `3`     | Heading level (1–6) for all item headers                                                     |
+| `aria-label`          | String  | `""`    | Accessible label for the accordion group                                                     |
+
+**JS-only property:**
+
+| Property         | Type       | Default | Description                                                            |
+| ---------------- | ---------- | ------- | ---------------------------------------------------------------------- |
+| `expandedValues` | `string[]` | `[]`    | Array of expanded section values (meaningful in `allow-multiple` mode) |
+
+## Slots
+
+| Slot        | Description                  |
+| ----------- | ---------------------------- |
+| `(default)` | `cv-accordion-item` elements |
+
+## CSS Parts
+
+| Part   | Element     | Description                    |
+| ------ | ----------- | ------------------------------ |
+| `base` | `<section>` | Root wrapper with `aria-label` |
+
+## CSS Custom Properties
+
+| Property             | Default                  | Description                     |
+| -------------------- | ------------------------ | ------------------------------- |
+| `--cv-accordion-gap` | `var(--cv-space-2, 8px)` | Spacing between accordion items |
+
+## Visual States
+
+| Host selector             | Description                       |
+| ------------------------- | --------------------------------- |
+| `:host([allow-multiple])` | Multiple sections can be expanded |
+
+## Events
+
+| Event       | Detail                      | Description                                                |
+| ----------- | --------------------------- | ---------------------------------------------------------- |
+| `cv-input`  | `{value, values, activeId}` | Fires on any interaction (expand/collapse or focus change) |
+| `cv-change` | `{value, values, activeId}` | Fires only when expanded sections change                   |
+
+**Event detail shape:**
+
+| Field      | Type             | Description                                  |
+| ---------- | ---------------- | -------------------------------------------- |
+| `value`    | `string \| null` | First expanded item value, or `null` if none |
+| `values`   | `string[]`       | All expanded item values                     |
+| `activeId` | `string \| null` | Currently focused item value                 |
+
+## Usage
+
+```html
+<!-- Single mode (default) -->
+<cv-accordion>
+  <cv-accordion-item value="about">
+    <span slot="trigger">About</span>
+    <p>About section content.</p>
+  </cv-accordion-item>
+  <cv-accordion-item value="faq">
+    <span slot="trigger">FAQ</span>
+    <p>Frequently asked questions.</p>
+  </cv-accordion-item>
+</cv-accordion>
+
+<!-- Multiple mode -->
+<cv-accordion allow-multiple>
+  <cv-accordion-item value="a" expanded>
+    <span slot="trigger">Section A</span>
+    <p>Content A</p>
+  </cv-accordion-item>
+  <cv-accordion-item value="b">
+    <span slot="trigger">Section B</span>
+    <p>Content B</p>
+  </cv-accordion-item>
+</cv-accordion>
+
+<!-- Exact-exclusive (one must stay open) -->
+<cv-accordion value="intro" :allow-zero-expanded="false">
+  <cv-accordion-item value="intro">
+    <span slot="trigger">Introduction</span>
+    <p>Intro content.</p>
+  </cv-accordion-item>
+  <cv-accordion-item value="details">
+    <span slot="trigger">Details</span>
+    <p>Details content.</p>
+  </cv-accordion-item>
+</cv-accordion>
+
+<!-- Custom heading level -->
+<cv-accordion heading-level="4">
+  <cv-accordion-item value="s1">
+    <span slot="trigger">Under an h3</span>
+    <p>Content here.</p>
+  </cv-accordion-item>
+</cv-accordion>
+
+<!-- Custom icons -->
+<cv-accordion>
+  <cv-accordion-item value="custom">
+    <span slot="trigger">Custom icons</span>
+    <cv-icon name="plus" slot="expand-icon"></cv-icon>
+    <cv-icon name="minus" slot="collapse-icon"></cv-icon>
+    <p>Content with plus/minus icons.</p>
+  </cv-accordion-item>
+</cv-accordion>
+
+<!-- Disabled item -->
+<cv-accordion>
+  <cv-accordion-item value="enabled">
+    <span slot="trigger">Enabled</span>
+    <p>This section works.</p>
+  </cv-accordion-item>
+  <cv-accordion-item value="locked" disabled>
+    <span slot="trigger">Locked</span>
+    <p>This section cannot be toggled.</p>
+  </cv-accordion-item>
+</cv-accordion>
+```
+
+## Child Elements
+
+### cv-accordion-item
+
+#### Anatomy
+
+```
+<cv-accordion-item> (host)
+└── <div part="base">
+    ├── <h3 part="header" id="…">          ← heading level from parent
+    │   └── <button part="trigger" aria-expanded="…" aria-controls="…">
+    │       ├── <slot name="trigger">       ← header label
+    │       └── <span part="indicator" aria-hidden="true">
+    │           ├── <slot name="expand-icon">▶</slot>   ← shown when collapsed
+    │           └── <slot name="collapse-icon">▶</slot>  ← shown when expanded (rotated)
+    └── <div part="panel" role="region" aria-labelledby="…">
+        └── <slot>                          ← panel content
+```
+
+#### Attributes
+
+| Attribute  | Type    | Default | Description                                                                   |
+| ---------- | ------- | ------- | ----------------------------------------------------------------------------- |
+| `value`    | String  | `""`    | Unique identifier for this section. Auto-generated as `section-{n}` if empty. |
+| `disabled` | Boolean | `false` | Prevents toggling this section                                                |
+| `expanded` | Boolean | `false` | Whether panel content is visible (reflected, managed by parent)               |
+| `active`   | Boolean | `false` | Whether this item's trigger has roving focus (reflected, managed by parent)   |
+
+#### Slots
+
+| Slot            | Description                                                       |
+| --------------- | ----------------------------------------------------------------- |
+| `(default)`     | Panel content                                                     |
+| `trigger`       | Header label text                                                 |
+| `expand-icon`   | Icon shown when the panel is collapsed. Default: `▶`              |
+| `collapse-icon` | Icon shown when the panel is expanded. Default: `▶` (rotated 90°) |
+
+#### CSS Parts
+
+| Part        | Element    | Description                                                    |
+| ----------- | ---------- | -------------------------------------------------------------- |
+| `base`      | `<div>`    | Root wrapper                                                   |
+| `header`    | `<h3>`     | Heading element (level controlled by parent's `heading-level`) |
+| `trigger`   | `<button>` | Interactive toggle button                                      |
+| `indicator` | `<span>`   | Wrapper around expand/collapse icon slots                      |
+| `panel`     | `<div>`    | Expandable content region                                      |
+
+#### CSS Custom Properties
+
+| Property                                     | Default                          | Description                                |
+| -------------------------------------------- | -------------------------------- | ------------------------------------------ |
+| `--cv-accordion-item-trigger-min-height`     | `36px`                           | Minimum height of the trigger button       |
+| `--cv-accordion-item-trigger-padding-inline` | `var(--cv-space-3, 12px)`        | Horizontal padding of trigger              |
+| `--cv-accordion-item-trigger-border-radius`  | `var(--cv-radius-sm, 6px)`       | Border radius of trigger                   |
+| `--cv-accordion-item-trigger-gap`            | `var(--cv-space-2, 8px)`         | Gap between trigger label and icon         |
+| `--cv-accordion-item-panel-padding`          | `var(--cv-space-3, 12px)`        | Padding inside the panel                   |
+| `--cv-accordion-item-panel-border-radius`    | `var(--cv-radius-sm, 6px)`       | Border radius of panel                     |
+| `--cv-accordion-item-gap`                    | `var(--cv-space-1, 4px)`         | Gap between trigger and panel              |
+| `--cv-accordion-item-indicator-size`         | `16px`                           | Size of the indicator icon area            |
+| `--cv-accordion-item-duration`               | `var(--cv-duration-fast, 120ms)` | Transition duration for indicator rotation |
+
+#### Visual States
+
+| Host selector       | Description                                                                                      |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| `:host([expanded])` | Panel visible; collapse-icon shown, expand-icon hidden; indicator rotated 90° (for default icon) |
+| `:host([active])`   | Trigger has roving focus; border highlighted with `--cv-color-primary`                           |
+| `:host([disabled])` | Trigger opacity reduced (`0.55`), `cursor: not-allowed`, interaction blocked                     |

package/specs/components/alert.md

@@ -0,0 +1,83 @@
+# cv-alert
+
+Passive live-region message that announces important updates without taking focus.
+
+**Headless:** [`createAlert`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/alert.md)
+
+## Anatomy
+
+```
+<cv-alert> (host)
+└── <div part="base" role="alert">
+    ├── <div part="message">  ← current message text
+    └── <slot>                  ← optional additional static content
+```
+
+## Attributes
+
+| Attribute     | Type            | Default       | Description                                                |
+| ------------- | --------------- | ------------- | ---------------------------------------------------------- |
+| `duration-ms` | Number          | `0`           | Auto-hide timeout in milliseconds (`0` disables auto-hide) |
+| `aria-live`   | String          | `"assertive"` | Live-region priority: `assertive` \| `polite`              |
+| `aria-atomic` | Boolean         | `true`        | Announces the whole region when content changes            |
+| `visible`     | Boolean (state) | `false`       | Reflected visibility state managed by component state      |
+
+## Slots
+
+| Slot        | Description                                            |
+| ----------- | ------------------------------------------------------ |
+| `(default)` | Optional static, non-interactive supplementary content |
+
+## CSS Parts
+
+| Part      | Element | Description                                           |
+| --------- | ------- | ----------------------------------------------------- |
+| `base`    | `<div>` | Live-region wrapper carrying role and ARIA attributes |
+| `message` | `<div>` | Current message text                                  |
+
+## CSS Custom Properties
+
+| Property                         | Default                                     | Description                             |
+| -------------------------------- | ------------------------------------------- | --------------------------------------- |
+| `--cv-alert-gap`                 | `var(--cv-space-2, 8px)`                    | Gap between message and slotted content |
+| `--cv-alert-padding-inline`      | `var(--cv-space-3, 12px)`                   | Horizontal padding for alert container  |
+| `--cv-alert-padding-block`       | `var(--cv-space-2, 8px)`                    | Vertical padding for alert container    |
+| `--cv-alert-radius`              | `var(--cv-radius-sm, 6px)`                  | Border radius                           |
+| `--cv-alert-border-color`        | `var(--cv-color-border, #2a3245)`           | Border color                            |
+| `--cv-alert-background`          | `var(--cv-color-surface-elevated, #1d2432)` | Background color                        |
+| `--cv-alert-color`               | `var(--cv-color-text, #e8ecf6)`             | Text color                              |
+| `--cv-alert-transition-duration` | `var(--cv-duration-fast, 120ms)`            | Transition duration for show/hide       |
+| `--cv-alert-transition-easing`   | `var(--cv-easing-standard, ease)`           | Transition timing function              |
+| `--cv-alert-hidden-translate-y`  | `-2px`                                      | Vertical offset when hidden             |
+
+## Visual States
+
+| Host selector            | Description                                             |
+| ------------------------ | ------------------------------------------------------- |
+| `:host([visible])`       | Visible state; base is fully opaque and interactive     |
+| `:host(:not([visible]))` | Hidden state; base fades and translates slightly upward |
+
+## Events
+
+| Event       | Detail                                | Description                    |
+| ----------- | ------------------------------------- | ------------------------------ |
+| `cv-input`  | `{visible: boolean, message: string}` | Fires when alert state updates |
+| `cv-change` | `{visible: boolean, message: string}` | Fires when visibility toggles  |
+
+## Accessibility
+
+- Root element always uses `role="alert"`.
+- `aria-live` and `aria-atomic` are sourced from headless `getAlertProps()`.
+- Component is passive and does not move focus or manage keyboard interaction.
+- For interactive/decision-required flows, use `cv-alert-dialog`.
+
+## Usage
+
+```html
+<cv-alert id="saved-alert"></cv-alert>
+
+<script type="module">
+  const alert = document.getElementById('saved-alert')
+  alert.show('Configuration saved successfully')
+</script>
+```

package/specs/components/badge.md

@@ -0,0 +1,183 @@
+# cv-badge
+
+Non-interactive status indicator that displays short labels, counts, or colored dots.
+
+**Headless:** [`createBadge`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/badge.md)
+
+## Anatomy
+
+```
+<cv-badge> (host)
+└── <div part="base">
+    ├── <span part="prefix">
+    │   └── <slot name="prefix">
+    ├── <span part="label">           ← hidden when [dot]
+    │   └── <slot>
+    └── <span part="suffix">
+        └── <slot name="suffix">
+```
+
+## Attributes
+
+| Attribute    | Type    | Default     | Description                                                                            |
+| ------------ | ------- | ----------- | -------------------------------------------------------------------------------------- |
+| `variant`    | String  | `"neutral"` | Visual variant: `"primary"` \| `"success"` \| `"neutral"` \| `"warning"` \| `"danger"` |
+| `size`       | String  | `"medium"`  | Size: `"small"` \| `"medium"` \| `"large"`                                             |
+| `dot`        | Boolean | `false`     | Dot mode: hides textual content, shows a colored circle indicator                      |
+| `pulse`      | Boolean | `false`     | Enables a pulsing animation to draw attention                                          |
+| `pill`       | Boolean | `false`     | Fully rounded edges (`border-radius: 999px`)                                           |
+| `dynamic`    | Boolean | `false`     | Enables live-region semantics for runtime content changes                              |
+| `decorative` | Boolean | `false`     | Hides the badge from assistive technology                                              |
+
+## Variants
+
+| Variant   | Description                                                     |
+| --------- | --------------------------------------------------------------- |
+| `neutral` | Default muted style with surface background and border          |
+| `primary` | Primary-tinted background and border using `--cv-color-primary` |
+| `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`   |
+
+The `dot`, `pulse`, and `pill` boolean modifiers can be combined with any variant.
+
+## Sizes
+
+| Size     | `--cv-badge-height` | `--cv-badge-padding-inline` | `--cv-badge-font-size` | `--cv-badge-dot-size` |
+| -------- | ------------------- | --------------------------- | ---------------------- | --------------------- |
+| `small`  | `20px`              | `var(--cv-space-1, 4px)`    | `11px`                 | `6px`                 |
+| `medium` | `24px`              | `var(--cv-space-2, 8px)`    | `12px`                 | `8px`                 |
+| `large`  | `28px`              | `var(--cv-space-3, 12px)`   | `14px`                 | `10px`                |
+
+## Slots
+
+| Slot        | Description                      |
+| ----------- | -------------------------------- |
+| `(default)` | Badge label (hidden in dot mode) |
+| `prefix`    | Icon or element before label     |
+| `suffix`    | Icon or element after label      |
+
+## CSS Parts
+
+| Part     | Element  | Description                                                               |
+| -------- | -------- | ------------------------------------------------------------------------- |
+| `base`   | `<div>`  | Root wrapper element; receives headless `getBadgeProps()` ARIA attributes |
+| `label`  | `<span>` | Wrapper around the default slot (hidden when `dot` is `true`)             |
+| `prefix` | `<span>` | Wrapper around the `prefix` slot                                          |
+| `suffix` | `<span>` | Wrapper around the `suffix` slot                                          |
+
+## CSS Custom Properties
+
+| Property                    | Default                    | Description                               |
+| --------------------------- | -------------------------- | ----------------------------------------- |
+| `--cv-badge-height`         | `24px`                     | Block size of the badge                   |
+| `--cv-badge-padding-inline` | `var(--cv-space-2, 8px)`   | Horizontal padding                        |
+| `--cv-badge-border-radius`  | `var(--cv-radius-sm, 6px)` | Border radius for badge shape             |
+| `--cv-badge-gap`            | `var(--cv-space-1, 4px)`   | Spacing between badge content parts       |
+| `--cv-badge-font-size`      | `12px`                     | Font size of badge content                |
+| `--cv-badge-dot-size`       | `8px`                      | Diameter of the dot indicator in dot mode |
+
+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-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 used for badge 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 |
+
+## Visual States
+
+| Host selector                | Description                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------- |
+| `:host([variant="neutral"])` | Default muted background with border                                                   |
+| `:host([variant="primary"])` | Primary-tinted background and border                                                   |
+| `: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([dot])`               | Dot mode: hides label/prefix/suffix, renders a colored circle of `--cv-badge-dot-size` |
+| `:host([pulse])`             | Applies a repeating scale/opacity animation to draw attention                          |
+| `:host([pill])`              | Fully rounded edges (`border-radius: 999px`)                                           |
+| `:host([size="small"])`      | Small size overrides                                                                   |
+| `:host([size="large"])`      | Large size overrides                                                                   |
+| `:host([dot][pulse])`        | Dot with pulse animation combined                                                      |
+| `:host([decorative])`        | Decorative mode; no visual change, ARIA-hidden via headless                            |
+
+## Reactive State Mapping
+
+`cv-badge` is a visual adapter over headless `createBadge`.
+
+| UIKit Property | Direction      | Headless Binding                                |
+| -------------- | -------------- | ----------------------------------------------- |
+| `variant`      | attr -> action | `actions.setVariant(value)`                     |
+| `size`         | attr -> action | `actions.setSize(value)`                        |
+| `dot`          | attr -> action | `actions.setDot(value)`                         |
+| `pulse`        | attr -> action | `actions.setPulse(value)`                       |
+| `pill`         | attr -> action | `actions.setPill(value)`                        |
+| `dynamic`      | attr -> action | `actions.setDynamic(value)`                     |
+| `decorative`   | attr -> action | `actions.setDecorative(value)`                  |
+| `aria-label`   | attr -> option | passed as `ariaLabel` in `createBadge(options)` |
+
+| Headless State    | Direction     | DOM Reflection                                                           |
+| ----------------- | ------------- | ------------------------------------------------------------------------ |
+| `state.variant()` | state -> attr | `[variant]` host attribute                                               |
+| `state.size()`    | state -> attr | `[size]` host attribute                                                  |
+| `state.dot()`     | state -> attr | `[dot]` host attribute                                                   |
+| `state.pulse()`   | state -> attr | `[pulse]` host attribute                                                 |
+| `state.pill()`    | state -> attr | `[pill]` host attribute                                                  |
+| `state.isEmpty()` | state -> DOM  | Hides `[part="label"]`, `[part="prefix"]`, `[part="suffix"]` when `true` |
+
+- `contracts.getBadgeProps()` is spread onto the inner `[part="base"]` element to apply `role`, `aria-live`, `aria-atomic`, `aria-hidden`, and `aria-label` as applicable.
+- UIKit does not own ARIA logic; headless state is the source of truth for all accessibility attributes.
+- Badge is non-interactive: no `tabindex`, no keyboard handlers, no focus management.
+
+## Events
+
+Badge is non-interactive. No `input`, `change`, or custom events are emitted.
+
+## Usage
+
+```html
+<cv-badge>Default</cv-badge>
+
+<cv-badge variant="primary">New</cv-badge>
+
+<cv-badge variant="success">Active</cv-badge>
+
+<cv-badge variant="warning">Pending</cv-badge>
+
+<cv-badge variant="danger">Error</cv-badge>
+
+<cv-badge variant="danger" dot></cv-badge>
+
+<cv-badge variant="primary" dot pulse aria-label="New notifications"></cv-badge>
+
+<cv-badge variant="primary" pill>Badge</cv-badge>
+
+<cv-badge variant="success" size="small">3</cv-badge>
+
+<cv-badge variant="danger" size="large">99+</cv-badge>
+
+<cv-badge dynamic variant="primary">5</cv-badge>
+
+<cv-badge decorative variant="neutral">Info</cv-badge>
+
+<cv-badge variant="primary">
+  <icon-circle slot="prefix"></icon-circle>
+  Online
+</cv-badge>
+
+<cv-badge variant="danger">
+  Alerts
+  <icon-bell slot="suffix"></icon-bell>
+</cv-badge>
+```

package/specs/components/breadcrumb.md

@@ -0,0 +1,152 @@
+# cv-breadcrumb
+
+Navigation landmark that displays a trail of links showing the user's current location within a hierarchical structure.
+
+**Headless:** [`createBreadcrumb`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/breadcrumb.md)
+
+## Anatomy
+
+```
+<cv-breadcrumb> (host)
+└── <nav part="base" role="navigation" aria-label="Breadcrumb">
+    └── <ol part="list">
+        └── <slot>                              ← cv-breadcrumb-item elements
+```
+
+## Attributes
+
+| Attribute         | Type   | Default        | Description                                                                                                |
+| ----------------- | ------ | -------------- | ---------------------------------------------------------------------------------------------------------- |
+| `value`           | String | `""`           | Value of the current (active) breadcrumb item. Reflects and controls which item has `aria-current="page"`. |
+| `aria-label`      | String | `"Breadcrumb"` | Accessible label for the navigation landmark                                                               |
+| `aria-labelledby` | String | `""`           | ID of an element that labels the navigation landmark. When set, `aria-label` is omitted.                   |
+
+## Slots
+
+| Slot        | Description                   |
+| ----------- | ----------------------------- |
+| `(default)` | `cv-breadcrumb-item` elements |
+
+## CSS Parts
+
+| Part   | Element | Description                                 |
+| ------ | ------- | ------------------------------------------- |
+| `base` | `<nav>` | Navigation landmark wrapper                 |
+| `list` | `<ol>`  | Ordered list container for breadcrumb items |
+
+## CSS Custom Properties
+
+| Property              | Default                  | Description                  |
+| --------------------- | ------------------------ | ---------------------------- |
+| `--cv-breadcrumb-gap` | `var(--cv-space-2, 8px)` | Gap between breadcrumb items |
+
+## Events
+
+No component-specific events. Navigation uses standard link click behavior.
+
+## Usage
+
+```html
+<cv-breadcrumb>
+  <cv-breadcrumb-item value="home" href="/">Home</cv-breadcrumb-item>
+  <cv-breadcrumb-item value="docs" href="/docs">Docs</cv-breadcrumb-item>
+  <cv-breadcrumb-item value="api" href="/docs/api">API</cv-breadcrumb-item>
+</cv-breadcrumb>
+
+<!-- Controlled current item -->
+<cv-breadcrumb value="docs">
+  <cv-breadcrumb-item value="home" href="/">Home</cv-breadcrumb-item>
+  <cv-breadcrumb-item value="docs" href="/docs">Docs</cv-breadcrumb-item>
+  <cv-breadcrumb-item value="api" href="/docs/api">API</cv-breadcrumb-item>
+</cv-breadcrumb>
+
+<!-- Custom aria-label -->
+<cv-breadcrumb aria-label="You are here">
+  <cv-breadcrumb-item value="home" href="/">Home</cv-breadcrumb-item>
+  <cv-breadcrumb-item value="page" href="/page">Current Page</cv-breadcrumb-item>
+</cv-breadcrumb>
+
+<!-- With prefix icons -->
+<cv-breadcrumb>
+  <cv-breadcrumb-item value="home" href="/">
+    <cv-icon name="home" slot="prefix"></cv-icon>
+    Home
+  </cv-breadcrumb-item>
+  <cv-breadcrumb-item value="settings" href="/settings">Settings</cv-breadcrumb-item>
+</cv-breadcrumb>
+
+<!-- Custom separator -->
+<cv-breadcrumb>
+  <cv-breadcrumb-item value="home" href="/">
+    Home
+    <span slot="separator">→</span>
+  </cv-breadcrumb-item>
+  <cv-breadcrumb-item value="page" href="/page">Page</cv-breadcrumb-item>
+</cv-breadcrumb>
+```
+
+## Child Elements
+
+### cv-breadcrumb-item
+
+#### Anatomy
+
+```
+<cv-breadcrumb-item> (host)
+├── <span part="prefix">
+│   └── <slot name="prefix">
+├── <a part="link" role="link" href="…" aria-current="page"?>
+│   └── <slot>                                  ← label text
+├── <span part="suffix">
+│   └── <slot name="suffix">
+└── <span part="separator" aria-hidden="true">
+    └── <slot name="separator">/</slot>
+```
+
+#### Attributes
+
+| Attribute        | Type    | Default | Description                                                                                                   |
+| ---------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------- |
+| `value`          | String  | `""`    | Unique identifier for this item. Auto-generated as `item-{n}` if empty.                                       |
+| `href`           | String  | `""`    | URL destination. Defaults to `#` if empty.                                                                    |
+| `current`        | Boolean | `false` | Whether this item represents the current page. Managed by parent, reflects `aria-current="page"` on the link. |
+| `show-separator` | Boolean | `true`  | Whether the separator is visible. Managed by parent — hidden on the last item.                                |
+
+**Internal property (not reflected):**
+
+| Property | Type   | Default | Description                                                       |
+| -------- | ------ | ------- | ----------------------------------------------------------------- |
+| `linkId` | String | `""`    | DOM id for the link element, set by parent from headless contract |
+
+#### Slots
+
+| Slot        | Description                           |
+| ----------- | ------------------------------------- |
+| `(default)` | Label text                            |
+| `prefix`    | Icon or element before the label      |
+| `suffix`    | Icon or element after the label       |
+| `separator` | Separator between items. Default: `/` |
+
+#### CSS Parts
+
+| Part        | Element  | Description                                    |
+| ----------- | -------- | ---------------------------------------------- |
+| `link`      | `<a>`    | The anchor element                             |
+| `prefix`    | `<span>` | Prefix container                               |
+| `suffix`    | `<span>` | Suffix container                               |
+| `separator` | `<span>` | Separator container (has `aria-hidden="true"`) |
+
+#### CSS Custom Properties
+
+| Property                                   | Default                  | Description                                     |
+| ------------------------------------------ | ------------------------ | ----------------------------------------------- |
+| `--cv-breadcrumb-item-gap`                 | `var(--cv-space-2, 8px)` | Gap between prefix, link, suffix, and separator |
+| `--cv-breadcrumb-item-separator-opacity`   | `0.6`                    | Opacity of the separator                        |
+| `--cv-breadcrumb-item-current-font-weight` | `600`                    | Font weight of the current item's link          |
+
+#### Visual States
+
+| Host selector                   | Description                                                       |
+| ------------------------------- | ----------------------------------------------------------------- |
+| `:host([current])`              | Current page — link has `font-weight: 600`, `aria-current="page"` |
+| `:host(:not([show-separator]))` | Separator hidden (last item)                                      |