@teamblind-chorus/ui 1.0.0

package/agents/components/toast/toast.family.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "toast",
+  "name": "Toast",
+  "description": "Transient confirmation strip \u2014 a short status message anchored to the viewport edge, surfaced after a user action lands (saved, copied, sent). Inverse-toned by default so the message contrasts with any underlying page tier without per-surface tuning. Single-spec family.",
+  "useCases": [
+    "transient confirmation",
+    "post-action status",
+    "undo affordance",
+    "non-blocking notice"
+  ],
+  "visualReuse": "locked",
+  "layoutInset": "bounded-surface",
+  "wrapperGuidance": "Renders into a body portal (or owns its own surface chrome). Place the call as a sibling of the page shell \u2014 do NOT wrap in a layout container, padding div, or className=\"px-*\". Full-bleed children inside the surface body get the negative-margin opt-out \u2014 see AGENTS.md \u00a7 Composition rules.",
+  "spec": "toast.md",
+  "usage": {
+    "note": "Message is children, not a `message` prop; an action / dismiss control goes in the `trailing` slot (an inverse-appearance Button).",
+    "example": "<Toast trailing={<Button variant=\"text\" appearance=\"inverse\" onClick={() => {}}>Undo</Button>}>…</Toast>"
+  },
+  "subcomponents": [
+    {
+      "slug": "toast",
+      "spec": "toast.spec.json",
+      "md": "toast.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/toast/toast.md

@@ -0,0 +1,133 @@
+# Toast
+
+A transient confirmation strip that floats above the page after a user action lands — saved, copied, sent, retried. Inverse-toned by default so the message contrasts with any underlying page tier; content-driven width up to a 400 cap.
+
+**Reach for this when** you need to confirm a system outcome the user just triggered — saved, copied, sent, retried. **Skip when** the message is contextual to the content itself (use [Banner](../banner/banner.md)), or the surface is a committed confirmation prompt (use [Dialog](../dialog/dialog.md)).
+
+**Layout inset.** `bounded-surface` — floating shell *above* the page. Anchored **bottom-center of the viewport** (`position: fixed; bottom: 0; left: 50%; transform: translateX(-50%)`) — never bottom-left, never bottom-right, never inline inside content flow. Pays its own `sys.layout.container.xs` (= **8px**) safe area on all four sides from the viewport edge; content-driven width grows up to `min(400px, 100vw - 16px)` (the `16 = 2 × 8` = the left/right safe-area margins together), so on a 320-wide viewport the strip caps at 304, and on a 600-wide viewport it caps at 400. Mount via a portal at the document root, not inside `<main>`; the page shell's `layout.page.*` gutter does NOT apply (the toast lives outside the gutter system, on its own viewport-anchored coordinate). See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+**Trailing action / dismiss color contract — `appearance="inverse"` is mandatory.** Toast paints `inverseSurface` (dark on a light page, light on a dark page) and the trailing Button MUST bind to `appearance="inverse"` so its label / glyph reads against the inverse fill. Passing a default-appearance Text Button (the canonical link-affordance `primary` blue) produces the unreadable `primary` -on- `inverseSurface` failure mode that fails contrast and reads as "default page action accidentally floating on top of a toast". The inverse cluster is non-negotiable for both action (`<Button variant="text" size="small" appearance="inverse">`) and dismiss (`<Button variant="icon" size="medium" appearance="inverse">`).
+
+## Default
+
+The bare confirmation strip — body text only. Inverse surface, 48 min-height, 16 / 8 inset, single line.
+
+```preview
+toast/default
+---
+import { Toast } from '@teamblind-chorus/ui';
+
+<Toast>Token copied to clipboard</Toast>
+```
+
+## Use cases
+
+### With action
+
+A small Text Button (`appearance="inverse"`) on the trailing edge for follow-through (Undo, Retry, View). With the trailing slot present, the toast stays on screen longer (~6s). The Button node is passed directly so the call site spells out the sub-component.
+
+```preview
+toast/with-action
+---
+import { Toast, Button } from '@teamblind-chorus/ui';
+
+<Toast trailing={
+  <Button variant="text" size="small" appearance="inverse" onClick={() => {}}>
+    Undo
+  </Button>
+}>
+  Message deleted
+</Toast>
+```
+
+### With dismiss
+
+A medium Icon Button (`appearance="inverse"`) on the trailing edge for explicit dismissal — used when the toast carries information the user may want to read at their own pace. Composed at the call site so the `appearance="inverse"` binding stays visible.
+
+```preview
+toast/with-dismiss
+---
+import { Toast, Button } from '@teamblind-chorus/ui';
+import { XIcon } from '@teamblind-chorus/ui/icons';
+
+<Toast trailing={
+  <Button
+    variant="icon"
+    size="medium"
+    appearance="inverse"
+    icon={<XIcon />}
+    aria-label="Dismiss"
+    onClick={() => {}}
+  />
+}>
+  Synced 12 channels in the background
+</Toast>
+```
+
+### Max width
+
+Strip grows until it hits the 400 cap (or viewport-minus-safe-area on narrow screens). Past that, the body wraps onto a second line rather than letting the strip stretch into a banner.
+
+```preview
+toast/max-width
+---
+import { Toast } from '@teamblind-chorus/ui';
+
+<Toast>Saved your draft to every workspace you joined this month</Toast>
+```
+
+### Truncation
+
+Body wraps up to two lines and truncates with an ellipsis past that — body, trailing button, and any leading glyph stay vertically centred. Pair with a trailing dismiss when the message is status the user may want to read at their own pace.
+
+```preview
+toast/truncation
+---
+import { Toast, Button } from '@teamblind-chorus/ui';
+import { XIcon } from '@teamblind-chorus/ui/icons';
+
+<Toast trailing={
+  <Button
+    variant="icon"
+    size="medium"
+    appearance="inverse"
+    icon={<XIcon />}
+    aria-label="Dismiss"
+    onClick={() => {}}
+  />
+}>
+  Saved your draft and synced 12 channels across every workspace you joined this month — long enough that the body has to wrap and then truncate at two lines.
+</Toast>
+```
+
+## Appearance
+
+A single appearance — inverse. The inverse pair (`inverseSurface` / `inverseOnSurface`) is the only one the toast renders in. A toast in a surface-family tone would read as part of the underlying page rather than a status message floating above it.
+
+| Appearance | Container fill              | Foreground                       | When to use |
+|------------|-----------------------------|----------------------------------|-------------|
+| `default`  | `sys.color.inverseSurface`  | `sys.color.inverseOnSurface`     | Every toast. Status messages that must read against any surface tier in the stack. |
+
+## Slots
+
+- **container** — pill-shaped strip. Horizontal flex with `align-items: center`; 16 / 8 inset; 48 min-height; content-driven width up to a 400 cap; `sys.radius.md` corners; `sys.elevation.overlay` shadow. `role="status"`, `aria-live="polite"`.
+- **body** — confirmation copy. `body.sm` / Regular / inherits container foreground. Wraps when the body would push the strip past the 400 cap (or the viewport-minus-safe-area cap on narrow screens), and truncates with an ellipsis past the second line.
+- **trailing** *(optional)* — a Button node. The canonical bindings are `<Button variant="text" size="small" appearance="inverse">` for an action (Undo, View, Retry) or `<Button variant="icon" size="medium" appearance="inverse">` for explicit dismissal. Right-aligned, with an `inline.xl` gap from the body.
+
+## Anatomy
+
+| Slot      | Token bindings |
+|-----------|----------------|
+| container | Fill + foreground per appearance, `sys.radius.md` (8) corners, `sys.layout.container.md` (16) inline padding, `sys.layout.container.xs` (8) block padding, 48 min-height, `min(400px, 100vw - 2 × sys.layout.container.xs)` max-width (content-driven up to the cap), `sys.elevation.overlay` shadow, `sys.layout.container.xs` (8) safe area from the viewport edge |
+| body      | `sys.typo.body.sm` (14 / Regular), color inherits, two-line clamp with `text-overflow: ellipsis` past the second line, vertically centred on the container's cross axis |
+| trailing  | Pass-through Button node. Canonical bindings: `Button variant="text" size="small" appearance="inverse"` for action; `Button variant="icon" size="medium" appearance="inverse"` for dismiss. `sys.layout.inline.xl` (16) gap from the body. Both bindings rely on the inverse cluster so the label / glyph reads against the toast's `inverseSurface` fill without a per-host tweak. |
+
+## States
+
+Container carries no interactive state. The trailing button follows the standard Button state contract.
+
+## Behavior
+
+- **Lifecycle.** Presentational. Owner code mounts the Toast and unmounts after a fixed beat — ~1.6s for a no-action toast, ~6s when an action slot is present. Hover does not pause the timer; toasts are non-essential.
+- **Position.** Bottom-center of the viewport with `sys.layout.container.xs` (8) safe area on all sides. Multiple concurrent toasts stack from bottom up.
+- **Role.** Container carries `role="status"` and `aria-live="polite"` so screen readers announce the confirmation without interrupting focus. The trailing button is a discrete interactive child and remains keyboard-reachable.

package/agents/components/toast/toast.spec.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Toast",
+  "family": "toast",
+  "description": "Transient confirmation strip — a short post-action status message that floats above the page (typically bottom-center) and dismisses on its own after a beat. Default appearance binds to the inverse pair (`inverseSurface` / `inverseOnSurface`), the same role pair that anchors snackbars and coach-marks, so the toast reads as a single visual family across light and dark modes without per-surface tuning. Optional trailing slot accepts either a small text button (undo, view, retry) or a medium icon button (dismiss).",
+  "element": "div",
+  "props": {
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "Body text — short confirmation phrase. Single line by intent; wraps within the toast when the viewport forces it."
+    },
+    "trailing": {
+      "type": "node",
+      "optional": true,
+      "description": "A Button node rendered at the trailing edge. The canonical bindings are `<Button variant=\"text\" size=\"small\" appearance=\"inverse\">` for an action (Undo, View, Retry) or `<Button variant=\"icon\" size=\"medium\" appearance=\"inverse\">` for explicit dismissal. Accepts a node (rather than a shorthand object) so the call site spells out the sub-component composition — including its `appearance=\"inverse\"` binding — instead of hiding it inside the Toast."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "The pill-shaped surface. Horizontal flex with align-items: center so the body and the trailing slot share the same vertical axis. role='status', aria-live='polite'.",
+      "intrinsic": true
+    },
+    "body": {
+      "required": true,
+      "description": "The confirmation copy. body.sm / Regular / inherits container foreground.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "trailing": {
+      "required": false,
+      "description": "Optional trailing slot — accepts a Button node directly. Canonical bindings: `Button variant=\"text\" size=\"small\" appearance=\"inverse\"` for an action affordance, or `Button variant=\"icon\" size=\"medium\" appearance=\"inverse\"` for explicit dismissal. **`appearance=\"inverse\"` is mandatory** — toast paints `inverseSurface`, so a Text Button with the default `primary` appearance produces an unreadable primary-on-inverseSurface failure mode. Anchored to the right edge with a flex gap from the body.",
+      "accepts": [
+        "button"
+      ],
+      "buttonContract": {
+        "appearance": {
+          "required": "inverse",
+          "rationale": "Toast paints inverseSurface; only the inverse cluster reads legibly. The default link-affordance `primary` Text Button (the canonical Section header / card header `See all` color) is forbidden here — it falls back to primary blue against the dark toast fill and fails contrast."
+        }
+      }
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.600",
+    "maxWidth": "min(400px, calc(100vw - 2 * sys.layout.container.xs))",
+    "radius": "sys.radius.md",
+    "paddingInline": "sys.layout.container.md",
+    "paddingBlock": "sys.layout.container.xs",
+    "safeArea": "sys.layout.container.xs",
+    "slotGap": "sys.layout.inline.xl",
+    "bodyTypo": "sys.typo.body.sm"
+  },
+  "position": {
+    "anchor": "viewport-bottom-center",
+    "css": "position: fixed; bottom: 0; left: 50%; transform: translateX(-50%)",
+    "safeArea": {
+      "token": "sys.layout.container.xs",
+      "value": "ref.space.100",
+      "applies": "all four sides from the viewport edge"
+    },
+    "maxWidth": "min(400px, 100vw - 16px)",
+    "note": "Toast is always bottom-center of the viewport, never bottom-left, bottom-right, or inline. The 8px safe area on all four sides is non-negotiable; max-width grows up to 400 or `100vw - 16` (whichever is smaller), so the 8px horizontal safe area is preserved even on narrow viewports. External renderers MUST anchor the portal to the document root."
+  },
+  "appearances": {
+    "default": {
+      "background": "sys.color.inverseSurface",
+      "foreground": "sys.color.inverseOnSurface",
+      "note": "The inverse pair is the only appearance — toasts always read as a contrasting strip against the page. Action buttons inside an inverse surface fall back to the regular primary family per the inverse-cluster contract."
+    }
+  },
+  "behavior": {
+    "lifecycle": "Owner code mounts the Toast when a user action lands and unmounts it after a fixed beat (~1.6s for a no-action toast, ~6s when an action slot is present). The component itself is presentational — it does not manage its own timer.",
+    "role": "Container carries role='status' and aria-live='polite' so screen readers announce the confirmation without interrupting the user's current focus."
+  },
+  "forbidden": [
+    "Toast painted with sys.color.surface — toast uses sys.color.inverseSurface fill + inverseOnSurface text",
+    "Toast as a blocking commit prompt — destructive prompts use Dialog or BottomSheet; toast is for non-blocking feedback",
+    "Toast persistent (no auto-dismiss)",
+    "More than one toast stacked — toast queue is single-at-a-time",
+    "Toast anchored bottom-left, bottom-right, top-anything, or inline inside the content flow — toast is bottom-center of the viewport only; any edge alignment breaks the focus-attention contract and collides with the safe-area inset",
+    "Toast horizontal safe area below 8px (sys.layout.container.xs) — the 8px left/right margin from the viewport edge is the non-negotiable floor; reducing it allows the strip to touch the screen edge on narrow viewports",
+    "Toast max-width exceeding `min(400px, 100vw - 16px)` — at viewports < 416px the strip MUST shrink so 8px safe area on each side is preserved",
+    "Toast trailing Button with appearance=\"default\" — toast paints inverseSurface, so the default link-affordance `primary` blue Text Button reads as unreadable primary-on-inverseSurface. Both action (`text` / `small`) and dismiss (`icon` / `medium`) MUST carry appearance=\"inverse\"",
+    "Toast trailing Button rendered as raw <a> / <button> or a non-Button node — the trailing slot is typed `button`; the inverse-cluster binding is what makes the affordance legible"
+  ]
+}

package/agents/components/tooltip/tooltip.family.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "tooltip",
+  "name": "Tooltip",
+  "description": "Trigger-anchored explanation bubble \u2014 a small contrast-toned surface with a caret pointing at the element it describes. Reach for it to surface a label or short hint that does not fit on the trigger itself; prefer [Banner](../banner/banner.md) when the message belongs in the reading flow rather than over it, and [Toast](../toast/toast.md) when the message confirms a recent action rather than describing a hovered/focused control. Single-spec family.",
+  "useCases": [
+    "trigger-anchored hint",
+    "icon-button label",
+    "coach-mark banner",
+    "compact disclosure"
+  ],
+  "visualReuse": "locked",
+  "layoutInset": "bounded-surface",
+  "wrapperGuidance": "Renders into a body portal (or owns its own surface chrome). Place the call as a sibling of the page shell \u2014 do NOT wrap in a layout container, padding div, or className=\"px-*\". Full-bleed children inside the surface body get the negative-margin opt-out \u2014 see AGENTS.md \u00a7 Composition rules.",
+  "spec": "tooltip.md",
+  "usage": {
+    "note": "Hint text is children, not a `text` prop; an optional action goes in the `action` slot (a node) — `placement` anchors the caret to the trigger.",
+    "example": "<Tooltip placement=\"top\" action={<Button variant=\"text\" appearance=\"onPrimary\" onClick={() => {}}>Got it</Button>}>…</Tooltip>"
+  },
+  "subcomponents": [
+    {
+      "slug": "tooltip",
+      "spec": "tooltip.spec.json",
+      "md": "tooltip.md",
+      "default": true
+    }
+  ],
+  "notes": "Initial scaffold \u2014 visual contract may iterate. Surface binds to the inverse cluster (per DESIGN.md's tooltip note) so the bubble reads against any underlying page tier without per-host tuning; action-button bindings mirror Toast."
+}

package/agents/components/tooltip/tooltip.md

@@ -0,0 +1,139 @@
+# Tooltip
+
+A trigger-anchored explanation bubble — a small contrast-toned surface with a caret that points at the host. Reach for it to surface a label or short hint that does not fit on the trigger ("Manage" on an icon button, a coach-mark). Prefer [Banner](../banner/banner.md) when the message belongs inline in the reading flow, and [Toast](../toast/toast.md) when it confirms a recent user action.
+
+**Layout inset.** `bounded-surface` — popover shell anchored to a trigger element. Owns its outer padding and trigger-relative placement; not subject to the page shell's `layout.page.*` gutter. Mount via a portal at the document root and position relative to the trigger. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+The brand-blue bubble — body text only. `primary` fill with `onPrimary` foreground (both theme-stable). 32 min-height, symmetric 12 inset (`sys.layout.container.sm` on every edge), `radius.lg` corners, overlay elevation. Caret renders on the edge facing the trigger. The bubble's **width hugs its content** up to a 300 cap — a one-word label sits tight to the caret, a longer hint grows until it hits the cap and then wraps. Keep copy intuitive at a glance; if the message routinely pushes the cap, it likely belongs in a [Banner](../banner/banner.md) or [Dialog](../dialog/dialog.md).
+
+```preview
+tooltip/default
+---
+import { Tooltip } from '@teamblind-chorus/ui';
+
+<Tooltip placement="top">Tooltip text</Tooltip>
+```
+
+## Use cases
+
+### Inverse
+
+The dark-cluster bubble. Reach for it when the host screen is already saturated with `primary` tone — the inverse cluster (`inverseSurface` / `inverseOnSurface`) reads as a distinct floating note above the page.
+
+```preview
+tooltip/inverse
+---
+import { Tooltip } from '@teamblind-chorus/ui';
+
+<Tooltip placement="top" appearance="inverse">Tooltip text</Tooltip>
+```
+
+### With action
+
+A small Text Button for follow-through ("Learn more", "Got it"). Bind the button's `appearance` to match the tooltip — `onPrimary` for the default (brand-blue) tooltip; `inverse` for the inverse tooltip.
+
+```preview
+tooltip/with-action
+---
+import { Tooltip, Button } from '@teamblind-chorus/ui';
+
+<Tooltip placement="top" action={
+  <Button variant="text" size="small" appearance="onPrimary" onClick={() => {}}>
+    Got it
+  </Button>
+}>
+  Tooltip text
+</Tooltip>
+```
+
+### Multi-line with action
+
+When the body grows past the 300 cap, the body wraps onto a second line and the action slot drops below the body. The body-to-action gap goes from 12 (inline) to 6 (block) so the stacked action reads as part of the same group.
+
+```preview
+tooltip/multiline-action
+---
+import { Tooltip, Button } from '@teamblind-chorus/ui';
+
+<Tooltip placement="bottom" action={
+  <Button variant="text" size="small" appearance="onPrimary" onClick={() => {}}>
+    Learn more
+  </Button>
+}>
+  Tooltip text wraps onto a second line when it would push the bubble past the 300 cap.
+</Tooltip>
+```
+
+### Placements
+
+Six placements, named `<edge>` or `<edge>-<align>`. The `<edge>` axis (top / bottom) places the bubble above or below the trigger and chooses the caret edge; the `<align>` axis (start / center / end) shifts the caret along the parallel axis.
+
+```preview
+tooltip/placements
+---
+import { Tooltip } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, max-content)', gap: 'var(--sys-layout-container-xl)' }}>
+  <Tooltip placement="top-start">Tooltip text</Tooltip>
+  <Tooltip placement="top">Tooltip text</Tooltip>
+  <Tooltip placement="top-end">Tooltip text</Tooltip>
+  <Tooltip placement="bottom-start">Tooltip text</Tooltip>
+  <Tooltip placement="bottom">Tooltip text</Tooltip>
+  <Tooltip placement="bottom-end">Tooltip text</Tooltip>
+</div>
+```
+
+## Appearance
+
+Two appearances — `default` (the canonical brand-blue tooltip) and `inverse` (for primary-heavy screens). See [DESIGN.md → Inverse cluster](../../DESIGN.md).
+
+| Appearance | Container fill              | Foreground                       | Pair the action button with                                   | When to use |
+|------------|-----------------------------|----------------------------------|---------------------------------------------------------------|-------------|
+| `default`  | `sys.color.primary`         | `sys.color.onPrimary`            | `<Button variant="text" appearance="onPrimary">`              | The canonical tooltip — brand-blue bubble, always-white label. |
+| `inverse`  | `sys.color.inverseSurface`  | `sys.color.inverseOnSurface`     | `<Button variant="text" appearance="inverse">`                | When the host screen is saturated with `primary` tone — the dark inverse bubble reads as distinct floating chrome. |
+
+`default` is the right reach in most cases; switch to `inverse` only when the surrounding surface gives the brand-blue bubble no breathing room.
+
+## Slots
+
+- **container** — bubble surface with the caret. Flex; symmetric 12 inset on every edge; 32 min-height; **content-driven width capped at 300** (`min(300px, viewport safe channel)`); `sys.radius.lg` corners; `sys.elevation.overlay` shadow. `role="tooltip"`.
+- **caret** — pointer tail on the edge facing the trigger. 8px footprint; inherits the container fill; flips per `placement` (top edge → caret on the bottom; bottom edge → caret on the top); the `-start` / `-end` aligners shift it along the parallel axis.
+- **body** — hint copy. `body.sm` / Regular / inherits container foreground. Hugs its own width until the 300 cap is reached, then wraps — short copy renders narrow, long copy clamps at the cap and wraps onto a second line.
+- **action** *(optional)* — a Button node. Canonical binding `<Button variant="text" size="small" appearance="onPrimary">` for the default tooltip, or `appearance="inverse"` for the inverse tooltip. Inline next to the body when the body is single-line; drops below the body once the body wraps.
+
+## Anatomy
+
+| Slot      | Token bindings |
+|-----------|----------------|
+| container | Fill + foreground per appearance, `sys.radius.lg` (12) corners, `sys.layout.container.sm` (12) padding on every edge, 32 min-height. **Content-driven width capped at 300** — `width: max-content`, `max-width: min(300px, viewport safe channel)`. Short copy renders narrow; long copy clamps at the cap and wraps. `sys.elevation.overlay` shadow |
+| caret     | 8px footprint, inherits container fill, flipped to the edge facing the trigger per `placement`, `sys.layout.stack.xs` (8) offset between caret tip and trigger |
+| body      | `sys.typo.body.sm` (14 / Regular), color inherits, hugs its own width until the 300 cap is reached, then wraps |
+| action    | Pass-through Button node. Canonical bindings: `Button variant="text" size="small" appearance="onPrimary"` (default appearance) or `appearance="inverse"` (inverse appearance). Inline gap from body = `ref.space.150` (12); block gap when the body wraps = `ref.space.75` (6). |
+
+`ref.space.150` (12) and `ref.space.75` (6) bind to the reference tier because `sys.layout.inline.*` and `sys.layout.stack.*` do not expose a 12-constant or 6-constant rung (per the system's "`sys.*` first, `ref.*` if no semantic alias" rule).
+
+## Alignment
+
+Placement is driven by where the trigger sits on the viewport. The component does not own positioning; the owner positioner enforces these rules.
+
+- **Viewport safe area.** The bubble (chrome + caret) MUST keep at least `sys.layout.container.xs` (8) clear of every viewport edge — same horizontal safe margin Toast pays. When honouring the safe area would push the bubble off its preferred placement, flip to the opposite edge.
+- **Trigger offset.** Caret tip sits `sys.layout.stack.xs` (8) from the trigger's bounding box.
+- **Width contract.** The bubble hugs its content: `width: max-content`, capped at `min(300px, viewport width - 2 × sys.layout.container.xs)`. Short copy renders narrow with the caret tight to the bubble; long copy clamps at the 300 cap and wraps onto a second line. Keep copy intuitive at a glance — the cap is a backstop, not a target.
+- **Mirror the trigger's position.** Pick the `<align>` axis to match the trigger's horizontal position:
+  - Trigger near the **leading** edge → `-start` (caret anchored to the leading edge).
+  - Trigger **centred** → bare edge name (caret at the bubble's centre).
+  - Trigger near the **trailing** edge → `-end` (caret anchored to the trailing edge).
+- **Pick the top/bottom edge by where there's room.** Trigger in the **bottom** half → prefer `top`. Trigger in the **top** half → prefer `bottom`. Collision-flipping is the positioner's job.
+
+## States
+
+Container carries no interactive state. The optional action button follows the standard Button state contract.
+
+## Behavior
+
+- **Lifecycle.** Presentational. Owner code mounts the Tooltip while the trigger is hovered or focused. Typical reveal delay is ~400ms on hover (immediate on focus); the component does not manage the timer.
+- **Role.** Container carries `role="tooltip"`. The trigger MUST own `aria-describedby` pointing at the tooltip's id so screen readers associate the hint with the host.
+- **Copy.** Tooltip text may run longer than a button label, but should stay **brief, essential, and intuitive at a glance** — a fragment, a one-line hint, an action label. The 300 cap is a safety backstop, not a target; if the message routinely fills it, it likely belongs in a [Banner](../banner/banner.md) or [Dialog](../dialog/dialog.md). The content-driven width means a one-word label like "Manage" sits tight to the caret rather than padding out to a fixed footprint — the visual length matches the semantic length.
+- **Reach for this when** the message describes a hovered or focused control. **Skip when** the message belongs in the reading flow (use [Banner](../banner/banner.md)) or confirms a recent action (use [Toast](../toast/toast.md)).

package/agents/components/tooltip/tooltip.spec.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Tooltip",
+  "family": "tooltip",
+  "description": "Trigger-anchored explanation bubble — a small contrast-toned surface with a caret that points at the host element. Two appearances: `default` (primary/onPrimary) is the brand-blue tooltip used by default, and `inverse` (inverseSurface/inverseOnSurface) for screens already saturated with primary tone. Optional action slot accepts a small text button bound to the matching `onPrimary` or `inverse` appearance.",
+  "element": "div",
+  "props": {
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "Body text — a short, essential hint or label. The bubble's width is content-driven (it hugs the body) and capped at 300; copy should stay brief and intuitive at a glance — a fragment, a one-line hint, an action label. The 300 cap is a safety backstop, not a target; if the message routinely fills it, it likely belongs in a Banner or Dialog."
+    },
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "default",
+        "inverse"
+      ],
+      "default": "default",
+      "description": "`default` paints the bubble in `primary` with an `onPrimary` foreground — the brand-blue tooltip. `inverse` paints in the inverse cluster (`inverseSurface` / `inverseOnSurface`) for use on screens already saturated with primary tone, where the brand-blue bubble would compete with the surrounding chrome."
+    },
+    "placement": {
+      "type": "enum",
+      "values": [
+        "top-start",
+        "top",
+        "top-end",
+        "bottom-start",
+        "bottom",
+        "bottom-end"
+      ],
+      "default": "top",
+      "description": "Where the bubble sits relative to its trigger. The `<edge>` axis (top / bottom) chooses whether the bubble floats above or below the trigger and which edge the caret renders on. The `<align>` axis (start / center / end) shifts the caret along the parallel axis so it lines up with an off-centre trigger — pick `-start` when the trigger sits near the leading edge of the viewport, `-end` when it sits near the trailing edge, and the bare edge name when the trigger is comfortably centred. Left/right placements are intentionally not in the enum — Tooltip is a top/bottom affordance; for side-anchored disclosure surfaces reach for a popover-style host instead."
+    },
+    "action": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional Button node rendered after the body. Canonical bindings: `<Button variant=\"text\" size=\"small\" appearance=\"onPrimary\">` for the `default` (primary) tooltip, or `<Button variant=\"text\" size=\"small\" appearance=\"inverse\">` for the `inverse` tooltip — so the label paints in the correct on-host token in either theme. Layout: inline-trailing when the body fits on one line; stacks below the body once the body wraps."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "The bubble surface with the caret. Appearance-bound fill, overlay elevation, lg-radius. role='tooltip'.",
+      "intrinsic": true
+    },
+    "caret": {
+      "required": true,
+      "description": "The pointer tail rendered on the edge facing the trigger. Inherits the container fill so the tail reads as one shape with the bubble. Edge flips per `placement` (top → bottom-edge caret pointing down at the trigger; bottom → top-edge caret pointing up); align (`-start` / `-end`) shifts the caret along the parallel axis.",
+      "intrinsic": true
+    },
+    "body": {
+      "required": true,
+      "description": "The hint copy. `body.sm` / Regular / inherits container foreground. The bubble is content-driven (see `sizing.widthContract`) — short copy renders narrow with the caret tight to the bubble, long copy clamps at the 300 cap and wraps onto a second line.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "action": {
+      "required": false,
+      "description": "Optional slot accepting a Button node. Canonical bindings: `Button variant=\"text\" size=\"small\" appearance=\"onPrimary\"` (default tooltip) or `appearance=\"inverse\"` (inverse tooltip). Inline next to the body when the body is single-line; drops below the body once the body wraps. Inline gap from body = `ref.space.150` (12); block gap when stacked = `ref.space.75` (6) so the wrapped action reads as part of the same group rather than a new row.",
+      "accepts": [
+        "button"
+      ]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.400",
+    "maxWidth": "300px",
+    "widthContract": "Content-driven — the bubble hugs its body. CSS: `width: max-content` (shrink-wraps the body); `max-width: min(300px, calc(100vw - 2 × viewportSafeArea))` (enforces both the 300 cap and the 8/8 viewport safe area when portal-mounted at the document root). Short body strings render narrow with the caret tight to the bubble; long copy clamps at the 300 cap and wraps onto a second line. The cap is a safety backstop, not a target — copy that routinely fills it belongs in a Banner or Dialog instead.",
+    "radius": "sys.radius.lg",
+    "paddingInline": "sys.layout.container.sm",
+    "paddingBlock": "sys.layout.container.sm",
+    "actionInlineGap": "ref.space.150",
+    "actionBlockGap": "ref.space.75",
+    "triggerOffset": "sys.layout.stack.xs",
+    "viewportSafeArea": "sys.layout.container.xs",
+    "caretSize": "ref.space.100",
+    "bodyTypo": "sys.typo.body.sm"
+  },
+  "appearances": {
+    "default": {
+      "background": "sys.color.primary",
+      "foreground": "sys.color.onPrimary",
+      "elevation": "sys.elevation.overlay",
+      "note": "Brand-blue bubble with an always-white label. Both `primary` and `onPrimary` are theme-stable, so the bubble reads the same in light and dark mode. Action buttons inside this appearance MUST use `Button variant=\"text\" appearance=\"onPrimary\"` so the label stays white in either theme — `appearance=\"inverse\"` flips with the theme and would render the label dark in dark mode."
+    },
+    "inverse": {
+      "background": "sys.color.inverseSurface",
+      "foreground": "sys.color.inverseOnSurface",
+      "elevation": "sys.elevation.overlay",
+      "note": "Inverse-cluster bubble for screens already saturated with primary tone, where the `default` brand-blue tooltip would compete with the surrounding chrome. Action buttons inside this appearance use `Button variant=\"text\" appearance=\"inverse\"` so the label flips with the host fill."
+    }
+  },
+  "behavior": {
+    "lifecycle": "Presentational. Owner code mounts the Tooltip while the trigger is hovered or focused, and unmounts it when the trigger loses both. Typical reveal delay is ~400ms on hover (immediate on focus); the component does not manage the timer.",
+    "role": "Container carries role='tooltip'. The trigger MUST own `aria-describedby` pointing at the tooltip's id so screen readers associate the hint with the host element.",
+    "placementSelection": "Pick `placement` so the bubble fits the trigger's position on the viewport: when the trigger sits near the leading edge of the viewport, use a `-start` aligner so the caret stays anchored to the trigger while the bubble extends inward; mirror for the trailing edge with `-end`. The `top` / `bottom` edge choice depends on which side has room — typically `top` when the trigger sits in the bottom half of the viewport, `bottom` when it sits in the top half. The owner positioner is responsible for collision-flipping (`top` → `bottom` when the bubble would clip).",
+    "viewportSafeArea": "The bubble (chrome + caret) MUST keep at least `sys.layout.container.xs` (8) clear of the viewport edge on every side — same 8/8 horizontal safe area Toast pays. The owner positioner enforces this; when honouring the safe area would push the bubble off its preferred placement, flip to the opposite edge before nudging within the safe area. The bubble's `max-width` is `min(300px, viewport width - 2 × viewportSafeArea)` so the safe channel and the cap meet cleanly at narrow widths.",
+    "triggerOffset": "The caret tip sits `sys.layout.stack.xs` (8) away from the trigger's bounding box — same `stack.xs` rung the rest of the system uses for vertical breathing room between an anchor and a floating element. The owner positioner applies this offset when placing the bubble.",
+    "widthHug": "The bubble's width is driven by its body, not by the channel. A one-word label like 'Manage' sits tight to the caret; a longer hint grows until it hits the 300 cap, then wraps onto a second line. The visual length matches the semantic length — short hints don't pad out to a fixed footprint, long hints don't escape the cap. This replaces the previous always-fill contract (the bubble no longer stretches to a fixed 240 footprint regardless of copy)."
+  },
+  "forbidden": [
+    "Tooltip used as a non-blocking confirmation — that role is the `toast` family",
+    "Tooltip rendered without a trigger anchor — tooltip is always anchored to a specific element via the trigger contract",
+    "Tooltip persistent (no auto-dismiss on blur / pointer-leave)",
+    "fixed `width` override on the Tooltip container — width is content-driven and capped at 300 by the component; consumers MUST NOT force a different footprint",
+    "copy that routinely fills the 300 cap — Tooltip copy is brief and intuitive at a glance; long-form messages belong in a Banner or Dialog"
+  ]
+}