@openreachtech/furo-vue 1.5.0 → 1.7.0

package/docs/furo-avatar-group.md

@@ -0,0 +1,87 @@
+# `<FuroAvatarGroup>` Interface Specification
+
+## Overview
+
+`<FuroAvatarGroup>` is a **shipped** avatar-group molecule in the Furo-Vue component system. It shows a set of people as overlapping avatars and collapses past a configurable count, so a row of assignees stays a fixed width instead of overflowing.
+
+It is purely presentational: it carries no value and emits nothing.
+
+**Public SFC prop:** `parcel` only. HTML attributes pass through to the root.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroAvatarGroup/` |
+| **Base primitive** | None; a row of `FuroAvatar` |
+| **Value** | None |
+| **Emits** | None |
+| **Composes** | `FuroAvatar` |
+
+## `parcel` keys
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `avatars` | `Array<FuroAvatarGroupEntry>` | `[]` | The people, in the order they render. |
+| `maxVisibleAvatars` | `number` | `5` | How many render before the rest become a count. Values below one are raised to one. |
+| `spacing` | `'wide' \| 'narrow'` | `'wide'` | How far the avatars overlap. |
+| `size` | `string` | `'1.5rem'` | Diameter of one avatar. |
+
+### `FuroAvatarGroupEntry`
+
+The subset of `FuroAvatar`'s parcel that identifies a person:
+
+| Key | Type | Meaning |
+|---|---|---|
+| `imageSource` | `string` | Photograph. |
+| `imageAlternativeText` | `string` | Alternative text for it. |
+| `fallbackText` | `string` | Shown while the image is absent or loading, for example initials. |
+
+The group pins every avatar to a circle, because a row of overlapping squares reads as a stack of cards rather than as a set of people.
+
+## Collapsing
+
+A group longer than `maxVisibleAvatars` renders that many avatars and then one count standing for the rest:
+
+| People | Renders |
+|---|---|
+| 5 or fewer | one avatar each |
+| 8, showing 5 | five avatars and `+3` |
+
+Values below one are raised to one: a group showing no avatar and only a count is a number, not a group.
+
+The overflow slot receives both the hidden entries and their count, so a consumer can name the hidden people in a tooltip without recomputing which ones they are.
+
+## Slots
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| `overflow` | `{ avatars, count }` | Replaces the count, receiving the hidden entries and how many there are. Default: `+N`. |
+
+## Styling
+
+| Part | Class | Notes |
+|---|---|---|
+| Root | `.unit-avatar-group` | Also carries `spacing-wide` or `spacing-narrow` |
+| One person | `.member` | A `FuroAvatar` |
+| The count | `.overflow` | Only rendered by the default slot content |
+
+Each avatar and the count carry a ring in `--color-border`, so an overlap still reads as two people rather than one clipped shape. `--furo-avatar-group-size` sets the diameter and is fed from `parcel.size`.
+
+## Read from the design
+
+The design draws the group at one avatar step, its smallest, and gives two spacings. The overlap was derived from the widths it draws rather than read from a variable, because the design carries no spacing token for it:
+
+| Spacing | Widths drawn for 2, 3, 4, 5 and 5+ people | Step per person | Overlap |
+|---|---|---|---|
+| `wide` | 40, 56, 72, 88, 104 | 16px | 8px |
+| `narrow` | 36, 48, 60, 72, 84 | 12px | 12px |
+
+Each row is `24 + (slots - 1) × step` wide, and the collapsed form adds one slot for the count rather than replacing an avatar with it, which is where the default fold at five comes from.
+
+The design's own names for the two spacings are `stack_wide` and `stack_narrow`. They are shortened here because the component is already a stack.
+
+### One gap in the existing avatar, recorded rather than fixed
+
+The design's avatar has three size steps, 40px, 32px and 24px, and it renders an icon, text or an image. `FuroAvatar` has no size channel: it declares `--furo-avatar-size` at 2.5rem, which is the design's largest step, and a consumer overrides the custom property. That is why this group sets the property rather than passing a size down. Giving `FuroAvatar` a size channel belongs to the fidelity pass on the existing components, not here.

package/docs/furo-avatar.md

@@ -0,0 +1,101 @@
+# FuroAvatar
+
+Image avatar atom with a graceful text fallback. Built on a headless avatar primitive that swaps to the fallback when the image is absent, loading, or fails to load. It carries no value and emits nothing.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Atom |
+| **Path** | `lib/components/atoms/FuroAvatar/` |
+| **Base primitive** | Headless avatar (`Root` + `Image` + `Fallback`) |
+| **Composes** | Nothing — a single styled avatar |
+| **Emits** | None |
+| **Shape** | `circle` (default) or `square` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `FuroAvatarParcel \| null` | `null` | Reactive data object holding the image source, fallback, and shape. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `imageSource` | `string` | unset | Image URL. When unset, only the fallback renders. |
+| `imageAlternativeText` | `string` | `''` | Alternative text applied to the image. |
+| `fallbackText` | `string` | `''` | Text shown while the image is absent or loading (e.g. initials). |
+| `fallbackDelay` | `number` | unset | Milliseconds to wait before showing the fallback, avoiding a flash on fast loads. |
+| `shape` | `'circle' \| 'square'` | `'circle'` | Avatar shape; circle is fully rounded, square uses the medium radius. |
+
+### Slots
+
+| Slot | Scoped props | Description |
+|---|---|---|
+| `fallback` | — | Custom fallback content; overrides `fallbackText` (e.g. an icon). |
+
+---
+
+## Usage
+
+```vue
+<FuroAvatar
+  :parcel="{
+    imageSource: '/jane.png',
+    imageAlternativeText: 'Jane Doe',
+    fallbackText: 'JD',
+  }"
+/>
+```
+
+Fallback only (no image source):
+
+```vue
+<FuroAvatar :parcel="{ fallbackText: 'AB' }" />
+```
+
+Square shape and a custom size:
+
+```vue
+<FuroAvatar
+  :parcel="{ imageSource: '/team.png', shape: 'square' }"
+  style="--furo-avatar-size: 4rem"
+/>
+```
+
+---
+
+## Sizing
+
+The avatar fills a box driven by the `--furo-avatar-size` custom property (default `2.5rem`). Override it on the element (or an ancestor) to scale the avatar; no size prop is needed.
+
+```vue
+<FuroAvatar :parcel="{ fallbackText: 'XL' }" style="--furo-avatar-size: 5rem" />
+```
+
+---
+
+## Accessibility
+
+- Provide `imageAlternativeText` so the image has an accessible name.
+- The fallback text is uppercased visually; pass readable initials.
+- Colors reference semantic tokens only (`--color-muted` background, `--color-muted-foreground` text); dimensions use `rem`.
+
+---
+
+## Types
+
+```ts
+type FuroAvatarParcel = {
+  imageSource?: string
+  imageAlternativeText?: string
+  fallbackText?: string
+  fallbackDelay?: number
+  shape?: 'circle' | 'square'
+}
+```

package/docs/furo-badge.md

@@ -0,0 +1,126 @@
+# `<FuroBadge>` Interface Specification
+
+## Overview
+
+`<FuroBadge>` is a **shipped** badge atom in the Furo-Vue component system. It labels a record's state so that the same state reads the same way on every screen.
+
+It is purely presentational: it carries no value, emits nothing, and takes no primitive from a headless library. Everything it renders comes from `parcel`.
+
+**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 chip. That word is already claimed in this project's glossary for the token rendered inside a multi-select, and one word carrying two meanings inside the document that defines the shared language is worse than a translation step. So the component is named for what it is.
+
+## Why one component and not five
+
+The design draws four separate components, one per shape, and treats its status component as a fifth. All five are the same object seen from different sides: a small label whose colour carries meaning. They are one component here, with a `shape` channel and a `tone` channel, rather than five components with overlapping surfaces.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Atom |
+| **Path** | `lib/components/atoms/FuroBadge/` |
+| **Base primitive** | None; a plain root element |
+| **Value** | None |
+| **Emits** | None |
+
+## `parcel` keys
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `label` | `string` | `''` | Text shown inside the badge. Ignored by the `dot` shape. |
+| `count` | `number` | `null` | Number shown by the `count` shape. Read instead of `label` there, so a consumer passing a number does not stringify it first. A `count` shape with no count renders `0`. |
+| `shape` | `FuroBadgeShape` | `'text'` | `text`, `count`, `state` or `dot`. |
+| `tone` | `FuroBadgeTone` | `'accent'` | `accent`, `neutral`, `success`, `warning` or `error`. |
+| `emphasis` | `FuroBadgeEmphasis` | `'solid'` | `solid`, `subtle` or `outline`. Meaningful for the `text` and `count` shapes only. |
+| `size` | `FuroBadgeSize` | `'medium'` | `large`, `medium` or `small`. |
+
+### Shapes
+
+| Shape | Renders | Geometry |
+|---|---|---|
+| `text` | A label on a surface | 28px, 24px or 20px tall; 6px corner, 4px at the small step |
+| `count` | A number on a surface | Fully rounded. A single digit is a circle; two or more digits widen into a pill |
+| `state` | A dot beside a coloured label | No surface, no border |
+| `dot` | A 6px dot | No surface, no border, no text |
+
+### Tones
+
+`accent` is the design's own default and reads the `--color-info` family. The other four are the status roles the token layer already declares, which is what the design's state component draws under its own colour names:
+
+| Tone | Reads | The design calls it |
+|---|---|---|
+| `accent` | `--color-info` | default |
+| `neutral` | `--color-foreground-secondary` | neutral |
+| `success` | `--color-success` | green |
+| `warning` | `--color-warning` | orange |
+| `error` | `--color-error` | red |
+
+The design's own state labels are `due soon`, `dued` and `completed`. Those are domain vocabulary, so they stay in the consumer application; this component exposes the roles, not the workflow.
+
+### Emphasis
+
+`emphasis` selects which of the tone's three values the surface, the border and the text read:
+
+| Emphasis | Surface | Border | Text |
+|---|---|---|---|
+| `solid` | the tone's solid surface | none | that surface's `-foreground` |
+| `subtle` | the tone's subtle surface | none | that surface's `-foreground` |
+| `outline` | the tone's subtle surface | the tone's border | that surface's `-foreground` |
+
+Only `--color-info` carries a distinct `-lighter` border step, because the design draws an outlined badge in the accent family and the neutral family and in no other. The three status families use their base colour for the border.
+
+The `solid` emphasis reads a pair of its own rather than the tone's accent colour, so a fill always carries a label chosen against it:
+
+| Tone | Solid surface | Solid text | Light | Dark |
+|---|---|---|---|---|
+| `accent` | `--color-info` | `--color-info-foreground` | 5.13:1 | 7.43:1 |
+| `neutral` | `--color-primary` | `--color-primary-foreground` | 9.31:1 | 14.69:1 |
+| `success` | `--color-success` | `--color-success-foreground` | 7.44:1 | 9.82:1 |
+| `warning` | `--color-warning` | `--color-warning-foreground` | 6.74:1 | 8.34:1 |
+| `error` | `--color-error` | `--color-error-foreground` | 5.14:1 | 7.01:1 |
+
+Two things follow. The status label is near-black in both themes, because a status fill stays mid-tone in both and the near-white it used to read landed at 2.42:1 in light. And the `neutral` tone fills from `--color-primary` rather than from `--color-foreground-secondary`, which is the colour it still reads as text under `subtle` and `outline`: a text role is never a fill, so the solid cell needed a surface. See [ADR 0039](./adr/0039-an-intent-surface-ships-the-label-it-can-carry.md).
+
+The `subtle` and `outline` emphases read a pair of their own on the same terms, because a tint cannot carry the family's mid-tone accent as text:
+
+| Tone | Tinted surface | Tinted text | Light | Dark |
+|---|---|---|---|---|
+| `accent` | `--color-info-subtle` | `--color-info-subtle-foreground` | 6.16:1 | 8.15:1 |
+| `neutral` | `--color-muted-subtle` | `--color-foreground-secondary` | 5.04:1 | 11.85:1 |
+| `success` | `--color-success-subtle` | `--color-success-subtle-foreground` | 5.21:1 | 9.94:1 |
+| `warning` | `--color-warning-subtle` | `--color-warning-subtle-foreground` | 6.38:1 | 6.92:1 |
+| `error` | `--color-error-subtle` | `--color-error-subtle-foreground` | 5.72:1 | 8.27:1 |
+
+Here the label does flip between the themes, where the solid label above does not: a tint travels from `emerald-050` to `emerald-950`, so its label travels with it. The `neutral` tone reads a foreground role instead, because a neutral family owns no accent step to darken. Painting the accent on its own tint is what put a `subtle` success badge at 2.41:1 in light, which left the two quiet emphases with no legible tone but the neutral one. See [ADR 0040](./adr/0040-a-tinted-surface-ships-its-own-label.md).
+
+## Slots
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| default | `{ text }` | Replaces the rendered text, so an application can put an icon, a truncation or tabular figures beside the state. Not rendered for the `dot` shape. |
+
+## Styling
+
+| Part | Class | Notes |
+|---|---|---|
+| Root | `.unit-badge` | Also carries `shape-*`, `tone-*`, `emphasis-*`, `size-*`, and `single-digit` for a one-digit count |
+| The mark | `.dot` | Rendered for the `state` and `dot` shapes |
+| The text | `.label` | Only rendered by the default slot content |
+
+Override `--color-info`, `--color-success`, `--color-warning` or `--color-error` to re-theme a tone; the badge reads them rather than holding its own colours. Each family's `-foreground`, `-subtle` and `-subtle-foreground` sit beside it in `0030`, so re-point those too when a fill or a tint needs a different label.
+
+## Read from the design, and the contradictions found
+
+Every value here was read from the CRM Kit design system rather than inferred. Three things in it disagree with themselves. Each is followed exactly rather than normalised, matching how this project handled the warning family's subtle step, and each is recorded here so the designer can correct the source.
+
+1. **The neutral family's subtle badge carries regular weight** while every other combination carries medium. A badge whose weight changes with its colour reads as a mistake, but it is what the design draws.
+2. **The count shape's small step declares a 20px line height inside a 16px box**, which cannot fit. The box height wins here, so the badge renders at the size drawn.
+3. **The count shape's two steps disagree on weight**: its medium step is regular and its small step is medium.
+
+Two further notes, not contradictions:
+
+- **The count shape has two size steps, not three.** A badge asked for the `large` step renders the medium geometry.
+- **The design draws no solid neutral badge.** The combination is implemented for a complete matrix rather than left to fall back silently, because a `tone` × `emphasis` surface where one cell behaves differently is a trap.

package/docs/furo-breadcrumb.md

@@ -0,0 +1,89 @@
+# `<FuroBreadcrumb>` Interface Specification
+
+## Overview
+
+`<FuroBreadcrumb>` is a **shipped** breadcrumb molecule in the Furo-Vue component system. It shows where a record sits in a hierarchy, so a user deep in a tree can see the path and retrace it.
+
+It is purely presentational: it carries no value, emits nothing, and takes no primitive from a headless library. The trail comes from `parcel.items`, and navigation is whatever the consumer puts on each entry.
+
+**Public SFC prop:** `parcel` only. HTML attributes pass through to the `nav` root.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroBreadcrumb/` |
+| **Base primitive** | None; a `nav` wrapping an ordered list |
+| **Value** | None |
+| **Emits** | None |
+| **Composes** | `FuroIcon` for the separator and the overflow marker |
+
+## The last entry is the current one
+
+Position decides which entry is current, not a flag. A flag would let a caller mark two entries current, or none, and neither is a trail. So the rule is positional and there is nothing to keep in sync.
+
+The current entry renders as text even when it carries a destination, because it is where the user already is. It is announced with `aria-current="page"`, which is what a screen reader reports instead of the visual weight change.
+
+## `parcel` keys
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `items` | `Array<FuroBreadcrumbItem>` | `[]` | The trail, root first. The last entry is the current one. |
+| `maxVisibleItems` | `number` | `4` | How many entries show before the trail collapses. Values below two are raised to two. |
+
+### `FuroBreadcrumbItem`
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `label` | `string` | — | Text shown for the entry. |
+| `href` | `string` | — | Destination. An entry with no destination renders as text. |
+| `disabled` | `boolean` | `false` | Renders as text and is announced with `aria-disabled`. |
+
+## Collapsing a deep trail
+
+A trail longer than `maxVisibleItems` keeps the **root** and the **tail**, and folds everything between into one overflow marker:
+
+| Depth | Renders |
+|---|---|
+| 4 or fewer | every entry |
+| 6, folding at 4 | `Level 1` · marker · `Level 4` `Level 5` `Level 6` |
+| 5, folding at 4 | `Level 1` · marker · `Level 3` `Level 4` `Level 5` |
+
+The root is kept because it is the one entry that says where the tree begins. The tail is kept because it says where the user is and how they got to the last turn.
+
+`maxVisibleItems` counts the entries shown, not counting the marker. Values below two are raised to two: a fold that shows neither the root nor the current entry has nothing left to say.
+
+The overflow slot receives the entries the marker stands for, so a consumer can hang a menu off the marker without recomputing which entries went missing. The component does not open a menu itself: that would mean a molecule reaching for an organism, and the layer order forbids it.
+
+## Slots
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| `crumb` | `{ crumb }` | Replaces one entry, for a router link or an icon. Default: the entry label. |
+| `overflow` | `{ items }` | Replaces the overflow marker, receiving the entries it stands for. Default: an ellipsis icon. |
+| `separator` | — | Replaces the mark between entries. Default: a right caret icon. |
+
+## Styling
+
+| Part | Class | Notes |
+|---|---|---|
+| Root | `.unit-breadcrumb` | A `nav` |
+| The list | `.trail` | An `ol` with its list styling removed |
+| One position | `.entry` | An `li` holding the entry and its separator |
+| One entry | `.crumb` | Gains `.current` and `.disabled`. Renders as `a` or `span` |
+| The separator | `.separator` | `aria-hidden`, so it is not read out between entries |
+| The marker | `.overflow` | Only rendered by the default slot content |
+
+## Read from the design
+
+| Part | Design value | Token |
+|---|---|---|
+| An entry | `#646c7d`, regular 13.5px/20 | `--color-foreground-secondary`, `--font-body-medium` |
+| An entry, hovered | `#424752` | `--color-foreground` |
+| The current entry | `#424752`, medium 13.5px/20 | `--color-foreground`, `--font-label-small` |
+| The separator and the marker | `#8b93a2` | `--color-foreground-glyph` |
+
+The current entry is the only place the trail changes weight. The design draws trails at two, three and four levels plus one collapsed form beyond that, which is where the default fold at four comes from.
+
+The design also draws entries carrying an icon, a dropdown, or both. Those are reachable through the `crumb` slot rather than as parcel keys, so the component does not grow a key per decoration.

package/docs/furo-button.md

@@ -0,0 +1,263 @@
+# `<FuroButton>` Interface Specification
+
+## Overview
+
+`<FuroButton>` is a **shipped** action primitive atom in the Furo-Vue component system. Its **public contract is Furo-defined**: application developers pass `parcel`, listen to Furo emits, and use documented slots — without importing the underlying primitive library.
+
+Implementation uses a headless action/polymorphic primitive inside `lib/components/atoms/FuroButton/*` only. That dependency is **not** part of the application API.
+
+Contract style aligns with other atoms:
+
+- behavior via `:parcel` (`FuroButtonParcel`)
+- HTML attributes via fallthrough (`id`, `aria-*`, `type` override via parcel, …)
+- Furo emit `click` with `ButtonEmitPayload`
+
+**Public SFC prop:** `parcel` only.
+
+**No `v-model`:** `FuroButton` is an action trigger, not a form value control.
+
+**Source files:**
+
+- `lib/components/atoms/FuroButton/FuroButton.vue`
+- `lib/components/atoms/FuroButton/FuroButtonContext.js`
+- `lib/components/atoms/FuroButton/ButtonEmitPayload.js`
+
+**Live samples:** `pages/samples/components/playground/FuroButtonPlayground/index.vue`
+
+---
+
+## Public API at a glance
+
+| Area | Status | Notes |
+| ---- | ------ | ----- |
+| **SFC surface** | | |
+| Public prop `parcel` only (+ attribute fallthrough) | **Implemented** | See [`FuroButtonParcel`](#furobuttonparcel) |
+| **Visual** | | |
+| Variants `default`, `secondary`, `destructive`, `outline`, `ghost`, `link` | **Implemented** | Via `parcel.variant` |
+| Sizes `default`, `sm`, `lg`, `icon` | **Implemented** | Via `parcel.size` |
+| `disabled`, `loading` | **Implemented** | Blocks click emit; `aria-disabled` / `aria-busy` |
+| `asChild` | **Implemented** | Headless composition for menu/dialog triggers |
+| **Emits** | | |
+| `click` | **Implemented** | `ButtonEmitPayload`; suppressed when disabled/loading |
+| **Slots** | | |
+| `default` | **Implemented** | Button label / content |
+| `loading` | **Implemented** | Custom spinner (default: `ph:circle-notch` icon) |
+
+---
+
+## Abstraction boundary
+
+| Layer | Responsibility |
+| ----- | -------------- |
+| Application | `parcel`, listeners, slots |
+| Atom (`FuroButton`) | Maps parcel → the underlying primitive; DOM, emits, default loading indicator |
+| Underlying primitive (maintainers) | Internal only; not part of the application API |
+
+**Rules:**
+
+1. Documented `parcel` keys are the **Furo contract**. Furo-owned keys are stripped in `extractRootAttributes()` before optional passthrough to the underlying primitive.
+2. Do **not** import the underlying primitive in application code.
+3. Use `parcel.asChild` when composing with `FuroDropdownMenu` or other underlying-primitive triggers — not ad-hoc wrapper divs.
+
+---
+
+## Props
+
+### Rule: `parcel` vs attributes
+
+| Mechanism | When to use | Application sees |
+| --------- | ----------- | ---------------- |
+| `:parcel` | Furo button behavior | `FuroButtonParcel` (+ merged defaults) |
+| Attributes on `<FuroButton>` | e.g. `id`, `aria-label` | Vue fallthrough to the underlying primitive (merged with `extractRootAttributes()`) |
+
+> **`parcel` must be JSON-serializable** — no functions inside `parcel`.
+
+```html
+<FuroButton
+  id="create-record"
+  :parcel="{
+    variant: 'default',
+    size: 'default',
+  }"
+  @click="context.onCreateRecord({ payload: $event })"
+>
+  Create record
+</FuroButton>
+```
+
+### Component props (public)
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `parcel` | `FuroButtonParcel` or `null` | `null` | Furo behavior (see table below) |
+
+### `FuroButtonParcel`
+
+Keys read in `FuroButtonContext` (defaults from `parcel` getter):
+
+| Key | Type | Default (getter) | Description |
+| --- | ---- | ---------------- | ----------- |
+| `variant` | `FuroButtonVariant` | `'default'` | Visual style preset |
+| `size` | `FuroButtonSize` | `'default'` | Size preset |
+| `disabled` | `boolean` | `false` | Disables interaction (also respects fallthrough `disabled`) |
+| `loading` | `boolean` | `false` | Shows loading slot; blocks click emit |
+| `asChild` | `boolean` | `false` | Merge props/behavior onto single child (headless composition) |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Native button `type` when not `asChild` |
+
+### `FuroButtonVariant`
+
+`'default' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link'`
+
+### `FuroButtonSize`
+
+`'default' | 'sm' | 'lg' | 'icon'`
+
+Furo-owned keys above are **not** forwarded via `extractRootAttributes()`.
+
+---
+
+## Emits
+
+| Event | Payload | When | Implemented |
+| ----- | ------- | ---- | ----------- |
+| `click` | `ButtonEmitPayload` | User activates button | Yes — not fired when `disabled` or `loading` |
+
+### Parent handler style
+
+```js
+onCreateRecord ({
+  payload,
+}) {
+  if (payload.isDefaultPrevented()) {
+    return
+  }
+
+  this.createRecord()
+}
+```
+
+```html
+@click="context.onCreateRecord({ payload: $event })"
+```
+
+---
+
+## `ButtonEmitPayload` API
+
+`ButtonEmitPayload` extends [`BaseEmitPayload`](../lib/emit-payload/BaseEmitPayload.js). Built from native `MouseEvent` / `PointerEvent` on click.
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `controlElement` | `HTMLElement \| null` | Button root (`currentTarget` preferred over `target`) |
+| `isDefaultPrevented()` | `boolean` | Whether the native event called `preventDefault()` |
+
+---
+
+## Slots
+
+| Slot | Scoped props | Default |
+| ---- | ------------ | ------- |
+| `default` | — | Button label / icon content |
+| `loading` | — | `ph:circle-notch` spinner in loading overlay |
+
+TypeScript / JSDoc: `FuroButtonSlots` in `FuroButtonContext.js` (`default`, `loading` — no scoped props).
+
+When `loading` is `true`, the `default` slot content stays in the layout (`visibility: hidden`) so the button keeps its size. The `loading` slot renders in an absolutely positioned overlay on top of the label — no layout shift for the button or adjacent UI.
+
+The default `ph:circle-notch` spinner turns once every `--transition-timer-spin` (`0.75s`), a duration of its own so retuning `--transition-timer` for hover and focus transitions never changes the spin. Under `prefers-reduced-motion: reduce` the spinner stays still. Set `--transition-timer-spin` on `:root` to change the pace.
+
+When `parcel.asChild` is `true`, composition forwards to a single child element; the overlay pattern is not applied (use `asChild: false` when you need loading overlay).
+
+---
+
+## `asChild` composition
+
+Use when another headless primitive or custom element must receive button styling and behavior:
+
+```html
+<FuroButton :parcel="{ asChild: true, variant: 'outline' }">
+  <a href="/docs">
+    Documentation
+  </a>
+</FuroButton>
+```
+
+`FuroDropdownMenu` (build #2) will use `FuroButton` as the default trigger with `parcel.asChild: true`.
+
+---
+
+## Accessibility requirements
+
+- Provide visible label text or `aria-label` on the button.
+- Keyboard: Enter and Space activate (native button / the underlying primitive with `as="button"`).
+- `aria-disabled="true"` when `parcel.disabled` or fallthrough `disabled`.
+- `aria-busy="true"` when `parcel.loading`.
+- Focus ring via `:focus-visible` using `var(--color-ring)`.
+- Icon-only buttons: use `parcel.size: 'icon'` and `aria-label`.
+
+---
+
+## Styling convention
+
+Styles in SFC `@layer furo`:
+
+- Root: `.unit-button.{variant}` + optional `.size-sm`, `.size-lg`, `.size-icon`
+- States: `.disabled`, `.loading`, `:hover`, `:focus-visible`, `:active`
+- Tokens: `--color-primary`, `--color-secondary`, `--color-destructive`, `--color-border`, `--color-accent`, `--color-ring`, `--size-input-height`, `--size-border-radius-medium`
+
+**Note:** `FuroButton` uses `unit-button`, not `unit-form-control` (form atoms only).
+
+---
+
+## Examples
+
+### Variants
+
+```html
+<FuroButton :parcel="{ variant: 'default' }">
+  Primary
+</FuroButton>
+
+<FuroButton :parcel="{ variant: 'destructive' }">
+  Delete
+</FuroButton>
+```
+
+### Loading
+
+```html
+<FuroButton
+  :parcel="{
+    loading: context.statusReactive.isSubmitting,
+    disabled: context.statusReactive.isSubmitting,
+  }"
+  @click="context.submitForm({ payload: $event })"
+>
+  Save
+</FuroButton>
+```
+
+### Icon button
+
+```html
+<FuroButton
+  :parcel="{
+    variant: 'outline',
+    size: 'icon',
+  }"
+  aria-label="Add record"
+>
+  <Icon name="ph:plus" />
+</FuroButton>
+```
+
+---
+
+## Implementation status
+
+| Deliverable | Status |
+| ----------- | ------ |
+| `FuroButton.vue` + context + payload | Shipped |
+| Public prop: `parcel` only | Shipped |
+| Playground `FuroButtonPlayground` | Shipped |
+| Unit tests `FuroButtonContext.js`, `ButtonEmitPayload.js` (jsdom) | Shipped |