@teamblind-chorus/ui 1.0.0

package/agents/components/banner/banner.spec.json

@@ -0,0 +1,136 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Banner",
+  "family": "banner",
+  "exportAlias": "Alert",
+  "description": "In-body explanation block — a tinted, self-contained card that sits within the reading flow but visually separates from it, used to teach a feature, surface a capability, or annotate content with a short paragraph and an optional follow-through link. Reach for Banner when a passage of body copy needs a brief aside that the reader can scan or skip, not when the message requires a decision (use Dialog or Bottom Sheet) or carries a transient confirmation weight (use Toast).",
+  "element": "div",
+  "props": {
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "default",
+        "accent",
+        "destructive"
+      ],
+      "default": "default"
+    },
+    "icon": {
+      "type": "node",
+      "optional": true,
+      "description": "A 16 × 16 (`sys.icon.md`) glyph at the container's leading edge. Inherits the banner's foreground (`currentColor`) so the mark reads as part of the body copy. The slot occupies the body.sm line-box height so the glyph centers on the **first line** of the body — multi-line bodies keep the icon anchored to the first-line cap, not the block center. Ignored when `thumbnail` is also passed."
+    },
+    "thumbnail": {
+      "type": "node",
+      "optional": true,
+      "description": "A leading visual rendered by [Thumbnail](../thumbnail/thumbnail.md) — used when the aside is anchored to a channel, author, or sub-brand image rather than to a glyph. Takes precedence over `icon`."
+    },
+    "action": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, href? , onClick? } — a follow-through link rendered as a block child below the body."
+    },
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "Body text — the explanation copy."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "The tinted block. Horizontal flex with align-items: flex-start so the optional leading icon top-aligns. role='note'.",
+      "intrinsic": true
+    },
+    "icon": {
+      "required": false,
+      "description": "16 × 16 (`sys.icon.md`) glyph slot. Paints in `currentColor` so the icon inherits the banner's foreground. Slot height equals the body.sm line box, centring the glyph on the body's first line.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "thumbnail": {
+      "required": false,
+      "description": "Leading slot that hosts a `Thumbnail` (channel / author / sub-brand image). Footprint and corner shape come from Thumbnail; the slot only top-aligns and prevents shrink.",
+      "accepts": [
+        "thumbnail"
+      ]
+    },
+    "content": {
+      "required": true,
+      "description": "Vertical column holding body and (optional) action. flex: 1 1 auto.",
+      "intrinsic": true
+    },
+    "body": {
+      "required": true,
+      "description": "Explanation copy. body.sm / Regular / inherits container's foreground. Single paragraph; wraps freely.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "action": {
+      "required": false,
+      "description": "Follow-through link below the body. label.md / Semibold / underlined.",
+      "accepts": [
+        "button"
+      ]
+    }
+  },
+  "sizing": {
+    "radius": "sys.radius.md",
+    "padding": "sys.layout.container.sm",
+    "slotGap": "sys.layout.stack.xs",
+    "iconSize": "sys.icon.md",
+    "iconSlotHeight": "calc(sys.typo.body.sm.size * sys.typo.body.sm.line)",
+    "iconColor": "currentColor",
+    "contentStackGap": "sys.layout.stack.xs",
+    "bodyTypo": "sys.typo.body.sm",
+    "actionTypo": "sys.typo.label.md"
+  },
+  "safeZone": {
+    "inline": {
+      "token": "sys.layout.container.md",
+      "value": "ref.space.200",
+      "paidBy": "host",
+      "note": "Banner is an `inline` card with no outer margin — the host owns the horizontal inset. At the page-shell level the inset is the shell's `layout.page.md` gutter (16); inside Section / Feed / BottomSheet content / SideSheet column the host's container padding governs the inset. Do not paint per-child horizontal margin on Banner."
+    },
+    "block": {
+      "token": "sys.layout.stack.xs",
+      "value": "ref.space.100",
+      "paidBy": "parent-gap",
+      "note": "Vertical 8 between Banner and its siblings is paid by the parent column as `gap: var(--sys-layout-stack-xs)`. Banner itself owns no outer margin. Do not wrap in Section to 'get spacing', do not paint `padding-block` on a wrapper, do not paint `margin-block` on Banner."
+    }
+  },
+  "appearances": {
+    "default": {
+      "background": "sys.color.scrimSubtle",
+      "foreground": "sys.color.onSurface",
+      "actionColor": "sys.color.primary",
+      "note": "Body sits in `onSurface`; the action link steps to primary so it carries the only chromatic emphasis. Background is the translucent inverse-tone scrim (`sys.color.scrimSubtle` — ~8% black light / ~8% white dark) so the banner stays harmonious on any underlying surface — body, raised card, BottomSheet, Dialog — by tinting one step darker (light mode) or lighter (dark mode) instead of pinning to a fixed neutral step that can collide with the surface ladder. Same scrim used by Chip / Tag default, Progress track, StatusTag neutral, and Skeleton."
+    },
+    "accent": {
+      "background": "sys.color.primaryContainer",
+      "foreground": "sys.color.onPrimaryContainer",
+      "actionColor": "inherit",
+      "note": "Both body and action paint in the primary family so the whole banner reads as one highlighted block. Reach for `accent` when the aside should pull more attention — feature explainers, capability nudges."
+    },
+    "destructive": {
+      "background": "sys.color.errorContainer",
+      "foreground": "sys.color.onErrorContainer",
+      "actionColor": "inherit",
+      "note": "Body and action paint in the error family so the whole banner reads as one warning block. Reach for `destructive` when the aside is a blocking error or rejection — failed approvals, integration outages, billing problems. Use sparingly — every destructive banner on a screen competes with the others for the user's alarm budget."
+    }
+  },
+  "behavior": {
+    "actionLink": "When present, renders as an <a> and accepts either href (browser navigation) or onClick (consumer-controlled). Underline persists at rest so the link reads as actionable inside the muted block.",
+    "role": "Container carries role='note' so screen readers announce the banner as an aside."
+  },
+  "forbidden": [
+    "default banner background painted with sys.color.brandContainer — informational banners use sys.color.primaryContainer; promotional banners use sys.color.surfaceContainerLow",
+    "banner thumbnail slot omitted when banner role carries imagery — empty image area is forbidden, fall back to /placeholder.png",
+    "banner used for transient confirmations — that role is the `toast` family (locked)",
+    "banner CTA rendered as raw <a> / <button> — use button/text inside the action slot",
+    "banner wrapped in Section, padding-block div, or per-child margin-block — vertical 8 (sys.layout.stack.xs) safe zone is paid once by the parent's `gap`, never per child",
+    "banner painted with per-child horizontal margin / padding-inline wrapper to fake a safe zone — the horizontal inset is the host's responsibility (page-shell gutter at the top level, container padding inside a host); Banner ships none and does not claim the page rail"
+  ]
+}

package/agents/components/bottom-sheet/bottom-sheet.family.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "bottom-sheet",
+  "name": "BottomSheet",
+  "description": "Modal surface anchored to the bottom of the viewport, used for a focused commit (an action menu, a confirmation, a short form) that should not navigate the user away from the underlying screen. Single-spec family.",
+  "useCases": [
+    "short focused commit",
+    "edge-anchored interruption",
+    "action menu",
+    "confirmation prompt",
+    "one-thumb reach decision"
+  ],
+  "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": "bottom-sheet.md",
+  "usage": {
+    "note": "Controlled via `open` + `onClose`; actions are objects (`primaryAction`/`secondaryAction`), not children.",
+    "example": "<BottomSheet open onClose={close} title=\"…\" body=\"…\" primaryAction={{ label, onClick }} secondaryAction={{ label, onClick }} />"
+  },
+  "subcomponents": [
+    {
+      "slug": "bottom-sheet",
+      "spec": "bottom-sheet.spec.json",
+      "md": "bottom-sheet.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/bottom-sheet/bottom-sheet.md

@@ -0,0 +1,176 @@
+# Bottom sheet
+
+An edge-anchored interruption — a panel that rises from the bottom of the viewport, sits over a scrim, and holds richer content than a Dialog can.
+
+**Reach for this when** you want to steer the user toward a preferred action *without severing the flow* — present enough to focus attention, light enough that dismissing returns them where they were. **Skip when** the decision must be committed before the flow can continue (use [Dialog](../dialog/dialog.md)).
+
+**Layout inset.** bounded-surface — its own modal / popover shell. Owns its outer padding; not a sibling of `full-bleed` page rows. A `full-bleed` child placed inside (List / Feed / AvatarRail / Chip group / Tabs rail) MUST opt out via `marginInline: 'calc(-1 * var(--sys-layout-container-md))'` (matching `width`, `maxWidth: 'none'`) so its row padding becomes the visual inset and the sheet title aligns with row leading content — precedent in `bottom-sheet/overflow` and `bottom-sheet/nested-step`. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+An information-style sheet — title, body paragraph, and a stacked primary / secondary action pair.
+
+```preview
+bottom-sheet/default
+---
+import { useState } from 'react';
+import { BottomSheet, Button } from '@teamblind-chorus/ui';
+
+const [open, setOpen] = useState(false);
+
+<>
+  <Button appearance="primary" onClick={() => setOpen(true)}>Open sheet</Button>
+  <BottomSheet
+    open={open}
+    onClose={() => setOpen(false)}
+    title="Channel settings"
+    body="Manage how this channel shows up in your feed and who can reach you here."
+    primaryAction={{ label: 'Done', onClick: () => setOpen(false) }}
+    secondaryAction={{ label: 'Cancel', onClick: () => setOpen(false) }}
+  />
+</>
+```
+
+## Use cases
+
+### Overflow
+
+When content exceeds the card's `max-height`, the content slot scrolls internally — handle and actions stay pinned, footer gains its `is-elevated` upward shadow.
+
+```preview
+bottom-sheet/overflow
+---
+import { useState } from 'react';
+import { BottomSheet, Button, List } from '@teamblind-chorus/ui';
+
+const [open, setOpen] = useState(false);
+
+<>
+  <Button appearance="primary" onClick={() => setOpen(true)}>Open sheet</Button>
+  <BottomSheet
+    open={open}
+    onClose={() => setOpen(false)}
+    title="Channels you follow"
+    body="Tap a channel to manage notifications, members, and pinned posts."
+    primaryAction={{ label: 'Done', onClick: () => setOpen(false) }}
+    secondaryAction={{ label: 'Cancel', onClick: () => setOpen(false) }}
+  >
+    <List items={/* many rows, each with nav: true */} />
+  </BottomSheet>
+</>
+```
+
+### Keyboard
+
+When the sheet hosts an input that summons the virtual keyboard, the card lifts above the keyboard's top edge so the actions footer stays reachable. Handle and footer pinned; content scrolls to keep the focused input in view.
+
+```preview
+bottom-sheet/keyboard
+---
+import { useState } from 'react';
+import { BottomSheet, Button, FormField } from '@teamblind-chorus/ui';
+
+const [open, setOpen] = useState(false);
+
+<>
+  <Button appearance="primary" onClick={() => setOpen(true)}>Open sheet</Button>
+  <BottomSheet
+    open={open}
+    onClose={() => setOpen(false)}
+    title="Name this channel"
+    primaryAction={{ label: 'Create', onClick: () => setOpen(false) }}
+    secondaryAction={{ label: 'Cancel', onClick: () => setOpen(false) }}
+  >
+    <FormField variant="input" label="Channel name" placeholder="e.g. design-systems" autoFocus />
+  </BottomSheet>
+</>
+```
+
+### Nested step
+
+The sheet can host a **drill-in step** without spawning a second modal. The consumer swaps title, content, and primary action between renders; passing `onBack` paints a leading back chevron — an Icon Button rendering `ChevronLeftIcon` at `sys.icon.lg` (24), with `sys.layout.inline.md` (8) between glyph and title. Card chrome, scrim, drag handle, and actions footer stay identical across steps.
+
+```preview
+bottom-sheet/nested-step
+---
+import { useState } from 'react';
+import { BottomSheet, Button, FormField, List } from '@teamblind-chorus/ui';
+
+const [open, setOpen] = useState(false);
+const [step, setStep] = useState('root');
+const [value, setValue] = useState('');
+
+<>
+  <Button appearance="primary" onClick={() => { setStep('root'); setOpen(true); }}>Open sheet</Button>
+  <BottomSheet
+    open={open}
+    onClose={() => setOpen(false)}
+    title={step === 'root' ? 'Yearly Equity Value' : 'RSUs'}
+    onBack={step === 'rsus' ? () => setStep('root') : undefined}
+    primaryAction={{ label: 'Save', onClick: () => setOpen(false) }}
+  >
+    {step === 'root' ? (
+      <List
+        variant="radio"
+        items={[
+          { id: 'rsus', label: 'RSUs', onClick: () => setStep('rsus') },
+          { id: 'none', label: 'None' },
+        ]}
+      />
+    ) : (
+      <FormField
+        variant="input"
+        leadingIcon="$"
+        placeholder="Ex: 100,000"
+        value={value}
+        onChange={setValue}
+        autoFocus
+      />
+    )}
+  </BottomSheet>
+</>
+```
+
+## Slots
+
+- **scrim** — translucent black overlay; dims the host. Clicking fires `onClose`. Aligns the card to the bottom edge.
+- **container** — the sheet card. `surfaceContainerHigh` fill, `radius.xl` top corners (bottom flat), `elevation.sheet` shadow, `max-width: 480px`.
+- **drag handle** — small grey pill centred at the top; decorative dismissal cue.
+- **content** — scrollable region holding title, body, and custom children. Title: `heading.lg` / Semibold / `onSurface`. Body: `body.md` / Regular / `onSurfaceVariant`.
+- **back** *(optional)* — leading back chevron, rendered only when `onBack` is wired. Delegates to [Button](../button/icon.md) `variant="icon"` with `ChevronLeftIcon` at `sys.icon.lg` and `sys.layout.inline.md` between glyph and title.
+- **actions** — pinned footer holding the action stack. Primary on top, secondary below; both stretch to the inner width. Primary = `Button appearance="primary"`; secondary = `Button appearance="secondary"`.
+
+## Anatomy
+
+| Slot         | Token bindings |
+|--------------|----------------|
+| scrim        | Fixed full-viewport overlay, `palette.black.600` (~24% alpha), aligns card to bottom |
+| container    | `surfaceContainerHigh` fill, `radius.xl` top corners (bottom flat), `elevation.sheet`, `max-width: 480px`, `max-height: 90vh` |
+| drag handle  | 48 × 4px pill, `onSurfaceVariant @ 40%`, `sys.radius.full`, 8px vertical gutter |
+| content      | Flex column, 16px padding, 16px between children, vertical scroll on overflow |
+| title        | `sys.typo.heading.lg` (24 / Semibold), `onSurface` |
+| back chevron | [Icon Button](../button/icon.md) → `ChevronLeftIcon` at `sys.icon.lg` (24), `sys.color.onSurface`. Glyph aligns to the title's leading edge via Icon Button optical-alignment. `sys.layout.inline.md` (8) glyph → title gap. |
+| body         | `sys.typo.body.md` (16 / Regular), `onSurfaceVariant` |
+| actions      | Flex column, 8px between buttons, 16px padding on all four sides |
+| primary CTA  | [Button](../button/button.md) `appearance="primary"`, `size="large"`, `fullWidth` |
+| secondary    | [Button](../button/button.md) `appearance="secondary"`, `size="large"`, `fullWidth` |
+
+## States
+
+Either **open** or **closed** — closed renders nothing. When open, scrim and card both render; the underlying surface is non-interactive. The container itself carries no interactive state — interaction lives in the action buttons.
+
+## Focus indicator
+
+Sheet itself isn't a focus target; primary and secondary slots inherit [Button → Outward](../button/button.md#focus-indicator) focus composition. On open, focus moves to the primary action. Trigger: `:focus-visible`.
+
+## Behavior
+
+- **Scrim click closes.** Tapping the scrim fires `onClose`; card stops propagation.
+- **Escape key closes.** `Esc` fires `onClose`.
+- **Focus management.** On open, focus moves to the primary action; returns to the previously-focused element on close.
+- **Body scroll lock.** The page underneath does not scroll while open.
+- **Overflow scrolling.** When content exceeds `max-height`, the content slot scrolls internally; handle and actions stay pinned. Flex column — handle and actions `flex: 0 0 auto`, content `flex: 1 1 auto` with `overflow-y: auto`.
+- **Elevated actions footer.** While content is overflowing, footer gains an upward drop shadow (`0 -2px 6px black/4%, 0 -8px 16px black/8%`) so it reads as pinned above the scrolling content.
+- **Keyboard handling.** When a hosted input opens the virtual keyboard, the scrim absorbs the keyboard height as `padding-bottom` via `--bottom-sheet-keyboard-inset`, translating the card up so the actions footer rides above the keyboard's top edge. Read at runtime from `window.innerHeight - visualViewport.height` on `visualViewport.resize`; resets to `0px` on dismissal.
+- **Portal rendering.** Renders into a portal at `document.body` by default. Pass `inline` to scope to the nearest positioned ancestor.
+- **Nested step.** Passing `onBack` paints the leading back chevron; the component is stateless about which step is active. The consumer owns the step (e.g. `useState`) and swaps `title` / `children` / `primaryAction` / `onBack` between renders. Card chrome, scrim, handle, and actions footer remain identical across steps.

package/agents/components/bottom-sheet/bottom-sheet.spec.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "BottomSheet",
+  "family": "bottom-sheet",
+  "exportAlias": ["Sheet", "Drawer"],
+  "description": "Edge-anchored interruption — a panel that rises from the bottom of the viewport, sits over a scrim, and holds richer content than a Dialog: longer copy, tabular comparisons, multi-section explanations, or a primary commit at the foot. Reach for Bottom Sheet when the answer needs more vertical room than a centred card affords but the surface is still a single decision the user can dismiss to return to the host.",
+  "element": "div",
+  "props": {
+    "open": {
+      "type": "boolean",
+      "required": true
+    },
+    "onClose": {
+      "type": "function",
+      "required": true
+    },
+    "title": {
+      "type": "node",
+      "optional": true
+    },
+    "body": {
+      "type": "node",
+      "optional": true
+    },
+    "primaryAction": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, onClick } — delegates to Button appearance='primary', size='large', fullWidth."
+    },
+    "secondaryAction": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, onClick } — delegates to Button appearance='secondary', size='large', fullWidth."
+    },
+    "onBack": {
+      "type": "function",
+      "optional": true,
+      "description": "When supplied, the sheet is a nested step inside its host flow — a back chevron (Icon Button → ChevronLeftIcon, sys.icon.lg, sys.layout.inline.md gap to the title) is rendered at the title's leading edge and invokes onBack on click. Consumer owns step state; the component only paints the chevron."
+    },
+    "backLabel": {
+      "type": "string",
+      "default": "Back",
+      "description": "Accessible name on the back Icon Button. Only consulted when onBack is set."
+    },
+    "children": {
+      "type": "node",
+      "optional": true
+    },
+    "inline": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, scopes the scrim and card to the nearest positioned ancestor instead of portaling to document.body."
+    }
+  },
+  "slots": {
+    "scrim": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Translucent black overlay covering the host surface; aligns the card to the bottom edge. Clicking fires onClose."
+    },
+    "container": {
+      "required": true,
+      "intrinsic": true,
+      "description": "The sheet card. surfaceContainerHigh fill, top radius.xl, bottom corners flat (edge-anchored rule), elevation.sheet shadow, max-width 480px, max-height 90vh."
+    },
+    "dragHandle": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Small grey pill centred at the top of the card. Decorative — interaction lives in scrim click + Esc key."
+    },
+    "content": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Scrollable region holding title, body, and any custom children. The component composes this from `title` + `body` + `actions` + any children — consumers do not provide a separate `content` node."
+    },
+    "title": {
+      "required": false,
+      "description": "heading.lg / Semibold / onSurface.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "back": {
+      "required": false,
+      "description": "Optional leading back chevron, rendered only when the host wires `onBack`. Delegates to Button variant='icon' with ChevronLeftIcon at sys.icon.lg and an 8px (sys.layout.inline.md) gap to the title. Icon Button's optical-alignment default places the glyph at the title's leading edge so the row stays flush with the content padding.",
+      "accepts": [
+        "button"
+      ]
+    },
+    "body": {
+      "required": false,
+      "description": "body.md / Regular / onSurfaceVariant.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "actions": {
+      "required": false,
+      "description": "Pinned footer holding the action stack. Primary on top, secondary below. Both stretch to the card's inner width.",
+      "accepts": [
+        "button"
+      ]
+    }
+  },
+  "sizing": {
+    "scrimTint": "ref.palette.black.600",
+    "containerFill": "sys.color.surfaceContainerHigh",
+    "containerRadiusTop": "sys.radius.xl",
+    "containerRadiusBottom": "0",
+    "elevation": "sys.elevation.sheet",
+    "maxWidth": "480px",
+    "maxHeight": "90vh",
+    "dragHandleSize": "48 × 4px",
+    "dragHandleFill": "sys.color.onSurfaceVariant @ 40%",
+    "dragHandleRadius": "sys.radius.full",
+    "dragHandleGutter": "sys.layout.container.xs",
+    "contentPadding": "sys.layout.container.md",
+    "contentStackGap": "sys.layout.stack.md",
+    "actionsStackGap": "sys.layout.stack.xs",
+    "actionsPadding": "sys.layout.container.md",
+    "titleTypo": "sys.typo.heading.lg",
+    "titleColor": "sys.color.onSurface",
+    "backIcon": "ChevronLeftIcon",
+    "backIconSize": "sys.icon.lg",
+    "backIconColor": "sys.color.onSurface",
+    "backToTitleGap": "sys.layout.inline.md",
+    "bodyTypo": "sys.typo.body.md",
+    "bodyColor": "sys.color.onSurfaceVariant"
+  },
+  "states": {
+    "open": {
+      "description": "Scrim + card both render; underlying surface remains in DOM but is non-interactive."
+    },
+    "closed": {
+      "description": "Renders nothing."
+    }
+  },
+  "focusIndicator": {
+    "description": "The sheet itself isn't a focus target. Its action slots (primary / secondary Buttons) inherit Button's outward focus composition; on open, focus is moved to the primary action. See the contained sub-components for the visual contract.",
+    "composition": "delegated",
+    "delegatesTo": "../button/standard.spec.json#/focusIndicator",
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "scrimClickCloses": true,
+    "escapeKeyCloses": true,
+    "focusManagement": "On open, focus moves into the sheet and is trapped there (see accessibility.focusTrap) — for a standard sheet onto the primary action so Enter commits, for a destructive confirmation onto the least-destructive action. Focus returns to the previously-focused element on close.",
+    "bodyScrollLock": true,
+    "overflow": "When content exceeds max-height, the content slot scrolls internally while drag handle and actions footer stay pinned. Card is a flex column; handle and actions are flex: 0 0 auto; content is flex: 1 1 auto with overflow-y: auto.",
+    "elevatedActionsFooter": "While content overflows, the actions footer carries a subtle upward drop shadow (0 -2px 6px black/4%, 0 -8px 16px black/8%) over its surfaceContainerHigh fill so it reads as pinned above the scrolling content. The shadow fades when content fits without scroll.",
+    "keyboardInset": "When a hosted input opens the virtual keyboard, the scrim absorbs the keyboard height as padding-bottom via the CSS custom property --bottom-sheet-keyboard-inset. Because the scrim aligns the card with align-items: flex-end, the inset pushes the entire card (and therefore the pinned actions footer) above the keyboard's top edge. Read at runtime from window.innerHeight - visualViewport.height on visualViewport.resize; reset to 0px when the keyboard dismisses.",
+    "portalRendering": "By default renders into a portal at document.body. Pass inline to scope to the nearest positioned ancestor.",
+    "nestedStep": "A sheet can host a drill-in step inside itself — when the consumer supplies `onBack`, a ChevronLeftIcon Button paints at the title's leading edge with `sys.layout.inline.md` between glyph and title. The component itself is stateless about which step is active: the consumer swaps `title` / `children` / `primaryAction` / `onBack` between renders. The card, scrim, handle, and actions footer remain identical across steps so the transition reads as a same-surface drill-in, not a new modal."
+  },
+  "accessibility": {
+    "role": "container carries role='dialog' (role='alertdialog' for a destructive / irreversible confirmation) — same blocking modal contract as Dialog, anchored to the bottom edge.",
+    "ariaModal": "aria-modal='true' on the container — content behind the scrim is inert to assistive tech, mirroring the scrim's pointer-event block.",
+    "labelling": "aria-labelledby points at the title slot's id when a title is rendered. When the sheet is title-less, the consumer MUST supply an aria-label so the modal is never announced unnamed.",
+    "focusTrap": "While open, Tab / Shift+Tab cycle only through the sheet's focusable descendants and wrap at the ends — focus never reaches the inert page behind the scrim. Required by the APG dialog-modal pattern.",
+    "dragHandle": "The drag handle is decorative (dismiss is scrim-tap + Esc, there is no swipe gesture) — it carries aria-hidden='true' and is not a focus target, so it never implies an unavailable drag affordance to assistive tech."
+  },
+  "forbidden": [
+    "BottomSheet without a scrim — same blocking contract as dialog",
+    "BottomSheet without a paired triggering action",
+    "BottomSheet content rendered with extra horizontal-padding wrappers — sheet body uses container.lg internally; full-bleed children opt out via negative margin per DESIGN.md",
+    "Multiple bottom-sheets stacked"
+  ]
+}

package/agents/components/bubble/bubble.family.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "bubble",
+  "name": "Bubble",
+  "description": "Always-on annotation bubble — a small pill-shaped label with a tail that points at a specific UI element to flag attention (a chat icon with new messages, a search bar with a fresh keyword promotion, a tab with a campaign). Distinct from Tooltip on visual-priority and persistence: Tooltip is a *transient, high-priority* explanation that can overlay surrounding chrome on hover/focus; Bubble is *persistent, lower-priority* annotation that sits inline next to its anchor and never occludes neighbour elements. Reach for Bubble when a hint should remain in view as part of the UI's resting state (an editorial nudge, a feature-flag callout, a count summary tied to an icon); reach for Tooltip when the hint is an on-demand explanation invoked by interaction. Single-spec family.",
+  "useCases": [
+    "always-on label next to a top-bar icon",
+    "feature-flag / new-feature nudge anchored to a UI element",
+    "editorial copy promoted next to a search bar",
+    "count or status summary that needs more presence than a Badge dot",
+    "campaign / event flag that should read at rest, not on hover"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "wrapperGuidance": "Inline atom — Bubble owns its own padding, fill, tail, and a viewport-safe width cap (`max-width: min(100%, calc(100vw - 2 × sys.layout.container.xs))`), but ships no positioning. The host anchors the bubble to the target element by VISUAL ALIGNMENT — CSS anchor positioning (`anchor-name` on the target, `position-anchor` + `top: anchor(bottom)` + `left: anchor(center)` + `translateX(-50%)` on the bubble) or a positioned wrapper around the anchor — rather than hand-computed pixel offsets, and owns four coupled decisions: (a) keep every bubble edge ≥8 (`sys.layout.container.xs`) from the viewport edge — visibility of the bubble is the contract; (b) **tail tip flush on the anchor's content edge** (padding excluded) — set the bubble body back from the anchor by the tail's protrusion (the `--bubble-tail-protrusion` token, = `ref.space.50 / √2`) so the tail's outer vertex meets the anchor edge without overlapping it; (c) **tail tip on the anchor's centreX** — centre the bubble on the anchor's visual centre so the tail tip falls on the anchor's horizontal centreline by construction; (d) pick `tailSide` (`top` if the bubble sits below the anchor, `bottom` if above) and keep `tailAlign='center'` for that centred case, flipping to `end` (bubble shifts left) or `start` (bubble shifts right) only when the viewport safe margin forces the bubble off-centre. Do NOT wrap Bubble in a portal / fixed-position scrim — that would defeat the 'never occludes neighbours' contract that separates Bubble from Tooltip. Do NOT wrap Bubble in an `overflow: hidden` ancestor that clips it — fix the ancestor, not the bubble. Inside a bounded surface (Dialog / BottomSheet / SideSheet), apply the negative-margin opt-out only when the bubble needs to escape the host's content box.",
+  "spec": "bubble.md",
+  "usage": {
+    "note": "Label is children; ships no positioning — the host anchors it. `tailSide`/`tailAlign` pick the tail; there is no separate tail element.",
+    "example": "<Bubble tailSide=\"top\" tailAlign=\"center\">…</Bubble>"
+  },
+  "subcomponents": [
+    {
+      "slug": "bubble",
+      "spec": "bubble.spec.json",
+      "md": "bubble.md",
+      "default": true
+    }
+  ]
+}