@teamblind-chorus/ui 1.0.0

package/agents/components/button/standard.md

@@ -0,0 +1,219 @@
+# Standard
+
+The default inline action surface — a labelled commit (form submit, dialog confirm, row action). Two axes: **size** (`large` / `medium` / `small`), **appearance** (`primary` / `secondary` / `outlined` / `tertiary`).
+
+**Reach for this when** you need a labelled commit inline with content — Save, Continue, Confirm, Cancel. **Skip when** the commit must float above scrolling content ([FAB](./fab.md)), the rung is body-text-sized ([Text Button](./text.md)), or the row is a dense toolbar ([Toolbar Button](./toolbar.md)).
+
+**Layout inset.** inline — content-sized (or `fullWidth`); inherits its surface's padding.
+
+## Default
+
+The single highest-emphasis action — `appearance="primary"`. One per view (Save, Continue, Confirm, Submit).
+
+```preview
+button/standard/default
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button appearance="primary" size="large">
+  Primary action
+</Button>
+```
+
+## Use cases
+
+### Secondary
+
+Lower-emphasis tier paired against `primary` — opposing actions (Cancel beside Save) or quieter alternatives. Safe to repeat on a single view.
+
+```preview
+button/standard/secondary
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button appearance="secondary" size="large">
+  Secondary action
+</Button>
+```
+
+### Outlined
+
+Bordered blue-on-transparent — supplementary option beside `primary` (*See more*, *Learn more*, *Skip for now*). For opposing paths use `secondary`.
+
+```preview
+button/standard/outlined
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button appearance="outlined" size="large">
+  See more
+</Button>
+```
+
+### Tertiary
+
+Neutral grey ghost — transparent at rest, label in `sys.color.onSurfaceVariant`. Reads as a button only on hover.
+
+```preview
+button/standard/tertiary
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button appearance="tertiary" size="large">
+  Tertiary action
+</Button>
+```
+
+### With leading icon
+
+Optional context glyph before the label. Inherits label color via `currentColor` (`sys.icon.lg` on `large`, `sys.icon.md` on `medium`/`small`).
+
+```preview
+button/standard/with-leading-icon
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button
+  appearance="primary"
+  size="large"
+  leadingIcon={<PlusIcon />}
+>
+  Add item
+</Button>
+```
+
+### Full width
+
+Stretched to fill the column (`width: 100%`). Default mobile shape for hero surfaces, empty states, onboarding, login. On wider surfaces, fall back to content-sized.
+
+```preview
+button/standard/full-width
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button
+  appearance="primary"
+  size="large"
+  fullWidth
+>
+  Confirm
+</Button>
+```
+
+### Group
+
+Adjacent Buttons share an **8px** gap (`sys.layout.inline.md` horizontal / `sys.layout.stack.xs` vertical). Horizontal: outlined left, primary right. Vertical: primary top, secondary below.
+
+```preview
+button/standard/group
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', gap: 8 }}>
+  <Button appearance="outlined" size="large">
+    See more
+  </Button>
+  <Button appearance="primary" size="large">
+    Confirm
+  </Button>
+</div>
+```
+
+```preview
+button/standard/group-vertical
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+  <Button appearance="primary" size="large">
+    Save
+  </Button>
+  <Button appearance="secondary" size="large">
+    Cancel
+  </Button>
+</div>
+```
+
+### Truncation
+
+When the column is narrower than the label, it clips with an ellipsis — Buttons are single-line by contract.
+
+```preview
+button/standard/truncation
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button
+  appearance="primary"
+  size="large"
+  fullWidth
+  truncate
+>
+  A very long label that should truncate gracefully
+</Button>
+```
+
+### Focus indicator
+
+Standard keyboard-focus ring (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)).
+
+```preview
+button/standard/focused
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button appearance="primary" size="large" state="focused">
+  Primary action
+</Button>
+```
+
+## Slots
+
+- **label** — accessible name. Required, single line; long labels truncate.
+- **leadingIcon** (optional) — context glyph before the label. Inherits via `currentColor` — see [Button → Icon colour inheritance](./button.md#icon-colour-inheritance).
+
+No trailing icon.
+
+## Appearance
+
+A **destructive** flavor swaps `primary` → `error` across any appearance; reserved for irreversible actions.
+
+| Appearance  | Background    | Border (1px)            | Label color                       | Notes                                                                 |
+|-------------|---------------|--------------------------|-----------------------------------|-----------------------------------------------------------------------|
+| `primary`   | `sys.color.primary`            | —                        | `sys.color.onPrimary`             | Single highest-emphasis action; one per view. |
+| `secondary` | `sys.color.secondaryContainer` | —                        | `sys.color.onSecondaryContainer`  | Lower-emphasis tier; opposing-action and quieter-alternative roles. |
+| `outlined`  | `transparent`                  | `sys.color.primary` (`sys.borderWidth.hairline`) | `sys.color.primary`               | Supplementary option beside `primary`. |
+| `tertiary`  | `transparent`                  | —                        | `sys.color.onSurfaceVariant`      | Lowest-emphasis neutral ghost. |
+
+## Sizes
+
+| Size     | Padding (block × Inline)                                            | Gap (icon ↔ label)            | Min-height               | Min-width                  | Radius                | Label                              | Icon                |
+|----------|---------------------------------------------------------------------|-------------------------------|--------------------------|----------------------------|-----------------------|------------------------------------|---------------------|
+| `large`  | `sys.layout.container.xs` × `sys.layout.container.md` (8 × 16)      | `sys.layout.inline.md` (8)    | `ref.space.600` (48) ‡   | **160** ⁂                  | `sys.radius.md` (8)   | `sys.typo.label.lg` (16, semibold) | `sys.icon.lg` (24)  |
+| `medium` | `sys.layout.container.xs` × `sys.layout.container.md` (8 × 16)      | `sys.layout.inline.md` (8)    | `ref.space.500` (40) ‡   | **160** ⁂                  | `sys.radius.md` (8)   | `sys.typo.label.md` (14, semibold) | `sys.icon.md` (16)  |
+| `small`  | `sys.layout.container.2xs` × `sys.layout.container.sm` (4 × 12)     | `sys.layout.inline.sm` (4)    | `ref.space.400` (32) ‡   | **160** ⁂                  | `sys.radius.sm` (4) † | `sys.typo.label.md` (14, semibold) | `sys.icon.md` (16)  |
+
+† Small Button's intended radius is 6px; implementation falls back to `sys.radius.sm` (4) until a 6px step lands.
+
+‡ `min-height` binds raw `ref.space.*` — `sys.*` does not expose 32 / 40 / 48 px steps.
+
+⁂ **Min-width 160px** is fixed across sizes so a row of buttons reads as one composition. `fullWidth` and `truncate` override.
+
+## 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`. |
+
+## Focus indicator
+
+Standard outward 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).
+
+## Behavior
+
+- **Chrome-aligned filled form** — layout by chrome (see [Button → Optical alignment](./button.md#optical-alignment)).
+- **Single line.** Long labels truncate; 160px min-width keeps a row reading as one composition unless `fullWidth` or `truncate` overrides.

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

@@ -0,0 +1,205 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Button",
+  "family": "button",
+  "subcomponent": "standard",
+  "description": "Standard inline action button. Two independent axes: size (chosen by surface), appearance (chosen by emphasis). Fixed-footprint. The default button form — reach for FAB / Toolbar Button / Toggle Button when the standard inline shape does not fit.",
+  "element": "button",
+  "props": {
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "primary",
+        "secondary",
+        "outlined",
+        "tertiary"
+      ],
+      "default": "primary"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "large",
+        "medium",
+        "small"
+      ],
+      "default": "large"
+    },
+    "leadingIcon": {
+      "type": "node",
+      "optional": true
+    },
+    "fullWidth": {
+      "type": "boolean",
+      "default": false
+    },
+    "truncate": {
+      "type": "boolean",
+      "default": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "label": {
+      "required": true,
+      "description": "Accessible name. Single line.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "leadingIcon": {
+      "required": false,
+      "description": "Optional context glyph before the label. Inherits currentColor.",
+      "accepts": [
+        "icon"
+      ]
+    }
+  },
+  "sizes": {
+    "large": {
+      "paddingBlock": "sys.layout.container.xs",
+      "paddingInline": "sys.layout.container.md",
+      "gap": "sys.layout.inline.md",
+      "minHeight": "ref.space.600",
+      "minWidth": "160px",
+      "radius": "sys.radius.md",
+      "labelTypo": "sys.typo.label.lg",
+      "iconSize": "sys.icon.lg"
+    },
+    "medium": {
+      "paddingBlock": "sys.layout.container.xs",
+      "paddingInline": "sys.layout.container.md",
+      "gap": "sys.layout.inline.md",
+      "minHeight": "ref.space.500",
+      "minWidth": "160px",
+      "radius": "sys.radius.md",
+      "labelTypo": "sys.typo.label.md",
+      "iconSize": "sys.icon.md"
+    },
+    "small": {
+      "paddingBlock": "sys.layout.container.2xs",
+      "paddingInline": "sys.layout.container.sm",
+      "gap": "sys.layout.inline.sm",
+      "minHeight": "ref.space.400",
+      "minWidth": "160px",
+      "radius": "sys.radius.sm",
+      "labelTypo": "sys.typo.label.md",
+      "iconSize": "sys.icon.md"
+    }
+  },
+  "appearances": {
+    "primary": {
+      "background": "sys.color.primary",
+      "border": null,
+      "label": "sys.color.onPrimary"
+    },
+    "secondary": {
+      "background": "sys.color.secondaryContainer",
+      "border": null,
+      "label": "sys.color.onSecondaryContainer"
+    },
+    "outlined": {
+      "background": "transparent",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.primary"
+      },
+      "label": "sys.color.primary"
+    },
+    "tertiary": {
+      "background": "transparent",
+      "border": null,
+      "label": "sys.color.onSurfaceVariant"
+    }
+  },
+  "flavors": {
+    "destructive": {
+      "description": "Swaps the primary family → error family across every appearance. Reserved for irreversible commits (Delete, Remove, Discard).",
+      "appearances": {
+        "primary": {
+          "background": "sys.color.error",
+          "border": null,
+          "label": "sys.color.onError"
+        },
+        "secondary": {
+          "background": "sys.color.errorContainer",
+          "border": null,
+          "label": "sys.color.onErrorContainer"
+        },
+        "outlined": {
+          "background": "transparent",
+          "border": {
+            "width": "sys.borderWidth.hairline",
+            "color": "sys.color.error"
+          },
+          "label": "sys.color.error"
+        },
+        "tertiary": {
+          "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": {
+    "labelLine": "single",
+    "truncation": {
+      "whiteSpace": "nowrap",
+      "overflow": "hidden",
+      "textOverflow": "ellipsis"
+    },
+    "fullWidth": {
+      "width": "100%"
+    }
+  },
+  "forbidden": [
+    "raw <button> wrapper styled with Tailwind / inline-style instead of the chorus-button--standard chrome",
+    "appearance=tertiary / outlined used as the screen's primary commit — the highest-emphasis commit uses appearance=primary; the lower-emphasis appearances are for secondary / supporting actions",
+    "destructive flavor used outside Dialog / BottomSheet primary-action context",
+    "raw `border:` declaration — the edge stroke is an inset box-shadow",
+    "manual focus ring via `outline:` — the ring is the `::after` overlay layer"
+  ]
+}

package/agents/components/button/text.md

@@ -0,0 +1,186 @@
+# Text
+
+The link-shaped commit surface — reads as text at rest, paints a button-like hover overlay and focus ring on interaction. Two axes: **appearance** (`default` / `accent` / `onPrimary` / `inverse`), **size** (`medium` / `small` / `xsmall`).
+
+**Reach for this when** the action is inline next to typographic content and commits — *Skip*, *Edit*, *Resend*, a section's trailing *See all*. **Skip when** the affordance navigates — use [Text link](../../DESIGN.md#text-links).
+
+**Layout inset.** inline — optical alignment is on by default, so the visible label box *is* the layout box; chrome bleeds outward only on hover.
+
+## Default
+
+Neutral label (`onSurfaceVariant`) in a transparent capsule — the base inline action ("Not now", trailing dismissals).
+
+```preview
+button/text/default
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="text">Not now</Button>
+```
+
+## Use cases
+
+### Accent
+
+Brand-blue label (`primary`) — the inline commit. Reach for `accent` when the button reads as a navigational link (*See all*, *Follow*, *View details*).
+
+```preview
+button/text/accent
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="text" appearance="accent">Skip</Button>
+```
+
+### On primary
+
+Always-white label on top of a `primary`-filled host (Tooltip `default`). Theme-stable.
+
+```preview
+button/text/on-primary
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="text" appearance="onPrimary">Got it</Button>
+```
+
+### Inverse
+
+For inverse hosts (Toast, coach-mark, snackbar). Label paints `inverseOnSurface`; tokens flip with theme.
+
+```preview
+button/text/inverse
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="text" appearance="inverse">Undo</Button>
+```
+
+### With leading icon
+
+16px (`sys.icon.md`) glyph before the label at 4px gap — fixed across rungs.
+
+```preview
+button/text/leading-icon
+---
+import { Button, ChevronLeftIcon } from '@teamblind-chorus/ui';
+
+<Button variant="text" leadingIcon={<ChevronLeftIcon />}>Back</Button>
+```
+
+### With trailing icon
+
+Destination glyph after the label — chevron-right *Continue*, external-link *Open in new tab*.
+
+```preview
+button/text/trailing-icon
+---
+import { Button, ChevronRightIcon } from '@teamblind-chorus/ui';
+
+<Button variant="text" trailingIcon={<ChevronRightIcon />}>Continue</Button>
+```
+
+### Dropdown
+
+Disclosure trigger: the label reads as the **current value**, the trailing chevron flips with state — `ChevronDownIcon` at rest, `ChevronUpIcon` while the menu is open. Pair `aria-haspopup` + `aria-expanded` on the trigger and portal the menu so it escapes any clipping ancestor; never freeze the chevron when the menu is open.
+
+Default rung is `xsmall` for inline / toolbar dropdowns (Size selectors, filter chrome, header trailing). Step up to `small` or `medium` when the dropdown is the row's primary commit.
+
+```preview
+button/text/dropdown
+---
+import { useState } from 'react';
+import { Button } from '@teamblind-chorus/ui';
+import { ChevronDownIcon, ChevronUpIcon } from '@teamblind-chorus/ui/icons';
+
+function Example() {
+  const [open, setOpen] = useState(false);
+  return (
+    <Button
+      variant="text"
+      size="xsmall"
+      trailingIcon={open ? <ChevronUpIcon /> : <ChevronDownIcon />}
+      aria-haspopup="listbox"
+      aria-expanded={open}
+      onClick={() => setOpen((v) => !v)}
+    >
+      Medium
+    </Button>
+  );
+}
+```
+
+### Group
+
+Optical alignment means chrome-to-chrome gap **is** the visible label-to-label distance. Row gap: `medium`/`small` → 16px (`sys.layout.inline.xl`); `xsmall` → 12px (`sys.layout.inline.lg`).
+
+```preview
+button/text/group
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-md)' }}>
+  <Button variant="text">Cancel</Button>
+  <Button variant="text" appearance="accent">Save</Button>
+</div>
+```
+
+### Focus indicator
+
+Standard ring.
+
+```preview
+button/text/focused
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="text" state="focused">Skip</Button>
+```
+
+## Slots
+
+- **label** — accessible name. Required, single line.
+- **leadingIcon** (optional) — context glyph before the label. 16px on every rung. Inherits via `currentColor`.
+- **trailingIcon** (optional) — directional/destination glyph after the label.
+
+## Appearance
+
+A **destructive** flavor swaps the label to `error` across every appearance.
+
+| Appearance  | Background (rest) | Label color                       | When to reach for it                                                                 |
+|-------------|-------------------|-----------------------------------|--------------------------------------------------------------------------------------|
+| `default`   | `transparent`     | `sys.color.onSurfaceVariant`      | Base inline action — "Not now", secondary inline trail commits. |
+| `accent`    | `transparent`     | `sys.color.primary`               | Brand-blue inline commit — "Skip", "See all". One per row. |
+| `onPrimary` | `transparent`     | `sys.color.onPrimary`             | On a `primary`-filled host (Tooltip `default`). Theme-stable. |
+| `inverse`   | `transparent`     | `sys.color.inverseOnSurface`      | Inside an inverse host (Toast, coach-mark). |
+
+## Sizes
+
+Three rungs. `medium` matches [Icon Button](./icon.md)'s 40-tall footprint; `small` / `xsmall` for denser call-sites. Icon and slot gap stay fixed (16px / 4px); only label rank and capsule height shrink.
+
+| Size      | Min-height       | Padding (block × inline)        | Slot gap                          | Label                          | Icon                          |
+|-----------|------------------|----------------------------------|-----------------------------------|--------------------------------|-------------------------------|
+| `medium`  | 40px (`ref.space.500`) ‡ | 8 × 8 (`sys.layout.container.xs` × `sys.layout.container.xs`) | 4px (`sys.layout.inline.sm`)   | 16 / Semibold (`sys.typo.heading.sm`) | 16px (`sys.icon.md`) |
+| `small`   | 32px (`ref.space.400`) ‡ | 4 × 8 (`sys.layout.container.2xs` × `sys.layout.container.xs`) | 4px (`sys.layout.inline.sm`)   | 14 / Semibold (`sys.typo.label.md`)   | 16px (`sys.icon.md`) |
+| `xsmall`  | 24px (`ref.space.300`) ‡ | 4 × 8 (`sys.layout.container.2xs` × `sys.layout.container.xs`) | 4px (`sys.layout.inline.sm`)   | 12 / Semibold (`sys.typo.label.sm`)   | 16px (`sys.icon.md`) |
+
+‡ `min-height` binds raw `ref.space.*` — `sys.*` does not expose 24/32/40 px steps.
+
+## States
+
+Overlay paints the **label color** over the transparent container.
+
+| State      | Overlay opacity            | Additional                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | —                          | Transparent capsule.                                                        |
+| `hovered`  | `sys.state.hover` (8%)     | `:hover`.                                                                   |
+| `pressed`  | `sys.state.pressed` (16%)  | `:active`.                                                                  |
+| `disabled` | overlay suppressed         | Label at `sys.state.disabled` (40%) opacity, focus ring suppressed, `cursor: not-allowed`. |
+
+## Focus indicator
+
+Standard outward ring. Trigger: `:focus-visible`. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+## Optical alignment
+
+Transparent at rest — the eye locks onto the label. Default rendering negates per-rung padding via `margin: calc(-1 × padding-block) calc(-1 × padding-inline)` so the visible **label box is the layout box**. Not opt-in.