@teamblind-chorus/ui 1.0.0

package/agents/components/bubble/bubble.md

@@ -0,0 +1,134 @@
+# Bubble
+
+A small persistent annotation pill with a tail pointing at an anchor — a chat-icon "new messages" flag, a search-bar campaign nudge, a feature-flag callout. Sibling of [Tooltip](../tooltip/tooltip.md): Tooltip is transient and overlays neighbours on hover; Bubble stays in view at the resting state, sits lower in visual priority (no elevation, smaller padding, single line), and never occludes the surrounding chrome.
+
+**Reach for this when** the annotation must remain readable as part of the resting UI. **Skip when** the hint is invoked on demand (use [Tooltip](../tooltip/tooltip.md)), carries a decision or blocking meaning (use [Banner](../banner/banner.md) / [Dialog](../dialog/dialog.md)), or is just a numeric count beside an icon (use [Badge](../badge/badge.md)).
+
+**Layout inset.** `inline` — the bubble ships no positioning. The host anchors it to the target element by *visual alignment* (CSS anchor positioning, or a positioned wrapper around the anchor): the tail's TIP sits flush on the anchor's content edge (padding excluded) — the bubble body is set back from that edge by the tail's own protrusion (`ref.space.50 / √2`) so the tail meets the anchor cleanly rather than overlapping it — and the bubble centres on the anchor's visual centre so the tail sits at the anchor's bottom-centre. The bubble caps its own `max-width` so it always keeps an 8-token margin from every viewport edge; position-clamping is the host's job. Only when centring would push the bubble past that safe margin does the host shift it inward and flip `tailAlign` so the tail still points at the anchor — `start` for left-edge anchors, `end` for right-edge anchors, `center` whenever the anchor has room on both sides (the default).
+
+**Colour tuning.** Default fill `sys.color.primary` / label `sys.color.onPrimary` — both theme-stable. Operations re-tint per campaign by setting `--bubble-fill` and `--bubble-ink` on inline style; the tail's `background: inherit` follows automatically.
+
+## Default
+
+```preview
+bubble/default
+---
+import { Bubble } from '@teamblind-chorus/ui';
+
+<Bubble>5 new messages + gift</Bubble>
+```
+
+## Use cases
+
+### Anchored to a top-bar icon
+
+A [Navigation bar (home)](../navigation-bar/main.md) with three trailing actions, bubble anchored to the chat glyph itself. The glyph carries `anchor-name: --chat-icon`; the bubble pins to the glyph's bottom — padding excluded — set back by the tail's own protrusion (`top: calc(anchor(bottom) + var(--bubble-tail-protrusion))`, the system token = `ref.space.50 / √2`) so the tail's top vertex lands *flush* on the glyph's bottom edge rather than poking into it, and centres on the glyph's visual centre (`left: anchor(center)` + `translateX(-50%)`). The tail tip thus sits on the chat icon's bottom-centre regardless of where the bar reflows — no hardcoded pixel offsets, `tailAlign="center"`.
+
+```preview
+bubble/anchored-icon
+---
+import { Bubble, NavigationBar } from '@teamblind-chorus/ui';
+import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+
+<div style={{ position: 'relative', paddingBottom: 'var(--sys-layout-stack-2xl)' }}>
+  <NavigationBar
+    variant="main"
+    title={
+      <img
+        src="/blind_logotype_black.svg"
+        alt="Chorus"
+        className="chorus-brand-logotype"
+        style={{ height: 24, width: 'auto', display: 'block' }}
+      />
+    }
+    trailingActions={[
+      { icon: <SearchIcon />, 'aria-label': 'Search' },
+      {
+        // `anchor-name` straight on the <svg> — no wrapper, so the icon
+        // button still sizes the glyph to the large 24-rung.
+        icon: <ChatIcon style={{ anchorName: '--chat-icon' }} />,
+        'aria-label': 'Messages',
+      },
+      { icon: <ProfileIcon />, 'aria-label': 'Profile' },
+    ]}
+  />
+  <div style={{
+    position: 'absolute',
+    positionAnchor: '--chat-icon',
+    // Set back by the tail's protrusion so the tail's top vertex sits flush
+    // on the glyph's bottom, not inside it. `--bubble-tail-protrusion`
+    // (= ref.space.50 / √2 ≈ 2.83px) is exposed at :root by the system.
+    top: 'calc(anchor(bottom) + var(--bubble-tail-protrusion))',
+    left: 'anchor(center)',
+    transform: 'translateX(-50%)',
+    display: 'flex',
+  }}>
+    <Bubble tailSide="top" tailAlign="center">5 new messages + gift</Bubble>
+  </div>
+</div>
+```
+
+### Tail alignment
+
+Three tail positions stacked so the offset reads at a glance — pick by where the anchor sits.
+
+```preview
+bubble/tail-positions
+---
+import { Bubble } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', flexDirection: 'column', alignItems: 'flex-start', gap: 'var(--sys-layout-stack-md)' }}>
+  <Bubble tailSide="top" tailAlign="start">New here?</Bubble>
+  <Bubble tailSide="top" tailAlign="center">Try free</Bubble>
+  <Bubble tailSide="top" tailAlign="end">Today only</Bubble>
+</div>
+```
+
+### Operations re-tint
+
+Brand red instead of primary blue — the tail inherits the fill, so a single declaration covers both surfaces.
+
+```preview
+bubble/recoloured
+---
+import { Bubble } from '@teamblind-chorus/ui';
+
+<Bubble style={{ '--bubble-fill': 'var(--sys-color-brand)', '--bubble-ink': 'var(--sys-color-onBrand)' }}>
+  Free daily tarot
+</Bubble>
+```
+
+### Long copy
+
+Copy that exceeds the host width truncates with an ellipsis. If the message can't fit on one line, it belongs in a [Banner](../banner/banner.md) instead.
+
+```preview
+bubble/long-copy
+---
+import { Bubble } from '@teamblind-chorus/ui';
+
+<div style={{ maxWidth: 220 }}>
+  <Bubble>A long campaign label that exceeds the bubble width and truncates with an ellipsis</Bubble>
+</div>
+```
+
+## Slots
+
+- **container** — pill body. `role='note'`.
+- **body** — copy. Single line; overflow truncates with an ellipsis.
+- **tail** — 4 × 4 square rotated 45°, `background: inherit`. Position driven by `tailSide` + `tailAlign`. `aria-hidden`.
+
+## Anatomy
+
+| Slot      | Token bindings |
+|-----------|----------------|
+| container | Fill `--bubble-fill` (default `sys.color.primary`), ink `--bubble-ink` (default `sys.color.onPrimary`), `sys.layout.container.2xs` padding-block, `ref.space.75` padding-inline, `sys.radius.full`, viewport-safe `max-width` cap |
+| body      | `sys.typo.caption` |
+| tail      | `ref.space.50` square, rotated 45° |
+
+## Behavior
+
+- **Persistent.** No hover/focus trigger, no entry/exit animation, no dismissal — the host removes the bubble when the moment passes.
+- **Single line.** Body never wraps. Overflow truncates rather than reflows.
+- **Host positions.** Bubble is presentational. The host anchors it to the target by visual alignment — the tail's tip flush on the anchor's content edge (the bubble body set back by the tail's protrusion, padding excluded), bubble centred on the anchor's visual centre so the tail sits at its bottom-centre, 8-token viewport-safe margin, `tailAlign` flipping to `start`/`end` only when the safe margin forces the bubble off-centre — all the host's contract.
+- **Never occludes.** No elevation shadow, not portal-mounted. If a parent clips the bubble, fix the parent.

package/agents/components/bubble/bubble.spec.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Bubble",
+  "family": "bubble",
+  "description": "Always-on annotation bubble — a pill-shaped label with a small tail that points at the anchor UI element. Ships with a default brand-blue fill (`sys.color.primary` / `sys.color.onPrimary` — both theme-stable so the bubble reads identically in light and dark mode) and exposes two CSS custom properties (`--bubble-fill`, `--bubble-ink`) so operations can re-tint per campaign without forking the component. Distinct from Tooltip on three axes: (1) persistent rather than transient — Bubble stays in view as part of the UI's resting state; (2) lower visual priority — no elevation shadow, smaller padding, single-line truncation; (3) does NOT occlude its neighbours — the host positions it inline next to the anchor, never as a portal-mounted overlay.",
+  "element": "div",
+  "props": {
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "Bubble copy. Single line by default — overflow truncates with an ellipsis."
+    },
+    "tailSide": {
+      "type": "enum",
+      "values": ["top", "bottom"],
+      "default": "top",
+      "description": "Which edge of the bubble grows a tail. `top` (default) places the tail on the bubble's top edge, pointing UP toward an anchor that sits above the bubble. `bottom` mirrors for anchors below the bubble."
+    },
+    "tailAlign": {
+      "type": "enum",
+      "values": ["start", "center", "end"],
+      "default": "center",
+      "description": "Where along the tail edge the tail sits. `center` (default) parks it dead-centre; `start` and `end` shift it toward the leading / trailing corner so the tail lines up with an off-centre anchor."
+    },
+    "className": {
+      "type": "string",
+      "optional": true,
+      "description": "Composes with the bubble's own class. Operations colour overrides should land on inline style as `--bubble-fill` / `--bubble-ink` rather than re-skinning via className."
+    },
+    "style": {
+      "type": "object",
+      "optional": true,
+      "description": "Standard inline style. The two custom properties consumers most often set here are `--bubble-fill` (background tone) and `--bubble-ink` (label tone) for runtime tinting."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "The pill body. `position: relative` so the tail can pin to its edge; `display: inline-flex` so the bubble shrink-wraps its body. Carries the fill (`--bubble-fill` defaulting to `sys.color.primary`), ink (`--bubble-ink` defaulting to `sys.color.onPrimary`), 4 / 6 padding, and pill radius. `role='note'` so the annotation reads as supplementary rather than as a main UI control.",
+      "intrinsic": true
+    },
+    "body": {
+      "required": true,
+      "description": "Bubble copy in `sys.typo.caption` (10 / Semibold). Single line — `white-space: nowrap` + `text-overflow: ellipsis` truncate overflow rather than wrap. Inherits the container's ink colour.",
+      "accepts": ["text"]
+    },
+    "tail": {
+      "required": true,
+      "description": "Decorative tail. A 4 × 4 square rotated 45° so a diamond vertex protrudes from the bubble's edge; `background: inherit` so it tracks the runtime fill including operations tints. Position is driven by `[data-tail-side]` + `[data-tail-align]`. `aria-hidden='true'` because the tail carries no semantic meaning.",
+      "intrinsic": true
+    }
+  },
+  "sizing": {
+    "background": "sys.color.primary",
+    "foreground": "sys.color.onPrimary",
+    "labelTypo": "sys.typo.caption",
+    "paddingBlock": "sys.layout.container.2xs",
+    "paddingInline": "ref.space.75",
+    "radius": "sys.radius.full",
+    "tailSize": "ref.space.50",
+    "tailEdgeInset": "ref.space.100",
+    "viewportSafeArea": "sys.layout.container.xs"
+  },
+  "appearance": {
+    "background": "sys.color.primary",
+    "foreground": "sys.color.onPrimary",
+    "note": "Single canonical appearance — Bubble has no `default` / `accent` / `destructive` axis. Default fill is `sys.color.primary` and label is `sys.color.onPrimary`; both are theme-stable so the bubble reads identically in light and dark mode. Operations re-tint by setting `--bubble-fill` and `--bubble-ink` on the bubble's inline style or a wrapping class — the tail inherits the fill via `background: inherit`, so a colour swap on the container covers the whole bubble in one declaration. Re-tints should keep the contrast above WCAG AA against `--bubble-ink` (4.5:1); the system does not enforce this at runtime."
+  },
+  "behavior": {
+    "ariaRole": "Container carries `role='note'` so screen readers announce the bubble as a supplementary note rather than as a main UI control. The decorative tail carries `aria-hidden='true'`.",
+    "truncation": "Single-line by default — `white-space: nowrap` keeps the body on one line and `text-overflow: ellipsis` truncates overflow at the container's max-inline-size. `max-width` is clamped to the lesser of `100%` and `calc(100vw - 2 × sys.layout.container.xs)`, so the parent column's width caps overflow and — as a hard-baked safety net — the bubble can never grow wide enough to break the 8-token viewport safe margin even if the host mis-positions it.",
+    "viewportSafeArea": "The bubble must keep an 8-token (`sys.layout.container.xs`, the same rung Tooltip uses for the same role) margin from every display edge. Width-clamping is built into the component CSS as a safety net; *position*-clamping (preventing the bubble's left or right edge from drifting into the safe area) is a host responsibility — when the anchor sits within 8 of an edge, the host must shift the bubble away from the edge and update `tailAlign` so the tail still points at the anchor.",
+    "tailTipCentredOnAnchor": "**The tail's TIP lands on the anchor's horizontal centre** — the canonical pointing contract (not 'the bubble is near the anchor'). Achieve it by *visual alignment*, not a hand-tuned pixel fudge: anchor the bubble to the target (CSS anchor positioning — `position-anchor` + `left: anchor(center)` + `translateX(-50%)`, or a positioned wrapper around the anchor) and centre the bubble on the anchor's visual centre with `tailAlign='center'`, so the tip falls on the anchor's centreX by construction. If the tip drifts off that centreline by more than ~2px, the bubble reads as pointing at empty space. (This is the HORIZONTAL axis; the one derived constant the host encodes is the VERTICAL set-back — see zeroGapToAnchor.)",
+    "zeroGapToAnchor": "**The tail's TIP sits flush on the anchor's CONTENT edge (padding excluded) — no overlap, no gap.** This is the canonical home of the set-back math. Align to the anchor's content box, not its padding box: the tail-bearing edge (top for `tailSide='top'`, bottom for `tailSide='bottom'`) is set BACK from the anchor by the tail's own protrusion so the tail's outer vertex lands exactly on the anchor's content edge. The tail is a `ref.space.50` (4) square rotated 45°, so its vertex pokes `ref.space.50 / √2` ≈ 2.83 past the bubble edge; the system exposes this at :root as `--bubble-tail-protrusion`, and the host adds exactly that set-back (e.g. `top: calc(anchor(bottom) + var(--bubble-tail-protrusion))`). Overlapping the anchor reads as a collision; a gap larger than the protrusion leaves the tail unattached. For more breathing room, widen the *anchor's* padding — never enlarge the set-back. This √2 set-back is the single derived constant in the contract; the horizontal axis is pure visual alignment.",
+    "tailAlignSelection": "`tailAlign='center'` is the default and preferred case — the bubble centres on the anchor so the tail sits dead-centre and its tip falls on the anchor's centreX by construction (see tailTipCentredOnAnchor). It flips off-centre only as an edge fallback: when the anchor sits so near a viewport edge that centring would push the bubble past the 8-token safe margin, the bubble shifts AWAY from the edge and `tailAlign` flips to the SAME side as the anchor — `end` at the right edge (bubble extends leftward), `start` at the left edge (bubble extends rightward). In every case the bubble's nearest edge stays ≥8 from the viewport edge and the tip stays on the anchor's centreline; visibility is the contract, tail position is the lever.",
+    "positioning": "Bubble is presentational — the *host* owns positioning, and the canonical pattern binds bubble to anchor by VISUAL ALIGNMENT (CSS anchor positioning, or a positioned wrapper around the anchor) rather than DOM proximity, so the tail tracks the anchor through reflows. Four coupled decisions, each detailed in its own rule: (a) `tailSide` — `top` when the bubble sits below the anchor, `bottom` when above; (b) the vertical set-back so the tail tip is flush on the anchor's content edge — see zeroGapToAnchor; (c) horizontal centring so the tip lands on the anchor's centreX — see tailTipCentredOnAnchor; (d) `tailAlign`, `center` by default and flipped only at a viewport edge — see tailAlignSelection. Get any one wrong and the tail points at empty space.",
+    "colorTuning": "Two CSS custom properties — `--bubble-fill` (background) and `--bubble-ink` (label) — are the supported runtime override surface. Default to `sys.color.primary` / `sys.color.onPrimary`. Operations campaigns set them on inline style; static themes set them on a wrapper class. The tail's `background: inherit` follows automatically."
+  },
+  "forbidden": [
+    "bubble used as a transient hover/focus tooltip — that role is the `tooltip` family; bubble must remain in view at the UI's resting state",
+    "bubble portal-mounted at document root with a fixed z-index that overlays surrounding chrome — bubble must NEVER occlude neighbour elements; that contract is what separates it from Tooltip",
+    "bubble painted with an elevation shadow (`sys.elevation.raised` / `floating` / `overlay` / `sheet`) — the lift signal is what makes Tooltip 'jump'; Bubble is intentionally flat",
+    "bubble copy that wraps to multiple lines — overflow truncates with an ellipsis rather than wrapping; if the message can't fit on one line, it belongs in a Banner or a Tooltip with action",
+    "bubble retinted with hardcoded hex / rgba on `background` or `color` instead of `--bubble-fill` / `--bubble-ink` — campaign tunes must route through the documented custom-property surface so the tail colour tracks the body",
+    "bubble used to convey *required* meaning (error blocking a submit, account-locked notice) — that role is Banner / Dialog; bubble is a soft annotation only",
+    "bubble positioned with any edge inside the 8-token (`sys.layout.container.xs`) viewport safe margin — the host must shift the bubble inward and flip `tailAlign` to keep the tail under the anchor; visibility is the contract, tail position is the lever",
+    "bubble placed under a sibling that occludes it (a scrim, a portal-mounted overlay, an `overflow: hidden` ancestor that clips its body) — Bubble must be fully readable at the UI's resting state; if a parent clips, the host fixes the parent, not the bubble",
+    "bubble whose tail overlaps the anchor, or whose tail tip floats short of the anchor's content edge — the tail's outer vertex must sit flush on the anchor's content edge (padding excluded), with the bubble body set back by the tail's `ref.space.50 / √2` protrusion so the tail meets the anchor without poking into it or hanging off it",
+    "bubble where the tail tip drifts off the anchor's horizontal centreline by more than ~2px — the tail TIP (not the bubble centre, not the bubble edge) must land on the anchor's centreX; otherwise the bubble reads as pointing at empty space"
+  ]
+}

package/agents/components/button/button.family.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "button",
+  "name": "Button",
+  "description": "The system's commit-action family. Seven anchoring forms — `standard` (default inline commit), `fab` (floating action button), `icon` (icon-only inline commit), `text` (link-shaped commit), `check` (text-shaped with leading checkbox toggle), `toggle` (reversible commit), `toolbar` (dense inline action). A cross-cutting `flavor` axis re-tones any form for irreversible commits (`destructive` swaps the primary family → error family). Consumers reach for `standard` by default; the other forms cover roles the standard inline shape does not fit.",
+  "useCases": [
+    "primary commit",
+    "inline action",
+    "save and continue",
+    "floating action",
+    "icon-only action",
+    "link-shaped action",
+    "reversible state",
+    "follow / unfollow",
+    "toolbar action",
+    "option toggle",
+    "item-use toggle"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "usage": {
+    "note": "All button roles are the single `Button` export selected by the `variant` prop — there is NO `<Fab>`, `<IconButton>`, `<ToggleButton>`, or `<Toolbar>` export. An `import { Fab }` failure does NOT mean the family is missing; reach for `<Button variant=\"fab\">`.",
+    "subs": {
+      "fab": { "variant": "fab", "example": "<Button variant=\"fab\" appearance=\"primary\" icon={<EditIcon />}>글쓰기</Button>" },
+      "icon": { "variant": "icon", "example": "<Button variant=\"icon\" aria-label=\"…\" icon={<MoreIcon />} />" }
+    }
+  },
+  "spec": "button.md",
+  "subcomponents": [
+    {
+      "slug": "standard",
+      "spec": "standard.spec.json",
+      "md": "button.md",
+      "default": true
+    },
+    {
+      "slug": "fab",
+      "spec": "fab.spec.json",
+      "md": "fab.md"
+    },
+    {
+      "slug": "icon",
+      "spec": "icon.spec.json",
+      "md": "icon.md"
+    },
+    {
+      "slug": "text",
+      "spec": "text.spec.json",
+      "md": "text.md"
+    },
+    {
+      "slug": "check",
+      "spec": "check.spec.json",
+      "md": "check.md"
+    },
+    {
+      "slug": "toggle",
+      "spec": "toggle.spec.json",
+      "md": "toggle.md"
+    },
+    {
+      "slug": "toolbar",
+      "spec": "toolbar.spec.json",
+      "md": "toolbar.md"
+    }
+  ],
+  "axes": {
+    "flavor": [
+      "default",
+      "destructive"
+    ]
+  },
+  "iconColor": "currentColor",
+  "iconColorNote": "Family-wide rule: every Button sub-component paints its icon glyph (leadingIcon / trailingIcon / icon slot) in the label / foreground colour via `currentColor`. SVG glyphs must declare `fill=\"currentColor\"` / `stroke=\"currentColor\"` and carry no hardcoded colour, so swapping `appearance`, entering `disabled` / hovered / pressed, or applying a `destructive` flavor re-tones the glyph in lockstep with the label without per-icon overrides. Sub-spec `appearances[*].iconColor` is implicit and equal to `appearances[*].label` — renderers should read the label token and apply it as both the label colour AND the icon's `currentColor`.",
+  "notes": "The `destructive` flavor is encoded on the three sub-specs that idiomatically host destructive commits: `standard`, `icon`, `text` — each carries a top-level `flavors.destructive` block that mirrors the appearance(s) with the primary-family → error-family swap. Other sub-specs (`fab`, `check`, `toggle`, `toolbar`) deliberately omit it: FAB is reserved for the surface's single canonical commit (a destructive primary commit belongs in a Dialog confirmation, not a free-floating FAB); Check is a state toggle, not a one-way commit; Toggle is a reversible state, not a one-way commit; Toolbar Button delegates chrome to Filter chip, which has no destructive role. If a destructive variant is added to any of those, encode it as `flavors.destructive` mirroring the same recipe."
+}

package/agents/components/button/button.md

@@ -0,0 +1,31 @@
+# Button
+
+The action-surface family. **Standard Button** is the default inline filled / outlined / tertiary control; the rest specialise by **shape · context · footprint**: floating canvas commit (FAB), glyph-only capsule (Icon Button), chromeless link-shaped commit (Text Button), dense capsule for toolbars and tabs (Toolbar Button), reversible commit at the Toolbar footprint (Toggle Button), option-toggle with leading checkbox (Check Button). Per-sub intent lives on each sub's page.
+
+**Layout inset.** `inline` — slot atom. No page-rail responsibility; the surrounding container places it. Lives inside another component's slot (List row trailing, Section header trailing, NavigationBar trailing, BottomSheet action stack) or inside a layout `<div>` that already pays the page gutter. The FAB sub is the one exception — pinned to the page viewport, not the row rail.
+
+## Cross-sub contract
+
+Three contracts hold across every family member — change one and every sub re-tones.
+
+### Icon colour inheritance
+
+**Every Button family component paints icon glyphs in the label / foreground colour via `currentColor`.** The SVG must declare `fill="currentColor"` (or `stroke="currentColor"`) with no hardcoded colour. Icon size follows the host's typography rung (24 on `large`, 16 on `medium`/`small`).
+
+### Optical alignment
+
+Transparent-rest forms ([Icon Button](./icon.md), [Text Button](./text.md), [Tertiary appearance of Standard Button](./standard.md#tertiary)) apply negative-margin compensation so the **glyph / label bounding box** is the layout box. Filled forms ([Standard Button](./standard.md), [FAB](./fab.md), [Toolbar Button](./toolbar.md)) align by **chrome**: the visible container is the layout box.
+
+### Focus ring
+
+All Button family components draw the same outward two-layer ring as a `position: absolute` pseudo-element — never a layout-affecting border. Suppressed while `disabled`. Trigger: `:focus-visible`. See [DESIGN.md → Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+## Sub-components
+
+- **[Check](./check.md)** — Option-toggle commit with a required leading checkbox glyph (outline → fill on `checked`) and an optional middle icon. Two sizes; reads as a [Text](./text.md) Button with a checkbox.
+- **[FAB](./fab.md)** — Surface-elevated pill anchored to the canvas; commit stays reachable while content scrolls.
+- **[Icon](./icon.md)** — 40 × 40 transparent capsule, glyph-only. Requires `aria-label`.
+- **[Standard](./standard.md)** — The default inline action. Four appearance treatments (`primary` / `secondary` / `outlined` / `tertiary`) over three sizes.
+- **[Text](./text.md)** — Link-shaped commit at the 16/Semibold rung; reads as inline `primary` type at rest.
+- **[Toggle](./toggle.md)** — Reversible commit at the Toolbar footprint. Follow ↔ Following.
+- **[Toolbar](./toolbar.md)** — 32px capsule for dense inline actions. Chrome shared with [Filter chip](../chip/filter.md).

package/agents/components/button/check.md

@@ -0,0 +1,138 @@
+# Check
+
+Option-toggle commit — a [Text Button](./text.md) with a required leading checkbox glyph that flips outline → fill on `checked`, plus an optional middle icon. Two sizes (`medium` / `small`) where the checkbox footprint is the differentiator.
+
+**Reach for this when** an option is committed alongside the surface's main action — *Use this perk?*, *Apply offer*, *Keep me signed in*. **Skip when** the row is a form-bound checkbox input (out-of-system), the commit is a one-shot action ([Text Button](./text.md)), or the row needs a radio's single-select contract ([Radio list](../list/radio.md)).
+
+**Layout inset.** `inline` — ships no padding outside its own chrome. Sits inside a host slot (Dialog confirmation row, BottomSheet option strip, perk-card footer) 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).
+
+## Default
+
+Leading 24px checkbox outline + label, no optional icon. Base neutral appearance — `onSurfaceVariant` label.
+
+```preview
+button/check/default
+---
+import { useState } from 'react';
+import { Button } from '@teamblind-chorus/ui';
+
+function Demo() {
+  const [checked, setChecked] = useState(false);
+  return (
+    <Button
+      variant="check"
+      size="medium"
+      checked={checked}
+      onClick={() => setChecked((v) => !v)}
+    >
+      Invisible to Coworkers
+    </Button>
+  );
+}
+
+<Demo />
+```
+
+## Use cases
+
+### Accent
+
+Brand-blue label — `sys.color.primary`. Use sparingly; never two accent Check Buttons in the same row.
+
+```preview
+button/check/accent
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="check" size="medium" appearance="accent" checked>
+  Apply offer
+</Button>
+```
+
+### Inverse
+
+Mirror for inverse hosts (Toast, coach-mark, snackbar). Label paints `sys.color.inverseOnSurface` against the host's `inverseSurface` fill.
+
+```preview
+button/check/inverse
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="check" size="medium" appearance="inverse" checked>
+  Keep me signed in
+</Button>
+```
+
+### Checked
+
+Same row with `checked={true}` — checkbox glyph flips to the filled square. State overlays follow the label color.
+
+```preview
+button/check/checked
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="check" size="medium" checked>
+  Invisible to Coworkers
+</Button>
+```
+
+### With middle icon
+
+Optional 16px icon between checkbox and label. Use sparingly — most rows don't need it. Canonical case: an item-use row where the middle glyph names the item being consumed.
+
+```preview
+button/check/icon
+---
+import { Button } from '@teamblind-chorus/ui';
+import { BookmarkFillIcon } from '@teamblind-chorus/ui/icons';
+
+<Button variant="check" size="medium" icon={<BookmarkFillIcon />} checked>
+  Use 1 promotion link
+</Button>
+```
+
+## Appearance
+
+Three appearances. `default` is the base neutral toggle; `accent` paints the label in the brand commit colour (one option per row); `inverse` for Toast / coach-mark / snackbar hosts.
+
+| Appearance | Background (rest) | Label color                  | When to reach for it                                                  |
+|-----------|-------------------|------------------------------|-----------------------------------------------------------------------|
+| `default` | `transparent`     | `sys.color.onSurfaceVariant` | The base neutral toggle — option rows next to a primary commit.       |
+| `accent`  | `transparent`     | `sys.color.primary`          | One option per row that needs commit-rank emphasis.                   |
+| `inverse` | `transparent`     | `sys.color.inverseOnSurface` | Inside an inverse host (Toast, coach-mark, snackbar).                 |
+
+## Slots
+
+- **checkbox** *(intrinsic, 24 / 16px)* — leading glyph rendered by the component based on `checked`. 24px on `medium`, 16px on `small`. Consumers do NOT pass an icon node; only `checked`.
+- **icon** *(optional, 16px)* — middle context glyph between checkbox and label. Inherits label color via `currentColor`. `aria-hidden`.
+- **label** *(required)* — accessible name. Single line.
+
+## Sizes
+
+Two rungs. Text rank identical (`sys.typo.label.sm`, 12) — the visual difference comes from the checkbox footprint.
+
+| Size   | Min-height | Padding (block × inline) | Label                    | Checkbox | Icon | Slot gap |
+|--------|------------|--------------------------|--------------------------|----------|------|----------|
+| medium | 40         | `xs` × `xs`              | `sys.typo.label.sm` (12) | 24       | 16   | 4        |
+| small  | 32         | `2xs` × `xs`             | `sys.typo.label.sm` (12) | 16       | 16   | 4        |
+
+## States
+
+Same recipe as [Text Button](./text.md#states): rest, hovered, pressed, disabled. Hover/pressed overlays paint `--button-check-label` at `sys.state.hover` / `sys.state.pressed`. Disabled drops container opacity to `sys.state.disabled` and suppresses the focus ring.
+
+## Focus indicator
+
+Standard `:focus-visible` ring. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+```preview
+button/check/focused
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="check" state="focused">Invisible to Coworkers</Button>
+```
+
+## Accessibility
+
+Toggle button — sets `aria-pressed={checked}` automatically. Do NOT model as a checkbox input (no form value, no name/value pair). For a form-bound checkbox, reach for `<input type="checkbox">` (out-of-system at present).

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

@@ -0,0 +1,161 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Button",
+  "family": "button",
+  "subcomponent": "check",
+  "description": "Option-toggle commit surface — a Text Button (default appearance) with a required leading checkbox glyph that flips outline → fill with the `checked` state and an optional middle icon between the checkbox and the label. Reach for this whenever an option is committed alongside (or selected for) a main action — the canonical Blind use is an in-app item-use affordance like 'Apply this perk?' that flips state before the surface's primary commit fires. Two sizes (`medium` / `small`) where the checkbox footprint is the size differentiator: medium pairs a 24px checkbox with 12-rank text, small drops the checkbox to 16px alongside the same 12-rank text. Appearances and state behavior mirror `button/text`. The optional middle icon stays at 16px on both rungs.",
+  "element": "button",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "check"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "medium",
+        "small"
+      ],
+      "default": "medium"
+    },
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "default",
+        "accent",
+        "inverse"
+      ],
+      "default": "default"
+    },
+    "checked": {
+      "type": "boolean",
+      "default": false,
+      "description": "Toggle state. `true` paints the leading checkbox glyph as a filled square; `false` paints it as an outline. The component itself renders the checkbox glyph — consumers do NOT pass a checkbox icon node, only the `checked` state."
+    },
+    "icon": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional context glyph rendered between the checkbox and the label (e.g. a coin glyph next to 'Use 1 perk'). Sized 16px on every rung — matches the optional middle icon footprint to `button/text` so the row reads at one density."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "checkbox": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Leading checkbox glyph. 24px on `medium`, 16px on `small` — the checkbox footprint is the size differentiator. Rendered by the component based on the `checked` prop — outline glyph when `checked=false`, fill glyph when `checked=true`. `aria-hidden`; the button's accessible name lives on the label and the toggle state is exposed via `aria-pressed`.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "icon": {
+      "required": false,
+      "description": "Optional context glyph between checkbox and label. 16px (`sys.icon.md`) on every rung — matches `button/text`'s icon footprint. On `medium` it sits one rung below the 24px checkbox; on `small` it matches the 16px checkbox at the same footprint. Inherits the label color via `currentColor`. `aria-hidden`.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "label": {
+      "required": true,
+      "description": "Button's accessible name. Required, single line.",
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "sizes": {
+    "medium": {
+      "minHeight": "ref.space.500",
+      "paddingBlock": "sys.layout.container.xs",
+      "paddingInline": "sys.layout.container.xs",
+      "radius": "sys.radius.full",
+      "labelTypo": "sys.typo.label.sm",
+      "checkboxSize": "sys.icon.lg",
+      "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.sm",
+      "checkboxSize": "sys.icon.md",
+      "iconSize": "sys.icon.md",
+      "slotGap": "sys.layout.inline.sm"
+    }
+  },
+  "appearances": {
+    "default": {
+      "background": "transparent",
+      "border": null,
+      "label": "sys.color.onSurfaceVariant",
+      "note": "The base neutral inline toggle — the canonical Check 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 toggle. Use sparingly — never two `accent` Check Buttons in the same row."
+    },
+    "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."
+    }
+  },
+  "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": "Two sizes only — `medium` (40 min-height, 24px checkbox, 12-rank label) and `small` (32 min-height, 16px checkbox, 12-rank label). Text size is identical across rungs; the **checkbox footprint** is the visual differentiator. Padding + radius mirror `button/text` at the matching min-height. Per-element gap is 4 (`sys.layout.inline.sm`). Optical alignment is inherited: the chrome is transparent at rest, negative margin cancels the chrome's contribution to the layout box so the checkbox + label visible footprint defines the layout edge.",
+    "ariaPressed": "Check Button is a toggle button. The component sets `aria-pressed={checked}` automatically and renders the matching checkbox glyph; consumers wire `onChange` (or `onClick` + setState) on the parent. Don't model it as a checkbox input — it is a `<button>` with toggle semantics, not a form control.",
+    "iconColor": "The 24px checkbox glyph inherits the label color via `currentColor`, same as `icon` and `button/text`'s leading/trailing slots. Re-tones with appearance + disabled + hover.",
+    "group": "Stacks vertically when multiple Check Buttons share an option band. Row gap follows `sys.layout.stack.md` between sibling checks; never use a wider gap that would visually disjoint sibling options."
+  },
+  "forbidden": [
+    "checkbox rendered as raw <input type=checkbox> without the chorus-button--check chrome",
+    "label split from the checkbox — the entire row is the click target",
+    "indeterminate state synthesized via opacity instead of the declared check state"
+  ]
+}