@teamblind-chorus/ui 1.0.0

package/agents/components/button/text.spec.json

@@ -0,0 +1,215 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Button",
+  "family": "button",
+  "subcomponent": "text",
+  "description": "Link-shaped commit surface — looks like a text link at rest (no fill, no border, label-coloured text) but paints a button-like hover overlay and a standard focus ring when interacted with. Reach for this whenever an inline affordance lives next to typographic content and should read as part of the text rhythm rather than as a separate filled control. Three sizes (medium / small / xsmall) for the row's density, four appearances (default / accent / onPrimary / inverse) for emphasis and host surface.",
+  "element": "button",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "text"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "medium",
+        "small",
+        "xsmall"
+      ],
+      "default": "medium"
+    },
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "default",
+        "accent",
+        "onPrimary",
+        "inverse"
+      ],
+      "default": "default"
+    },
+    "leadingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional context glyph rendered before the label (e.g. a back chevron next to a 'Back' label, an external-link glyph next to 'Open'). Sized 16px on every rung — the glyph stays legible on the dense `xsmall` rung where the label drops to 12-rank type."
+    },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional directional / destination glyph rendered after the label (e.g. a chevron-right next to 'Continue', an external-link glyph next to 'Open in new tab'). Same per-size footprint as the leading slot. For the **dropdown** pattern (see `useCases.dropdown`), pass `<ChevronDownIcon />` at rest and flip to `<ChevronUpIcon />` while the menu is expanded — the chevron is a state signal tied to `aria-expanded`, never decorative."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "label": {
+      "required": true,
+      "description": "Button's accessible name. Required, single line.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "leadingIcon": {
+      "required": false,
+      "description": "Context glyph before the label. 16px (`sys.icon.md`) on every rung — the glyph stays legible on the dense `xsmall` rung where the label drops to 12-rank type. Inherits the label color via `currentColor`. `aria-hidden`.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "trailingIcon": {
+      "required": false,
+      "description": "Directional / destination glyph after the label. Same per-size footprint as the leading slot, inherits the label's color. `aria-hidden`.",
+      "accepts": [
+        "icon"
+      ]
+    }
+  },
+  "sizes": {
+    "medium": {
+      "minHeight": "ref.space.500",
+      "paddingBlock": "sys.layout.container.xs",
+      "paddingInline": "sys.layout.container.xs",
+      "radius": "sys.radius.full",
+      "labelTypo": "sys.typo.heading.sm",
+      "iconSize": "sys.icon.md",
+      "slotGap": "sys.layout.inline.sm"
+    },
+    "small": {
+      "minHeight": "ref.space.400",
+      "paddingBlock": "sys.layout.container.2xs",
+      "paddingInline": "sys.layout.container.xs",
+      "radius": "sys.radius.full",
+      "labelTypo": "sys.typo.label.md",
+      "iconSize": "sys.icon.md",
+      "slotGap": "sys.layout.inline.sm"
+    },
+    "xsmall": {
+      "minHeight": "ref.space.300",
+      "paddingBlock": "sys.layout.container.2xs",
+      "paddingInline": "sys.layout.container.xs",
+      "radius": "sys.radius.full",
+      "labelTypo": "sys.typo.label.sm",
+      "iconSize": "sys.icon.md",
+      "slotGap": "sys.layout.inline.sm"
+    }
+  },
+  "appearances": {
+    "default": {
+      "background": "transparent",
+      "border": null,
+      "label": "sys.color.onSurfaceVariant",
+      "note": "The base neutral inline action — the canonical Text Button. Quiet enough to live next to typographic content without claiming commit-rank attention."
+    },
+    "accent": {
+      "background": "transparent",
+      "border": null,
+      "label": "sys.color.primary",
+      "note": "Brand-blue label for the inline commit affordance. Use sparingly — never two `accent` Text Buttons in the same row.",
+      "linkAffordanceRecommendation": "Prefer `accent` whenever the Text Button reads as a **link affordance** — a section header's trailing 'See all' / 'See more', a card-header 'Follow', an inline 'View details' next to a body paragraph. Link-like affordances should carry chromatic emphasis so the navigational intent is unambiguous; `default` (onSurfaceVariant) is for quieter inline commits that should recede into the body copy. Override to `default` only when a parent surface (e.g. a busy chrome bar) already carries enough chromatic weight that an `accent` label would compete."
+    },
+    "onPrimary": {
+      "background": "transparent",
+      "border": null,
+      "label": "sys.color.onPrimary",
+      "note": "Always-white label for use on top of a `primary`-filled host (e.g. the Tooltip `default` appearance). Both `primary` and `onPrimary` are theme-stable (blue / white in light and dark mode), so the label reads as white against the brand-blue fill in either theme — unlike `inverse`, which flips with the theme."
+    },
+    "inverse": {
+      "background": "transparent",
+      "border": null,
+      "label": "sys.color.inverseOnSurface",
+      "note": "Mirror for use inside an inverse host (Toast, coach-mark, snackbar). Label paints in `inverseOnSurface` so it reads against the host's `inverseSurface` fill; state overlays mix from the same token so the recipe carries over without per-host tuning. The `inverseOnSurface` token FLIPS with the theme (white in light mode, dark in dark mode) — that's correct against the also-flipping `inverseSurface` host. When the host fill does NOT flip (e.g. a `primary`-filled Tooltip in `default` appearance), reach for `onPrimary` instead so the label stays white in both themes."
+    }
+  },
+  "flavors": {
+    "destructive": {
+      "description": "Swaps the label color to the error family across every appearance. Reserved for inline destructive commits next to typographic content (a 'Delete account' trail in a settings row, a 'Discard' inline next to a draft).",
+      "appearances": {
+        "default": {
+          "background": "transparent",
+          "border": null,
+          "label": "sys.color.error"
+        },
+        "accent": {
+          "background": "transparent",
+          "border": null,
+          "label": "sys.color.error"
+        },
+        "onPrimary": {
+          "background": "transparent",
+          "border": null,
+          "label": "sys.color.error"
+        },
+        "inverse": {
+          "background": "transparent",
+          "border": null,
+          "label": "sys.color.error"
+        }
+      }
+    }
+  },
+  "states": {
+    "default": {
+      "overlay": null
+    },
+    "hovered": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.hover"
+      }
+    },
+    "pressed": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "disabled": {
+      "overlay": null,
+      "containerOpacity": "sys.state.disabled",
+      "suppressFocusRing": true,
+      "cursor": "not-allowed"
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the button is in. The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
+    "composition": "outward",
+    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding layout.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset"
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "note": "min-height binds to raw reference-tier space steps (the system tier does not currently expose 24 / 32 / 40 px control-height steps). medium's 40 floor aligns with Icon Button next to it; small's 32 sits one density lower (14-rank label, same 16-glyph), and xsmall's 24 is the densest variant for inline call-sites where even small over-claims (preview-stage toolbars, feed engagement counters).",
+    "group": "Horizontally-grouped Text Buttons share a row gap that pairs with the size rung. Because Text Button applies optical alignment by default (each button's chrome bleeds outward by its own padding so the visible label box is the layout box), the chrome-to-chrome gap IS the visible label-to-label distance — there is no per-button padding to add on top: medium and small groups use `sys.layout.inline.xl` (16); xsmall groups tighten to `sys.layout.inline.lg` (12). Wider chrome gaps push the visible labels apart and break the row's grouping; tighter gaps collapse adjacent commits into one visual block.",
+    "opticalAlignmentDefault": "Text Button applies optical alignment as the **default** rendering rule, on all four sides: the chrome is transparent at rest, so the visible label box (not the padded chrome) defines the button's layout edges. Implemented as a base `margin: calc(-1 × padding-block) calc(-1 × padding-inline)` on `.chorus-button--text`, which cancels the chrome's contribution to the layout box per-rung. Hover capsule still paints on every side — the chrome becomes a hover-only affordance. Consumers do not opt in; alignment with the surrounding content rail just works."
+  },
+  "useCases": {
+    "dropdown": {
+      "description": "Disclosure-trigger pattern: the Text Button reads as the **current value** of a single-select, the trailing chevron flips between `ChevronDownIcon` (closed) and `ChevronUpIcon` (open) as a state signal. Consumer-owned menu surface rendered in a portal — Button only owns the trigger. Default rung is `xsmall` for inline / toolbar dropdowns (preview-stage Size selector, filter chrome, Header trailing); step up to `small` or `medium` when the dropdown is the row's primary commit. Adopted by the docs `ComponentPreview` size selector and by the Header `headerDropdown` mode.",
+      "ariaContract": [
+        "`aria-haspopup` — `\"listbox\"` for a value-selector pattern; `\"menu\"` for a command palette pattern.",
+        "`aria-expanded` — required; mirror the menu's open state so the chevron + AT stay in lockstep.",
+        "`aria-controls` (when open) — points to the menu's id so AT can move focus into the listed options."
+      ],
+      "chevronContract": "ChevronDownIcon at rest → ChevronUpIcon while expanded. Never freeze on Down when open — the chevron is a state signal, not decoration. Sized at 16 (`sys.icon.md`) on every rung, same as any other trailing icon.",
+      "labelContract": "Label IS the current value (e.g. 'Medium' for a size selector, 'Last 7 days' for a date range). When no value is selected yet, fall back to the field name ('Size', 'Range'). Never use a static verb like 'Choose…' when a value is selected — the label is the value."
+    }
+  },
+  "forbidden": [
+    "raw <a> or <span> with Tailwind text-color overrides — link-affordance text is button/text with appearance=accent",
+    "appearance=default for navigational copy — link affordance carries appearance=accent so chrome reads as commit",
+    "padding override that breaks the optical-alignment leading nudge (the chrome bleeds out by its own padding — re-padding on the consumer side mis-aligns the label rail)",
+    "manual color override on the label — re-tone via the `--button-text-label` plumbing var, never via inline color"
+  ]
+}

package/agents/components/button/toggle.md

@@ -0,0 +1,108 @@
+# Toggle
+
+Commit-and-record action — a Toolbar-footprint button with two states. **Inactive** invites the commit (`primary` fill); **active** records it (`transparent` fill + hairline `outlineVariant` outline).
+
+**Reach for this when** you need a reversible commit that persists across views — *Follow / Following*, *Subscribe / Subscribed*, *Join / Joined*. **Skip when** the action is one-shot ([Standard Button](./standard.md)), the row is a dense toolbar ([Toolbar Button](./toolbar.md)), or the toggle belongs to a filter set ([Filter Chip](../chip/filter.md)).
+
+**Layout inset.** `inline` — ships no padding outside its own chrome. Sits inside a host slot (profile card footer, channel header, list-row trailing slot) with the host paying surrounding rhythm. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), the host already owns the inset — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Inactive
+
+The at-rest urging form — `primary` fill, no border. Used when the action is offered but not yet taken.
+
+```preview
+button/toggle/inactive
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="toggle">
+  Follow
+</Button>
+```
+
+## Active
+
+The committed form — `transparent` fill with hairline `outlineVariant` stroke. The transparent fill lets the button sit on any host surface tier (page `surface`, card `surfaceContainer`, raised `surfaceContainerHigh`) without re-painting a background that would clash with the host. Use the same element across both states and toggle the `active` flag; the consumer swaps the label text. Reports state via `aria-pressed`.
+
+```preview
+button/toggle/active
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="toggle" active>
+  Following
+</Button>
+```
+
+## Use cases
+
+### With icon
+
+A check glyph on commit reinforces the active read. Inactive form stays glyph-less.
+
+```preview
+button/toggle/with-icon
+---
+import { Button } from '@teamblind-chorus/ui';
+import { CheckedIcon } from '@teamblind-chorus/ui/icons';
+
+<Button variant="toggle" active leadingIcon={<CheckedIcon />}>
+  Following
+</Button>
+```
+
+### Focus indicator
+
+Both forms take the same standard ring; below shows inactive. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+```preview
+button/toggle/focused
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="toggle" state="focused">
+  Follow
+</Button>
+```
+
+## Slots
+
+- **label** — accessible name. Required, single line. Consumer swaps the verb between states ("Follow" → "Following"); no auto-rewrite.
+- **leadingIcon** (optional) — context glyph before the label. Inherits colour via `currentColor` per the [family rule](./button.md#icon-colour-inheritance-family-wide).
+- **trailingIcon** (optional) — directional/destination glyph after the label. Same contract as [Toolbar Button](./toolbar.md#with-trailing-icon).
+
+## Sizes
+
+Single fixed footprint — identical to [Toolbar Button](./toolbar.md#sizes) and [Filter chip](../chip/filter.md#sizes).
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Min-height                        | 32px                 | `ref.space.400`                    |
+| Padding (block × inline)          | 4 × 12               | `sys.layout.container.2xs` × `sys.layout.container.sm` |
+| Label inset (within label slot)   | 4px (horizontal)     | `sys.layout.container.2xs`         |
+| Slot gap (icon ↔ label)           | 0                    | —                                  |
+| Radius                            | pill                 | `sys.radius.full`                  |
+| Label                             | 12 / Semibold        | `sys.typo.label.sm`                |
+| Icon                              | 16px                 | `sys.icon.md`                      |
+
+## Variants
+
+A single visual variant — inactive/active is expressed as a state on the same button. Container/label pair swaps wholesale on commit, mirroring the [Filter chip](../chip/filter.md#variants) selection contract.
+
+| State        | Background                          | Border (always 1px `sys.borderWidth.hairline`)          | Label / icon color                | Notes                                                                |
+|--------------|-------------------------------------|---------------------------------------------------------|-----------------------------------|----------------------------------------------------------------------|
+| inactive     | `sys.color.primary`                 | `transparent`                                           | `sys.color.onPrimary`             | Brand-loud fill inviting commit. Border `transparent` but 1px width held so footprint never changes between states. |
+| active       | `transparent`                       | `sys.color.outlineVariant`                              | `sys.color.onSurface`             | Committed form — hairline-outlined ghost over whatever host surface the button sits on. Transparent fill records state without claiming attention or clashing with the host tier. |
+
+## States
+
+| State      | Overlay opacity            | Additional                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | —                          | Container + label at rest.                                                  |
+| `hovered`  | `sys.state.hover` (8%)     | Pointer-driven via `:hover`.                                                |
+| `pressed`  | `sys.state.pressed` (16%)  | Pointer-driven via `:active`.                                               |
+| `disabled` | overlay suppressed         | Container at `sys.state.disabled` (40%) opacity, focus ring suppressed, `cursor: not-allowed`. The hairline stroke (active form) is kept because the variant's identity is the stroke. |
+
+## Focus indicator
+
+Standard ring drawn as a `position: absolute` pseudo-element so it never affects layout. Trigger: `:focus-visible`. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).

package/agents/components/button/toggle.spec.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Button",
+  "family": "button",
+  "subcomponent": "toggle",
+  "description": "Toolbar-footprint toggle button. Inactive (urging) = primary fill that invites the commit; active (committed) = transparent fill with hairline outline that records the commit without re-soliciting it. Transparent fill lets the button sit on any host surface tier (page surface, surfaceContainer, surfaceContainerHigh) without re-painting a background that would clash with the host. Follow ↔ Following, Subscribe ↔ Subscribed, Join ↔ Joined.",
+  "element": "button",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "toggle"
+    },
+    "active": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether the action has been committed. Maps to aria-pressed."
+    },
+    "leadingIcon": {
+      "type": "node",
+      "optional": true
+    },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "label": {
+      "required": true,
+      "description": "Required, single line. Swap between the urging verb (\"Follow\") and the committed participle (\"Following\") at the consumer.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "leadingIcon": {
+      "required": false,
+      "description": "Context glyph before the label — most often a check appearing on commit.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "trailingIcon": {
+      "required": false,
+      "description": "Directional / destination glyph after the label.",
+      "accepts": [
+        "icon"
+      ]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.400",
+    "paddingBlock": "sys.layout.container.2xs",
+    "paddingInline": "sys.layout.container.sm",
+    "labelInset": "sys.layout.container.2xs",
+    "slotGap": "0",
+    "radius": "sys.radius.full",
+    "labelTypo": "sys.typo.label.sm",
+    "iconSize": "sys.icon.md"
+  },
+  "selectionStates": {
+    "unselected": {
+      "background": "sys.color.primary",
+      "label": "sys.color.onPrimary",
+      "border": null
+    },
+    "selected": {
+      "background": "transparent",
+      "label": "sys.color.onSurface",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.outlineVariant"
+      }
+    }
+  },
+  "states": {
+    "default": {
+      "overlay": null
+    },
+    "hovered": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.hover"
+      }
+    },
+    "pressed": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "disabled": {
+      "overlay": null,
+      "containerOpacity": "sys.state.disabled",
+      "suppressFocusRing": true,
+      "cursor": "not-allowed"
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the button is in. The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
+    "composition": "outward",
+    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding layout.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset"
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "forbidden": [
+    "active state painted with sys.color.primary fill — active is transparent + hairline outline (the active state recedes, not asserts)",
+    "active state painted with any opaque surface fill (surface, surfaceContainer, surfaceContainerHigh) — the committed form is transparent so the host surface shows through; do not re-bind to a tier'd fill",
+    "rest state without an explicit `active={false}` — toggle is a binary contract, never tristate",
+    "manual width override that breaks the full-card stretch when used inside ProfileCarousel.followAction"
+  ]
+}

package/agents/components/button/toolbar.md

@@ -0,0 +1,189 @@
+# Toolbar
+
+Dense inline action — a 32-tall capsule for toolbars, table-row actions, and inline menu triggers. Chrome shared with [Filter chip](../chip/filter.md) and [Tabs Segmented](../tabs/segmented.md) so mixed rows read at one density; divergence is intent (Toolbar fires, Filter toggles, Segmented enforces single-select).
+
+**Reach for this when** a dense row needs an inline action — toolbar opener, table-row action, inline menu trigger. **Skip when** the standard inline shape fits ([Button](./button.md)), the affordance floats above content ([FAB](./fab.md)), or the row is body-text density ([Text Button](./text.md)).
+
+**Layout inset.** inline — content-sized; inherits the surrounding row's padding and gap.
+
+## Default
+
+Base shape — label-only on Filter-chip chrome. The quiet inline action.
+
+```preview
+button/toolbar/default
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="toolbar">
+  Edit
+</Button>
+```
+
+## Use cases
+
+### Accent
+
+Brand-blue fill, `onPrimary` label — the single-commit form. Used when the Toolbar Button IS the surface's commit affordance.
+
+```preview
+button/toolbar/accent
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="toolbar" appearance="accent">
+  Save
+</Button>
+```
+
+### Inverse
+
+Mirror for inverse hosts (snackbars, coach-mark surfaces). Geometry identical; colour pair flips.
+
+```preview
+button/toolbar/inverse
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="toolbar" appearance="inverse">
+  Open
+</Button>
+```
+
+### With icon
+
+Context glyph before the label — tag for *Filters*, calendar for *Pick date*.
+
+```preview
+button/toolbar/leading-icon
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button
+  variant="toolbar"
+  leadingIcon={<PlusIcon />}
+>
+  Add row
+</Button>
+```
+
+### With trailing icon
+
+Directional/destination glyph — chevron-down to open a menu, "×" to clear. Unlike standard [Button](./button.md), Toolbar Button carries trailing icons because its role is often *trigger* rather than commit.
+
+```preview
+button/toolbar/trailing-icon
+---
+import { Button } from '@teamblind-chorus/ui';
+import { CheckedIcon } from '@teamblind-chorus/ui/icons';
+
+<Button
+  variant="toolbar"
+  trailingIcon={<CheckedIcon />}
+>
+  Sort by date
+</Button>
+```
+
+### Icon only
+
+Glyph-only 32×32 square. Requires `aria-label`. When the label slot is absent, inline padding drops to `sys.layout.container.xs` (8) so the glyph centers.
+
+```preview
+button/toolbar/icon-only
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button
+  variant="toolbar"
+  leadingIcon={<PlusIcon />}
+  aria-label="Add"
+/>
+```
+
+### Group
+
+Adjacent Toolbar Buttons share `4px` gap (`sys.layout.inline.sm`) with Filter chips. Mix freely.
+
+```preview
+button/toolbar/group
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon, CheckedIcon } from '@teamblind-chorus/ui/icons';
+
+<div style={{ display: 'flex', gap: 4 }}>
+  <Button variant="toolbar" leadingIcon={<PlusIcon />}>
+    Add
+  </Button>
+  <Button variant="toolbar">
+    Edit
+  </Button>
+  <Button variant="toolbar" trailingIcon={<CheckedIcon />}>
+    Sort
+  </Button>
+</div>
+```
+
+### Focus indicator
+
+Hairline stroke is kept underneath the standard ring.
+
+```preview
+button/toolbar/focused
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button variant="toolbar" state="focused" leadingIcon={<PlusIcon />}>
+  Add row
+</Button>
+```
+
+## Slots
+
+- **label** — accessible name. Required, single line.
+- **leadingIcon** (optional) — context glyph before the label.
+- **trailingIcon** (optional) — directional/destination glyph after the label.
+
+## Appearance
+
+Only the container ↔ label colour pair flips; geometry identical. For inline destructive commits use standard [Button](./button.md) `secondary` flavored as `destructive`.
+
+| Appearance  | Background                          | Border                                          | Label / icon                       | When to reach for it |
+|-------------|-------------------------------------|--------------------------------------------------|------------------------------------|----------------------|
+| `default`   | `sys.color.surfaceContainerHigh`    | 1px `sys.color.outlineVariant`                   | `sys.color.onSurface`              | Quiet inline action — toolbar opener, "Edit" beside a row title. |
+| `accent`    | `sys.color.primary`                 | none                                             | `sys.color.onPrimary`              | The single commit — a [Page](../navigation-bar/sub.md) bar's "Save". Never two in a row. |
+| `inverse`   | `sys.color.inverseSurface`          | none                                             | `sys.color.inverseOnSurface`       | Inside an inverse host (Toast, coach-mark). |
+
+## Sizes
+
+A single fixed 32px footprint across breakpoints.
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Min-height                        | 32px                 | `ref.space.400` ‡                  |
+| Padding (block × inline)          | 4 × 12               | `sys.layout.container.2xs` × `sys.layout.container.sm` |
+| Label inset (within label slot)   | 4px (horizontal)     | `sys.layout.container.2xs`         |
+| Slot gap (icon ↔ label)           | 0                    | — †                                |
+| Radius                            | pill                 | `sys.radius.full`                  |
+| Label                             | 12 / Semibold        | `sys.typo.label.sm`                |
+| Icon                              | 16px                 | `sys.icon.md`                      |
+
+‡ Footprint shared with [Filter chip](../chip/filter.md) and [Tabs Segmented](../tabs/segmented.md).
+
+† See [Filter → Sizes](../chip/filter.md#sizes).
+
+## States
+
+| State      | Overlay opacity            | Additional                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | —                          | Container + label at rest.                                                  |
+| `hovered`  | `sys.state.hover` (8%)     | `:hover`.                                                                   |
+| `pressed`  | `sys.state.pressed` (16%)  | `:active`.                                                                  |
+| `disabled` | overlay suppressed         | Container at `sys.state.disabled` (40%) opacity, hairline stroke kept, focus ring suppressed, `cursor: not-allowed`. |
+
+## Focus indicator
+
+Standard outward ring with hairline stroke kept underneath. Trigger: `:focus-visible`. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).