@openreachtech/furo-vue 1.6.0 → 2.0.0

package/docs/furo-sidebar.md

@@ -0,0 +1,178 @@
+# `<FuroSidebar>` Interface Specification
+
+## Overview
+
+`<FuroSidebar>` is a **shipped** navigation organism in the Furo-Vue component system. It is the rail an application navigates from: a column of grouped items, each optionally disclosing a nested run of its own, with a search entry above them and a collapsed form that narrows to the icon boxes.
+
+Navigation items arrive as data. The component never knows what an item means, only that it has a key, a label and possibly children, so the same rail serves a catalogue, a console or a document store as readily as a customer list.
+
+**Public SFC prop:** `parcel` only. Every other HTML attribute lands on the `nav` element.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Organism |
+| **Path** | `lib/components/organisms/FuroSidebar/` |
+| **Base primitive** | None; a `nav` holding lists of buttons |
+| **Emits** | `navigate`, `update:activeKey`, `expand-change`, `update:expandedKeys`, `search-change`, `search-commit`, `update:searchValue` |
+| **Composes** | `FuroSearchField` for the search entry, `FuroIcon` for item icons and the disclosure caret |
+
+## What this is not
+
+The design uses the word sidebar for two different surfaces: this navigation rail on the left of every screen, and a panel on the right of the detail view holding a record's comments and mail. Only the first is here. The second carries the meaning of a record and stays in the consuming application.
+
+`FuroOffCanvasMenuLayout` is untouched by this component. It is excluded from the published package and is a layout, not a navigation surface.
+
+## `parcel` keys
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `groups` | `Array<FuroSidebarGroup>` | `[]` | Runs of items, each with an optional heading. |
+| `activeKey` | `string \| null` | — | The key the application currently shows. Absent by default. |
+| `expandedKeys` | `Array<string> \| null` | — | The keys whose sub-items are revealed. Absent by default. |
+| `collapsed` | `boolean` | `false` | Narrows the rail to its icon boxes. |
+| `searchable` | `boolean` | `false` | Renders the search entry above the groups. |
+| `searchValue` | `string \| null` | `null` | The text the search entry holds. |
+| `searchPlaceholder` | `string \| null` | `null` | Placeholder of the search entry. |
+| `searchLabel` | `string` | `'Search'` | Accessible name of the search entry. |
+| `label` | `string` | `'Sidebar'` | Accessible name of the navigation landmark. |
+
+### Types
+
+```text
+FuroSidebarGroup   { key: string, label?: string | null, items?: Array<FuroSidebarItem> }
+FuroSidebarItem    { key: string, label: string, icon?: string | null, disabled?: boolean, items?: Array<FuroSidebarSubItem> }
+FuroSidebarSubItem { key: string, label: string, disabled?: boolean }
+```
+
+A group is how the design separates one run of items from the next: the first run carries no heading, the later ones do. A flat rail is therefore one group with no `label`.
+
+## Controlled and uncontrolled
+
+`activeKey` and `expandedKeys` follow the same rule `FuroTabs` uses, and the presence of the key decides, not its value:
+
+| Parcel | Meaning |
+|---|---|
+| Key absent | Uncontrolled. The rail holds the value internally, which is what makes the playground and a quick prototype work with no handler. |
+| Key present with a value | Controlled. The rail draws what you pass and reports every change without moving on its own. |
+| Key present and `null` | Controlled with nothing selected. The rail highlights no row and still moves nowhere on its own. |
+
+Pass `activeKey: null` to say "I own this, and right now nothing is selected". A sentinel such as an empty string is never needed.
+
+`collapsed` has no uncontrolled form, because the control that toggles it is drawn in the application header, not in the rail. The rail takes the state and never toggles itself.
+
+## Routing
+
+The rail emits navigation intent and never imports a router. Two ways to wire it, and they are exclusive:
+
+1. **Listen to `navigate`.** The default item is a `button`, and choosing it emits `{ key, parentKey }`. The application maps the key to whatever it routes with. This is the default because a key is a value, so the rail stays serialisable and testable, and it does not force a router to exist.
+2. **Fill the `item` and `sub-item` slots.** The slot replaces the whole button, so an application that wants real links renders `RouterLink` or `NuxtLink` there and gets middle-click, hover preview and copy-link for free. The rail still supplies `entry`, `active`, `expanded` and `collapsed`, so the slot content can look identical to the default.
+
+An item that declares `items` of its own is a disclosure: choosing it opens and closes its run and it does **not** emit `navigate`. The design gives such an item a caret rather than a destination. An item that is both a destination and a parent should carry its own destination as the first sub-item.
+
+## Events
+
+| Event | Payload | When |
+|---|---|---|
+| `navigate` | `{ key, parentKey }` | An item without sub-items, or a sub-item, is chosen. `parentKey` is `null` for a primary item. |
+| `update:activeKey` | `string` | Alongside `navigate`, which is what makes `v-model:active-key` work. |
+| `expand-change` | `{ key, expanded }` | A disclosure opens or closes. |
+| `update:expandedKeys` | `Array<string>` | Alongside `expand-change`, which is what makes `v-model:expanded-keys` work. |
+| `search-change` | Field payload | Every keystroke in the search entry. |
+| `search-commit` | Field payload | Blur and Enter in the search entry. |
+| `update:searchValue` | `string \| null` | Alongside both search events. |
+
+The search payload is the one `FuroSearchField` emits, so `payload.trimmedValue` and `payload.hasEnteredTrimmedText()` read the same as anywhere else.
+
+## Slots
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| `header` | — | Content above the search entry, for a product mark or an account switcher. |
+| `search` | — | Replaces the default search control while keeping its place in the rail. |
+| `item` | `{ entry, active, expanded, collapsed }` | Replaces the default primary button. |
+| `sub-item` | `{ entry, parent, active }` | Replaces the default nested button. |
+| `footer` | — | Content below the groups. |
+
+The product mark is a slot rather than a parcel key because a mark is an image and a wordmark, not a value, and because a design system that shipped one would be shipping somebody's brand.
+
+## States
+
+| State | What changes |
+|---|---|
+| Rest | Transparent row, title-tone label, icon in its own rounded box. |
+| Hover | The row takes the muted surface. |
+| Active | The row keeps the muted surface and carries `aria-current="page"`. |
+| Disclosure closed | A caret pointing down; the sub-items are not rendered. |
+| Disclosure open | The caret points up and the sub-items appear, connected by an elbow rule. |
+| Nested sub-item | Indented past the icon column, drawn in the caption tone until it is active. |
+| Disabled | The row dims and leaves the tab order. |
+| Collapsed | The rail narrows to the icon boxes; labels, headings, carets, sub-items and the search entry are dropped. |
+
+The search entry is dropped rather than squeezed when the rail collapses, because a collapsed rail is one icon box wide and no text control fits in it.
+
+## Styling
+
+| Part | Class | Notes |
+|---|---|---|
+| Root | `.unit-sidebar` | Gains `.collapsed` |
+| Header region | `.header` | Only rendered when the slot is filled |
+| Search region | `.search-entry` | Holds `FuroSearchField` |
+| Group | `.group` | One run of items |
+| Group heading | `.group-label` | Also names the list it heads |
+| Item list | `.items` | One `li.entry` per item |
+| Primary row | `.row` | Gains `.active` and `.disclosure` |
+| Icon box | `.row-icon` | The rounded square the design draws behind every glyph |
+| Disclosure caret | `.caret` | |
+| Sub-item list | `.sub-items` | One `li.sub-entry` per sub-item |
+| Nested sub-row | `.sub-row` | Gains `.active` |
+| Footer region | `.footer` | Only rendered when the slot is filled |
+
+## Read from the design
+
+Design node: `4047:22441`, the `Panel_side_bar` instance in the `List_view [Admin_list]` frame.
+
+| Part | Design value | Token |
+|---|---|---|
+| The rail | `#ffffff` | `--color-background` |
+| Its trailing edge | `1px` `#e0e2e6` | `--size-thinnest`, `--color-border` |
+| Its width | `256px` | `--size-sidebar-width` |
+| Its width, collapsed | not drawn | `--size-sidebar-width-collapsed` |
+| Its block padding | `12px` | `0.75rem` |
+| Its inline padding | `16px` | `1rem` |
+| Between groups | `12px` | `--size-space-compact` |
+| Between rows | `4px` | `--size-space-tiny` |
+| Group heading | `#8b93a2`, medium 12px/20 | `--color-foreground-secondary`, `--font-label-tiny` |
+| Group heading padding | `8px` | `0.5rem` |
+| Row corners | `10px` | `--size-border-radius-large` |
+| Row padding | `4px`, `10px` at the caret edge | `0.25rem`, `0.625rem` |
+| Between the icon box and the label | `12px` | `--size-space-compact` |
+| Row surface, current | `#f1f2f4` | `--color-muted` |
+| Row label | `#22252a`, medium 13.5px/20 | `--color-foreground-title`, `--font-label-small` |
+| Icon box | `#ffffff`, corners `8px`, padding `6px` | `--color-background`, `--size-border-radius-medium`, `0.375rem` |
+| Icon | `20px` | `1.25rem` |
+| Caret | `14px` | `0.875rem` |
+| Sub-item indent | `36px` | `2.25rem` |
+| Sub-item padding | `8px` block, `12px` inline | `0.5rem`, `0.75rem` |
+| Sub-item label | `#8b93a2`, medium 13.5px/20 | `--color-foreground-secondary`, `--font-label-small` |
+| Elbow connector | `1px` `#e0e2e6`, `16px` wide from `20px` | `--size-thinnest`, `--color-border`, `1rem` |
+
+Every colour above is the exact value the token already carries, so nothing is approximated: `#f1f2f4` is `--color-muted`, `#e0e2e6` is `--color-border`, `#22252a` is `--color-foreground-title` and `#8b93a2` is `--color-foreground-glyph`. The two text rows above read `--color-foreground-secondary` (`#646c7d`) instead, because `#8b93a2` is 3.09:1 on the page, under the 4.5:1 text floor. The two text styles are the composite tokens `--font-label-small` and `--font-label-tiny`, both carried through the `font` shorthand per [ADR 0032](./adr/0032-composite-text-style-tokens-via-font-shorthand.md).
+
+Four notes on what the design does and does not settle:
+
+- **The current row reads `#f1f2f4`, which is `--color-muted` rather than `--color-accent`.** `--color-accent` is the nominal role for a hover surface, but it carries `#e0e2e6`, one palette step darker than the design draws. The token that carries the drawn value wins, so hover and current both use `--color-muted`.
+- **The elbow connector is drawn in CSS, not as an asset.** The design draws it as three vector strokes. They are rules rather than glyphs, so a border on a pseudo-element reproduces them exactly and keeps them on `--color-border` in both themes.
+- **The collapsed width is the library's arithmetic, not a drawn value.** The design contains no collapsed navigation variant. The rail is `16px` of padding plus a `32px` icon box plus `16px` of padding, which is `64px`, and the file's icon-only rail (`4055:85083`) is drawn at exactly that width, though it is a different component. The value is the library's under [ADR 0041](./adr/0041-a-value-the-design-does-not-draw-is-the-librarys-to-choose.md) and moves by overriding `--size-sidebar-width-collapsed`. A drawn collapsed rail supersedes it.
+- **The search entry's place in the rail is the library's ordering.** No node draws a search inside a navigation rail. The design system library carries the search control as `Search_bar`, a component set bound to no container, so the design makes it composable without saying where it goes. The rail puts it under the `header` slot and above the groups, which is the order [#223](https://github.com/openreachtech/furo-vue/issues/223) listed, and the `search` slot replaces the control while keeping that place.
+
+The design's product mark is `20px` Roboto SemiBold on a `24px` line. No composite text token carries that pairing: `--font-headline-medium` is the nearest at `20px`, but on a `28px` line at weight `500`. The mark is a slot rather than component-drawn text, so the mismatch is the consuming application's to resolve and no token was invented for it.
+
+## Accessibility
+
+The root is a `nav` landmark named by `parcel.label`, so the rail is reachable by landmark rather than by scrolling to it. Each run of items is a `ul`, named by its heading when the group carries one, and each row is a real `button` inside an `li`, so a disabled row leaves the tab order for free.
+
+A disclosure row carries `aria-expanded` and keeps its sub-list inside the same `li`, which is the disclosure pattern a screen reader already knows. The row the application currently shows carries `aria-current="page"`.
+
+A collapsed row keeps its accessible name through `aria-label`, and its pointer name through `title`, because the label is no longer drawn. An expanded row does neither, so the name is not announced twice.

package/docs/furo-skeleton.md

@@ -0,0 +1,92 @@
+# FuroSkeleton
+
+Presentational loading placeholder shown while real content is fetching. A single styled box whose shape comes from the variant and whose size comes from optional width / height overrides. A shimmer animation signals the loading state. It carries no value and emits nothing.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroSkeleton/` |
+| **Base primitive** | None — a single styled box (no headless primitive needed) |
+| **Composes** | Nothing |
+| **Emits** | None |
+| **Variants** | `text` (default), `circle`, `rectangle` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `SkeletonParcel \| null` | `null` | Reactive data object holding the variant, size overrides, and animation flag. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'text' \| 'circle' \| 'rectangle'` | `'text'` | Placeholder shape. `circle` renders a round shape; `text` and `rectangle` use a small radius. |
+| `width` | `string` | variant default | CSS length overriding the width. Defaults to `100%` for `text` / `rectangle` and `2.5rem` for `circle`. |
+| `height` | `string` | variant default | CSS length overriding the height. Defaults to `1rem` for `text` / `rectangle` and `2.5rem` for `circle`. |
+| `animated` | `boolean` | `true` | When `true`, the placeholder shimmers. Reduced-motion users always see a static placeholder. |
+
+### Emits
+
+None. The skeleton is presentational.
+
+### Slots
+
+None.
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Variant** | `parcel.variant` maps to the `text` / `circle` / `rectangle` root class; no JS branching. |
+| **Sizing** | `parcel.width` / `parcel.height` feed `--furo-skeleton-width` / `--furo-skeleton-height`. Null overrides are dropped so the CSS fallback keeps the variant default. |
+| **Animation** | `isAnimated()` toggles the `animated` class. The shimmer is disabled under `prefers-reduced-motion: reduce`. |
+| **Semantics** | The box sets `aria-hidden="true"`; announce the loading state on the surrounding region. |
+| **Passthrough** | Extra attributes fall through to the box (`inheritAttrs: false` + `v-bind="$attrs"`). |
+
+---
+
+## Usage
+
+```vue
+<!-- Text line placeholder -->
+<FuroSkeleton :parcel="{ variant: 'text' }" />
+
+<!-- Avatar circle placeholder -->
+<FuroSkeleton :parcel="{ variant: 'circle', width: '3rem', height: '3rem' }" />
+
+<!-- Card block placeholder -->
+<FuroSkeleton :parcel="{ variant: 'rectangle', height: '8rem' }" />
+
+<!-- Static placeholder -->
+<FuroSkeleton :parcel="{ animated: false }" />
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- All logic lives in `FuroSkeletonContext` as extract-only getters (`variant`, `width`, `height`, `inlineStyle`) and one boolean method (`isAnimated()`).
+- CSS is wrapped in `@layer furo`; dimensions use `rem`, and the box color references the semantic `--color-muted` token only. The shimmer is a highlight of `--color-background` sweeping horizontally across that box once every 1.8s; under `prefers-reduced-motion: reduce` the highlight is removed with the animation, so the box stays a flat `--color-muted`.
+
+---
+
+## Testing
+
+- Context logic (`variant` / `width` / `height` / `inlineStyle` getters, `isAnimated()`) is fully covered by jsdom unit tests, with the boolean method split into truthy / falsy describe blocks.
+- No SFC mount test: behavior is declarative bindings over the tested context. Rendered output (variant class, animation, size) is verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Skeleton** tab. Demonstrates text lines, an avatar + lines row, a card block, and a static (non-animated) placeholder.

package/docs/furo-splitter.md

@@ -0,0 +1,103 @@
+# FuroSplitter
+
+A resizable split view that lays its child panes out side by side (or stacked) with a draggable handle between each pair. Panes are declared through a `panels` array; each pane's content is supplied via the scoped `panel` slot.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroSplitter/` |
+| **Base primitive** | Headless resizable split-pane group (`Group` + `Panel` + `ResizeHandle`) |
+| **Value** | Pane sizes (`Array<number>`, percent), surfaced outward via `update:value` |
+| **Emits** | `change-value`, `update:value` |
+| **Orientation** | `horizontal` (default) or `vertical` |
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `FuroSplitterParcel \| null` | `null` | Reactive configuration object. |
+
+Any extra attributes on the parcel that are not Furo-owned keys (e.g. `autoSaveId`, `aria-label`) are forwarded to the underlying group element.
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direction the panes are arranged in. |
+| `appearance` | `'default' \| 'plain'` | `'default'` | `default` shows a divider line between panes; `plain` hides it so panes read as separated cards (the grip appears on hover / focus only). |
+| `panels` | `Array<FuroSplitterPanel>` | `[]` | One descriptor per pane. A resize handle is inserted between consecutive panes. |
+
+### `FuroSplitterPanel`
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `id` | `string` | `pane-{index}` | Stable key; also used as the `panel` slot's `id` binding. |
+| `defaultSize` | `number` | auto | Initial size, in `sizeUnit`. |
+| `minSize` | `number` | `10` | Minimum size. |
+| `maxSize` | `number` | `100` | Maximum size. |
+| `collapsible` | `boolean` | `false` | Whether the pane collapses when dragged below `minSize`. |
+| `collapsedSize` | `number` | `0` | Size when collapsed. |
+| `sizeUnit` | `'%' \| 'px'` | `'%'` | Unit used to interpret the size values. |
+
+### Emits
+
+| Event | Payload | When |
+|---|---|---|
+| `change-value` | `SplitterEmitPayload` | A handle is dragged and the layout changes. Use `payload.layout` (and `payload.extractPaneSize({ index })`). |
+| `update:value` | `Array<number>` | Same moment as `change-value`; powers one-way `v-model:value` for persisting the layout. |
+
+### Slots
+
+| Slot | Props | Description |
+|---|---|---|
+| `panel` | `{ panel, index, id }` | Content for each pane. Switch on `id` or `index` to render the right region. |
+| `handle` | `{ index }` | Custom resize handle between panes. Defaults to a centered grip. |
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Layout source** | The underlying primitive owns the live layout; FuroSplitter reflects it outward. There is no inbound controlled `value`. |
+| **Persistence** | Forward `autoSaveId` through the parcel to let the primitive persist the arrangement in `localStorage`, or store the `update:value` layout yourself. |
+| **Handles** | A handle is rendered between every consecutive pair of panes, never after the last pane. |
+
+## Usage
+
+```vue
+<!-- Two panes, capture the layout -->
+<FuroSplitter
+  :parcel="{
+    orientation: 'horizontal',
+    panels: [
+      { id: 'sidebar', defaultSize: 30, minSize: 15 },
+      { id: 'main', defaultSize: 70 },
+    ],
+  }"
+  @change-value="onResize"
+>
+  <template #panel="{ id }">
+    <SidebarView v-if="id === 'sidebar'" />
+    <MainView v-else />
+  </template>
+</FuroSplitter>
+```
+
+## Composition notes
+
+- Imports nothing from the app, Nuxt, PrimeVue, or GraphQL.
+- Renders panes and handles from a declarative `panels` array — consumers never import the headless primitive's sub-components.
+- All logic lives in `FuroSplitterContext`; the template only calls context methods.
+- CSS is wrapped in `@layer furo` with the `unit-splitter` root class and semantic tokens only.
+
+## Testing
+
+- `FuroSplitterContext` is covered by jsdom unit tests (parcel defaults, class/attribute extraction, key resolution, last-pane detection, layout emit).
+- No SFC mount test — DOM resize behavior is exercised manually in the playground.
+
+## Playground
+
+`/samples/components/playground` → **Splitter** tab. Demonstrates horizontal, vertical, and three-pane (collapsible) layouts.

package/docs/furo-stepper.md

@@ -0,0 +1,127 @@
+# FuroStepper
+
+Organism — multi-step progress indicator built on a headless stepper primitive
+(`Root` + `Item` + `Trigger` + `Indicator` + `Separator` + `Title` +
+`Description`). Renders a step rail from a declarative `steps` list and an
+optional panel per step via named slots, tracking the active step and emitting
+changes. Supports horizontal/vertical orientation, a linear (no-forward-jump)
+mode, and an indicator-only strip. Consumed by `crm-kit-frontend`'s
+`FuroFormSequence` template. Domain-agnostic: no GraphQL, router, or Nuxt
+imports — the consumer wires the emitted step to its own state.
+
+Location: `lib/components/organisms/FuroStepper/`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `parcel` | `FuroStepperParcel \| null` | `null` | Reactive behavior object (below) |
+
+### `parcel`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `steps` | `Array<FuroStepperStep>` | `[]` | Step descriptors that drive the rail and panel slots (below). |
+| `value` | `number \| null` | — | Active step (1-based), where the presence of the key decides ownership. Absent, the component manages its own active step, defaulting to the first step. Present with a value, the parent owns the active step. Present and `null`, the parent owns it and no step is active. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction of the step rail. |
+| `linear` | `boolean` | `false` | When `true`, steps must be completed in order — forward jumps are blocked. |
+| `showPanels` | `boolean` | `true` | When `false`, no panels render — the component is an indicator strip only (the active value drives an external form region). |
+| `disabled` | `boolean` | `false` | Disables the whole stepper. |
+
+### `FuroStepperStep`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `value` | `string \| number` | — | Unique step identifier; also the default panel slot name and the suffix for `indicator-<value>` / `title-<value>` slots. |
+| `title` | `string` | `''` | Step label (overridable via the `title-<value>` slot). |
+| `description` | `string` | — | Optional secondary line under the title. |
+| `slotName` | `string` | `value` | Overrides the panel slot name for this step. |
+| `disabled` | `boolean` | `false` | Disables this single step. |
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `update:value` | `number` | Active step changed — enables `v-model:value`. |
+| `step:change` | `{ value: number }` | Active step changed. |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `<value>` (or `<slotName>`) | Panel content for the matching step. One slot per step, keyed by the step's `value` (or its `slotName` override), receiving `{ value, step }`. |
+| `indicator-<value>` | Custom indicator content for the matching step, receiving `{ step, value, completed }`. When omitted, the indicator shows a check icon when completed, else the step number. |
+| `title-<value>` | Custom title content for the matching step, receiving `{ value }`. When omitted, the title shows `title`. |
+
+## Usage
+
+### Uncontrolled
+
+```vue
+<FuroStepper
+  :parcel="{ steps: [
+    { value: 'account', title: 'Account' },
+    { value: 'profile', title: 'Profile' },
+    { value: 'review', title: 'Review' },
+  ]}"
+  @step:change="onStepChange($event.value)"
+>
+  <template #account>...account panel...</template>
+  <template #profile>...profile panel...</template>
+  <template #review>...review panel...</template>
+</FuroStepper>
+```
+
+### Controlled (`v-model:value`)
+
+```vue
+<FuroStepper
+  :parcel="{ value: activeStep, steps }"
+  @step:change="activeStep = $event.value"
+>
+  <template #account>...</template>
+  <template #profile>...</template>
+</FuroStepper>
+```
+
+### Vertical orientation
+
+```vue
+<FuroStepper :parcel="{ orientation: 'vertical', steps }">
+  <template #account>...</template>
+  <template #profile>...</template>
+</FuroStepper>
+```
+
+### Linear (no forward jumps)
+
+```vue
+<FuroStepper :parcel="{ linear: true, steps }">
+  <!-- panel slots per step -->
+</FuroStepper>
+```
+
+### Indicator strip (no panels)
+
+```vue
+<FuroStepper :parcel="{ showPanels: false, value: activeStep, steps }" />
+```
+
+### Custom indicator content
+
+```vue
+<FuroStepper :parcel="{ steps }">
+  <template #indicator-account>A</template>
+  <template #account>...</template>
+</FuroStepper>
+```
+
+## Notes
+
+- The active step is marked with `data-state="active"` and preceding steps with
+  `data-state="completed"` for styling; disabled steps are non-interactive.
+- Root CSS class: `unit-stepper` (inside `@layer furo`). Modifier classes:
+  `vertical` (orientation), `linear` (sequential mode), and `disabled` (whole
+  control disabled).
+- `value` is 1-based — the first step is `1`. Step numbers are derived from the
+  position of each entry in `steps`.

package/docs/furo-switch.md

@@ -0,0 +1,107 @@
+# `<FuroSwitch>` Interface Specification
+
+## Overview
+
+`<FuroSwitch>` is a **shipped** switch atom in the Furo-Vue component system. It is a track with a sliding knob, bound to a boolean: the control an application reaches for when a setting is on or off and the change takes effect immediately.
+
+**Public SFC prop:** `parcel` only. HTML attributes pass through to the root.
+
+## Why the name differs from the design's
+
+The design calls this a toggle. That word is already claimed in this library by `FuroToggle`, a pressed/unpressed button carrying text and the building block of `FuroToggleGroup` and `FuroToolBar`. One word carrying two meanings is what let the switch go missing from the component inventory in the first place, and it caused a real defect when `FuroToggle` was given the switch's fully rounded corner. So the component is named for what it is.
+
+The two are not interchangeable:
+
+| | `FuroSwitch` | `FuroToggle` |
+|---|---|---|
+| Shape | A track with a sliding knob | A button with a label |
+| Meaning | A setting is on or off | An action is currently applied |
+| Where the design uses it | Settings rows | An editor toolbar (bold, italic) |
+| Corner | Fully rounded | The medium step |
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Atom |
+| **Path** | `lib/components/atoms/FuroSwitch/` |
+| **Base primitive** | Headless switch (`Root` + `Thumb`) |
+| **Value** | `boolean`, through `parcel.value` and `v-model:value` |
+| **Emits** | `change-value`, `update:value` |
+
+## `parcel` keys
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `value` | `boolean` | `false` | On/off model. Declaring the key makes the switch controlled. |
+| `size` | `FuroSwitchSize` | `'medium'` | `medium` or `small`. |
+| `disabled` | `boolean` | `false` | Blocks interaction and repaints the track with the disabled colour. |
+| `required` | `boolean` | `false` | Marks the control required for the surrounding form. |
+
+Every other key on the parcel is forwarded to the root element untouched.
+
+## Controlled and uncontrolled
+
+The switch follows the same rule as `FuroCheckbox` and `FuroToggle`: **declaring `value` on the parcel is what makes it controlled**, not the value itself.
+
+- **Controlled** (`parcel` has a `value` key): the switch renders what the parent holds and never flips on its own. It reports the flip the user asked for and waits for the parent to hand the new value back.
+- **Uncontrolled** (`parcel` has no `value` key): the switch owns its state, flips itself, and reports the new value.
+
+`v-model:value` is the shorthand for the controlled form.
+
+## Events
+
+| Event | Payload | When |
+|---|---|---|
+| `change-value` | `SwitchEmitPayload` | Every flip. `payload.value` is the new boolean; `payload.isChecked()` and `payload.isUnchecked()` read it, and `payload.controlElement` is the root element. |
+| `update:value` | `boolean` | Every flip, alongside `change-value`. Backs `v-model:value`. |
+
+## Sizes
+
+The design draws two steps, not three. The internal spacing is 2px at both, so the knob and its travel follow the track height:
+
+| Size | Track | Knob | Travel |
+|---|---|---|---|
+| `medium` | 36px × 20px | 16px | 16px |
+| `small` | 28px × 16px | 12px | 12px |
+
+## Colours
+
+The switch reads the `--color-selected` family, so it re-themes with the checkbox and the radio rather than carrying blues of its own:
+
+| Part | Reads | The design's value |
+|---|---|---|
+| Track, on | `--color-selected` | blue-500 |
+| Track, on and hovered | `--color-selected-lighter` | blue-300 |
+| Track, on and pressed | `--color-selected-darker` | blue-700 |
+| Track, off | `--color-input` | the neutral every unfilled form control carries |
+| Track, disabled | `--color-secondary` | gray-200 |
+| Knob | `--color-selected-foreground` | white |
+| Focus ring | `--color-ring` | — |
+
+Two notes on the mapping:
+
+1. **The knob is drawn pure white and the token layer has no semantic white.** `--color-selected-foreground` is the role that means "what sits on a selected surface", and in the light theme it resolves to gray-050 rather than `#ffffff`. The role is used instead of the exact value, because it is the one that flips correctly in the dark theme; a token holding pure white unconditionally would leave a white knob on a dark track.
+2. **The design records no colour for the off track.** `--color-input` is used, the role that already means "the neutral of an unfilled form control". Reusing the recorded gray-200 there would have made the off state and the disabled state identical.
+
+Because the design gives the disabled track a colour of its own, the disabled switch is repainted rather than dimmed with `opacity`, which is how `FuroCheckbox` and `FuroRadio` draw their disabled state.
+
+## Slots
+
+None. The switch renders a track and a knob and no text.
+
+## Styling
+
+| Part | Class | Notes |
+|---|---|---|
+| Root | `.unit-form-control.switch` | Also carries `size-*` and `disabled`; the primitive adds `data-state="checked"` or `"unchecked"` |
+| The knob | `.knob` | Slides by the travel distance for the size |
+
+The geometry is held in component-level custom properties on the root: `--furo-switch-track-width`, `--furo-switch-track-height`, `--furo-switch-track-inset`, `--furo-switch-knob-size` and `--furo-switch-knob-travel`. Override them to draw a step the two sizes do not cover.
+
+## Accessibility
+
+- The root carries the switch role and its checked state, so a screen reader announces on and off rather than pressed.
+- The switch renders no text of its own. Give it an accessible name through `aria-label`, `aria-labelledby`, or by wrapping it in `FuroControlBlock`.
+- `Space` and `Enter` flip it; `Tab` moves focus onto and off it.
+- Focus draws a ring on the track, and the knob's position carries the state, so colour is never the only signal.