@teamblind-chorus/ui 1.0.0

package/agents/components/dialog/dialog.md

@@ -0,0 +1,113 @@
+# Dialog
+
+A focused, opt-in interruption — a centred card over a scrim that holds the flow until the user makes a single decision.
+
+**Reach for this when** the flow must pause for a definitive response — destructive actions, conflicts, consent gates, "Are you sure?". **Skip when** the same nudge can be delivered without halting the flow (use [Bottom sheet](../bottom-sheet/bottom-sheet.md)), the message is contextual to underlying content ([Banner](../banner/banner.md)), or the confirmation is post-action ([Toast](../toast/toast.md)).
+
+**Layout inset.** `bounded-surface` — its own modal shell. Owns its outer padding; not a sibling of `full-bleed` page rows. A `full-bleed` child placed inside (List / Feed / Chip group) MUST opt out via `marginInline: 'calc(-1 * var(--sys-layout-container-md))'` (matching `width`, `maxWidth: 'none'`) so its own row padding becomes the visual inset and the dialog title aligns with row leading content. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+A confirmation-style dialog with title, body, and stacked primary / tertiary actions. No image, so the text left-aligns.
+
+```preview
+dialog/default
+---
+import { useState } from 'react';
+import { Dialog, Button } from '@teamblind-chorus/ui';
+
+const [open, setOpen] = useState(false);
+
+<>
+  <Button appearance="primary" onClick={() => setOpen(true)}>Open dialog</Button>
+  <Dialog
+    open={open}
+    onClose={() => setOpen(false)}
+    title="Pick your major and get tailored job recommendations"
+    body="We'll surface the companies and roles your seniors applied to most often, first."
+    primaryAction={{ label: 'Pick major', onClick: () => setOpen(false) }}
+    secondaryAction={{ label: 'Later', onClick: () => setOpen(false) }}
+  />
+</>
+```
+
+## Use cases
+
+### With image
+
+Pass an `image` to add a centred illustration between title and actions. With the image present, the whole stack centre-aligns. `imageFirst` (default `true`) controls whether the image sits under the title or the body.
+
+```preview
+dialog/with-image
+---
+import { useState } from 'react';
+import { Dialog, Button } from '@teamblind-chorus/ui';
+
+const [open, setOpen] = useState(false);
+
+<>
+  <Button appearance="primary" onClick={() => setOpen(true)}>Open dialog</Button>
+  <Dialog
+    open={open}
+    onClose={() => setOpen(false)}
+    title="You earned the Sourdough Starter badge"
+    body="Three open-crumb bakes shared this week — your channel just lit up."
+    image={{ src: '/badge.png', alt: 'Sourdough Starter badge' }}
+    primaryAction={{ label: 'Share to channel', onClick: () => setOpen(false) }}
+    secondaryAction={{ label: 'Not now', onClick: () => setOpen(false) }}
+  />
+</>
+```
+
+## Slots
+
+- **scrim** — translucent black overlay; clicking fires `onClose`. Holds the card to a 40px inset from the wrapper's left and right edges.
+- **container** — dialog card. `surfaceContainerHigh` fill, `radius.xl`, `elevation.overlay`. Caps at `max-width: 480px`. Vertical stack: title, (optional) image, body, actions.
+- **title** — short headline. `heading.sm` / Semibold / `onSurface`. Always sits at the top.
+- **image** *(optional)* — illustrative image between title and actions. Spans the inner width; preserves intrinsic aspect ratio.
+- **body** *(optional)* — one-paragraph supporting copy. `body.sm` / Regular / `onSurfaceVariant`.
+- **actions** — vertical stack at the bottom; primary on top, secondary below. Both stretch full inner width. Primary = `appearance="primary"`; secondary = `appearance="tertiary"`.
+
+## Anatomy
+
+| Slot         | Token bindings |
+|--------------|----------------|
+| scrim        | Fixed full-viewport overlay, `palette.black.600` (~24% alpha), centres container, fixed 40px inline padding |
+| container    | `surfaceContainerHigh` fill, `radius.xl` (16px), `elevation.overlay`, `sys.layout.container.lg` padding, `max-width: 480px` |
+| title        | `sys.typo.heading.sm` (16 / Semibold), `onSurface` |
+| image        | `width: 100%`, `height: auto`, `radius.lg` corners, 16px above and below |
+| body         | `sys.typo.body.sm` (14 / Regular), `onSurfaceVariant`, 16px above |
+| actions      | Flex column, 8px between buttons, 16px above the stack |
+| primary CTA  | [Button](../button/button.md) `appearance="primary"`, `size="large"`, `fullWidth` |
+| secondary    | [Button](../button/button.md) `appearance="tertiary"`, `size="large"`, `fullWidth` |
+
+**Inter-slot rhythm.** Every gap between adjacent card children is `sys.layout.stack.md` (16px).
+
+## Alignment
+
+- **With image** — title, body, and stack centre-align (`text-align: center`, `align-items: center`).
+- **Text only** — title and body left-align (`text-align: start`, `align-items: stretch`).
+
+Actions row is always stretched to the inner width.
+
+## Sizes
+
+A single rung. Card holds a fixed `max-width: 480px` and 40px gutter; below that breakpoint it fills available width.
+
+## States
+
+Dialog is either **open** or **closed** — closed renders nothing. When open, the underlying surface is non-interactive behind the scrim.
+
+The container itself has no interactive state — interaction lives in the action buttons.
+
+## Focus indicator
+
+Dialog itself isn't a focus target; action 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.** Card stops propagation.
+- **Escape key closes.** Bound at the document level.
+- **Focus management.** On open, focus moves to the primary action; returns to the previously-focused element on close.
+- **Body scroll lock.** Page underneath does not scroll while the dialog is open.
+- **Portal rendering.** Renders into a portal at `document.body` by default. Pass `inline` to scope to the nearest positioned ancestor (must declare `position: relative` and `overflow: hidden`).

package/agents/components/dialog/dialog.spec.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Dialog",
+  "family": "dialog",
+  "description": "Focused, opt-in interruption — a centred card over a scrim that asks the user to make a single decision before continuing. Reach for Dialog when the surface needs an explicit commit / dismiss pair (onboarding nudge, confirm-before-destructive) and the answer can fit in a short title + one supporting paragraph. Anything longer than two action buttons or a paragraph of supporting copy belongs in a full screen or sheet, not a dialog.",
+  "element": "div",
+  "props": {
+    "open": {
+      "type": "boolean",
+      "required": true
+    },
+    "onClose": {
+      "type": "function",
+      "required": true
+    },
+    "title": {
+      "type": "node",
+      "required": true
+    },
+    "body": {
+      "type": "node",
+      "optional": true
+    },
+    "image": {
+      "type": "object",
+      "optional": true,
+      "description": "{ src, alt } — illustrative image between the title and the actions."
+    },
+    "imageFirst": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true (default), the image sits directly under the title; when false, under the body."
+    },
+    "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='tertiary', size='large', fullWidth."
+    },
+    "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,
+      "description": "Translucent black overlay covering the host surface; centres the container with flex. Clicking fires onClose. Holds the card to a 40px inset from the wrapper's left and right edges.",
+      "intrinsic": true
+    },
+    "container": {
+      "required": true,
+      "description": "The dialog card. surfaceContainerHigh fill, radius.xl, elevation.overlay. Fills the available width up to max-width: 480px.",
+      "intrinsic": true
+    },
+    "title": {
+      "required": true,
+      "description": "Short headline. heading.sm / Semibold / onSurface. Always sits at the top of the stack.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "image": {
+      "required": false,
+      "description": "Single illustrative image between title and actions. Spans the card's inner width and preserves intrinsic aspect ratio.",
+      "accepts": [
+        "image"
+      ]
+    },
+    "body": {
+      "required": false,
+      "description": "One-paragraph supporting copy. body.sm / Regular / onSurfaceVariant.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "actions": {
+      "required": false,
+      "description": "Vertical stack of action buttons at the bottom of the card. Primary on top, secondary below. Both stretch to inner width.",
+      "accepts": [
+        "button"
+      ]
+    }
+  },
+  "sizing": {
+    "scrimTint": "ref.palette.black.600",
+    "scrimPaddingInline": "ref.space.500",
+    "containerFill": "sys.color.surfaceContainerHigh",
+    "containerRadius": "sys.radius.xl",
+    "elevation": "sys.elevation.overlay",
+    "containerPadding": "sys.layout.container.lg",
+    "maxWidth": "480px",
+    "titleTypo": "sys.typo.heading.sm",
+    "titleColor": "sys.color.onSurface",
+    "imageWidth": "100%",
+    "imageHeight": "auto",
+    "imageRadius": "sys.radius.lg",
+    "bodyTypo": "sys.typo.body.sm",
+    "bodyColor": "sys.color.onSurfaceVariant",
+    "interSlotGap": "sys.layout.stack.md",
+    "actionsStackGap": "sys.layout.stack.xs"
+  },
+  "alignment": {
+    "withImage": {
+      "textAlign": "center",
+      "alignItems": "center",
+      "note": "The image's visual mass anchors the composition; centred copy reads as a unified illustrated card."
+    },
+    "textOnly": {
+      "textAlign": "start",
+      "alignItems": "stretch",
+      "note": "Left alignment matches the reading rhythm of the body copy."
+    },
+    "actions": "Always stretched to the card's inner width regardless of alignment."
+  },
+  "states": {
+    "open": {
+      "description": "Scrim + card both render; underlying surface remains in DOM but pointer events suppressed by the scrim's full-viewport overlay."
+    },
+    "closed": {
+      "description": "Renders nothing — no reserved whitespace, no hidden DOM."
+    }
+  },
+  "focusIndicator": {
+    "description": "The dialog 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": "Tapping anywhere on the scrim fires onClose. The card stops click propagation so a tap inside never closes the dialog by accident.",
+    "escapeKeyCloses": "Pressing Esc fires onClose. Bound at the document level so the dialog doesn't need to own focus to receive the key.",
+    "focusManagement": "On open, focus moves into the dialog and is trapped there (see accessibility.focusTrap). For a standard dialog focus lands on the primary action so Enter commits; for a destructive confirmation (role='alertdialog') focus lands on the least-destructive action (the cancel / dismiss control) so the dangerous commit is never one keystroke away. Focus returns to the previously-focused element on close (consumer-managed via onClose).",
+    "bodyScrollLock": true,
+    "portalRendering": "By default renders into a portal at document.body. Pass inline to scope to the nearest positioned ancestor; that ancestor must declare position: relative and overflow: hidden."
+  },
+  "accessibility": {
+    "role": "container carries role='dialog'. For a destructive / irreversible confirmation it is role='alertdialog' instead, so assistive tech announces it as a decision that requires attention.",
+    "ariaModal": "aria-modal='true' on the container — assistive tech treats content outside the dialog as inert while it is open (mirrors the scrim's pointer-event block in the a11y tree).",
+    "labelling": "aria-labelledby points at the title slot's id (always present, title is required). aria-describedby points at the body slot's id when a body is rendered.",
+    "focusTrap": "While open, Tab / Shift+Tab cycle only through the dialog's focusable descendants and wrap at the ends — focus can never reach the inert page behind the scrim. Required by the APG dialog-modal pattern; pairs with the scrim's pointer-event block so keyboard and pointer are gated identically.",
+    "initialFocus": "Standard dialog → primary action. Destructive (alertdialog) → least-destructive action (cancel / dismiss).",
+    "escape": "Esc fires onClose (see behavior.escapeKeyCloses)."
+  },
+  "forbidden": [
+    "Dialog without a scrim — dialog is a page-blocking modal and requires the scrim layer",
+    "Dialog without a paired triggering action — modal opens are always commit-triggered, never auto-on-mount",
+    "Dialog body without a primary action — every dialog has a commit (even informational dialogs carry an Acknowledge / Close action)",
+    "Dialog stacked on top of another dialog — pre-overlay flow is sequential, not stacked"
+  ]
+}

package/agents/components/directory-list/directory-list.family.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "directory-list",
+  "name": "DirectoryList",
+  "description": "Vertical follow-list — labelled block where each row pairs a 48 thumbnail, identity column (name + followers + description), and a trailing Follow toggle. **Preset wrapper** over `<Header /> + <List variant=\"entry\" size=\"large\" divider={false}>` — no new tokens, no new selection model; reach for it when you want the canonical Follow-able directory shape with item-descriptor sugar (`name → label`, `followers → secondary`, `active/onToggle → trailingIcon`). If you need any divergence from that preset (different rung, different trailing affordance, mixed-thumbnail rows, custom divider behavior), drop down to `<Header /> + <List variant=\"entry\" />` and compose freely. Sibling of SuggestionList: same entity-agnostic row anatomy, but no swipeable pager — the full set is scanned vertically.",
+  "useCases": [
+    "follow-able directory of entities",
+    "new / recommended channels (full list)",
+    "people you may know",
+    "browse / explore index"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "Owns its inline padding internally. Place as a direct child of the page-shell <main> (or any host that pays the gutter once). Do NOT wrap in a padding-inline div, className=\"px-*\", or style={{ padding }} — the page rail is paid once at the shell, never on the full-bleed child. Inside a bounded surface (Dialog / BottomSheet / SideSheet), apply the negative-margin opt-out — see AGENTS.md § Composition rules.",
+  "compositionModes": {
+    "standalone": {
+      "default": true,
+      "chrome": {
+        "background": "sys.color.surface",
+        "padding": "sys.layout.container.lg block / sys.layout.container.md inline"
+      },
+      "context": "Direct child of the page shell or any host that pays the page-rail gutter once."
+    },
+    "embedded": {
+      "trigger": "prop `embedded={true}` on <DirectoryList /> OR direct child of `.chorus-carousel` / `.chorus-feed` (DOM-ancestry safety net).",
+      "chrome": {
+        "background": "transparent",
+        "padding": "0"
+      },
+      "context": "Composed inside another rail-responsible host (`<Carousel label=\"New channels\"><DirectoryList embedded /></Carousel>`). Row content takes over from the host's content-box edge."
+    }
+  },
+  "usage": {
+    "note": "Rows are an `items` array of descriptors (name/followers/description/thumbnail/active/onToggle) — there are NO List or row children.",
+    "example": "<DirectoryList label=\"…\" items={[{ value, name, followers, description, thumbnail: { src, alt }, active, onToggle }]} />"
+  },
+  "spec": "directory-list.md",
+  "subcomponents": [
+    {
+      "slug": "directory-list",
+      "spec": "directory-list.spec.json",
+      "md": "directory-list.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/directory-list/directory-list.md

@@ -0,0 +1,87 @@
+# Directory list
+
+A vertical follow-list — labelled block where each row pairs a 48 [Thumbnail](../thumbnail/thumbnail.md), an identity column (name + `secondary` followers + `description`), and a trailing [Toggle Button](../button/toggle.md) flipping between "Follow" and "Following". Anatomy is entity-agnostic — channels, people, companies, topics share one shape.
+
+**Preset wrapper.** Internally this is `<Header /> + <List variant="entry" size="large" divider={false}>`. The wrapper exists to (a) map entity-flavored item keys (`name → label`, `followers → secondary`, `active/onToggle → trailingIcon`) and (b) lock the rung + divider preset for the canonical Follow-able directory shape. There is no new visual grammar — just a pinned set of `List` props plus item-key sugar.
+
+**Reach for `<DirectoryList />` when** you want the canonical Follow-able directory shape verbatim (48 rung, no inter-row divider, Follow Toggle trailing). **Drop down to `<Header /> + <List variant="entry" />` instead when** you need any divergence — different size rung, mixed label-only and thumbnail rows, a different trailing affordance (chevron / icon button / star), per-row dividers, or a non-toggle commit pattern. **Skip when** the surface is a peek of three with horizontal paging (use [SuggestionList](../suggestion-list/suggestion-list.md)) or a label-only category index ([NavList](../nav-list/nav-list.md)).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell (or any host that pays the gutter). Container pays its own `24px block / 16px inline` padding; each row keeps the list/entry native `16px inline padding` for the tap target and pulls its inline margin by `-16` so the visible avatar lines up with the header label at 16 from the surface. Do **not** wrap in another `padding-inline` / `px-*` / `style={{ padding: … }}` div. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Header label only, five follow-able channels at the `large` rung.
+
+```preview
+directory-list/default
+---
+import { DirectoryList } from '@teamblind-chorus/ui';
+
+<DirectoryList
+  label="New channels"
+  items={[
+    { value: 'devsplan',  name: 'Devs Plan',           followers: '2.1K Followers', description: 'Chat about Devs Plan launches and tips.',           thumbnail: { alt: 'Devs Plan' } },
+    { value: 'passnotes', name: 'Pass Notes Together', followers: '1.4K Followers', description: 'Ghosting Blind threads on offers and promo packs.', thumbnail: { alt: 'Pass Notes Together' }, active: true },
+    { value: 'cars',      name: 'Cars',                followers: '8.7K Followers', description: 'Daily-driver picks, trims, and ownership notes.',   thumbnail: { alt: 'Cars' } },
+    { value: 'beauty',    name: 'Beauty Bursts',       followers: '4.2K Followers', description: 'Routines, cushion drops, scent threads.',           thumbnail: { alt: 'Beauty Bursts' } },
+    { value: 'health',    name: 'Health · Diet',       followers: '11.3K Followers', description: 'Programs, macros, and weekday-meal logistics.',     thumbnail: { alt: 'Health · Diet' } },
+  ]}
+/>
+```
+
+## Use cases
+
+### With header action
+
+Extends the header with a trailing `accent` Text Button when the screen has a broader index page to route to.
+
+```preview
+directory-list/with-header-action
+---
+import { DirectoryList } from '@teamblind-chorus/ui';
+
+<DirectoryList
+  label="People you may know"
+  headerAction={{ label: 'See all', href: '/people' }}
+  items={[
+    { value: 'jordan', name: 'Jordan Lee',    followers: '342 Followers',  description: 'PM at a logistics startup. Mostly here for roadmap reviews.',         thumbnail: { alt: 'Jordan Lee' } },
+    { value: 'taylor', name: 'Taylor Brooks', followers: '1.1K Followers', description: 'Frontend engineer. Writes about the bits between framework and user.', thumbnail: { alt: 'Taylor Brooks' }, active: true },
+    { value: 'morgan', name: 'Morgan Park',   followers: '512 Followers',  description: 'Designer-turned-PM. Notes on the handoff layer.',                      thumbnail: { alt: 'Morgan Park' } },
+  ]}
+/>
+```
+
+## Slots
+
+- **container** — `surface` block with 24px block / 16px inline padding. Holds the header above the vertical list.
+- **header** — [Header](../header/header.md) `size="large"`. Section label leading, optional accent Text Button trailing. Anchored above the list.
+- **list** — embedded [List](../list/entry.md) `variant="entry"` `size="large"`. The inter-row hairline divider is suppressed (`divider={false}`); rows tile against the surface fill.
+- **row** — entity entry rendered as a [list/entry](../list/entry.md) row at the `large` rung (48 Thumbnail). Each item descriptor (`name` / `followers` / `description` / `thumbnail` / `active` / `onToggle`) maps to the entry contract (`label` / `secondary` / `description` / `thumbnail` / `trailingIcon`). The row body is presentational — tapping does not route.
+- **trailingAction** — [Toggle Button](../button/toggle.md), `variant="toggle"` — composed into the row's `trailingIcon` slot.
+
+## Anatomy
+
+| Slot           | Token bindings |
+|----------------|----------------|
+| container      | `surface` fill, 24px block / 16px inline padding, vertical stack |
+| header         | [Header](../header/header.md) `size="large"`. Container stack (`sys.layout.stack.md` = 16px) separates from list. |
+| label          | `heading.md` / Semibold / `onSurface` |
+| headerAction   | `xsmall` [Text Button](../button/text.md), `accent` appearance |
+| list           | [List](../list/entry.md) `variant="entry"` `size="large"`. `embedded` (wrapper section owns the rail). `divider={false}` (rows tile without an inter-row hairline). |
+| row            | [list/entry](../list/entry.md)-shaped row at `large` rung — 48 avatar, `inline.lg` gap, label.md primary / label.sm `secondary` + `description`. Keeps the list/entry native `container.md` inline padding and adds `margin-inline: -container.md` so the avatar lines up at the section rail (16 from the surface). The inter-row hairline divider is suppressed — rows tile against the surface fill with `stack.sm` (12) breathing room from the row's intrinsic block padding. |
+| trailingAction | [Toggle Button](../button/toggle.md), `variant="toggle"` — composed into the row's `trailingIcon` slot. |
+
+## States
+
+Container has no interactive state. Each row's only interactive surface is its **trailingAction** — a Toggle Button obeying the [Toggle Button](../button/toggle.md) state contract. Row body is presentational; tapping the row does not route. The **headerAction** is an `xsmall` Text Button (rendered as `<a>` when `href` is set).
+
+## Focus indicator
+
+Row body is presentational; the only row-level focus target is the trailing Toggle Button (Outward ring). headerAction also paints its own Outward ring. Composition for any future row-level focus target: Inward — rows tile with a hairline divider.
+
+## Behavior
+
+- **Header is required.** Every DirectoryList carries a `label`; the optional `headerAction` extends the header with a trailing `accent` Text Button when there's an index page to route to.
+- **Vertical scroll, no pager.** The full list scrolls in normal document flow — reach for [SuggestionList](../suggestion-list/suggestion-list.md) instead when the surface needs a horizontal peek.
+- **Toggle commits in place.** State is owned by the consumer — `active` and `onToggle` forward per row through `items`.
+- **Entity-agnostic anatomy.** Same row shape carries channels, people, companies, or topics.

package/agents/components/directory-list/directory-list.spec.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "DirectoryList",
+  "family": "directory-list",
+  "description": "Vertical follow-list — labelled block of follow-able entries rendered at the [list/entry](../list/entry.md) `large` rung (48 Thumbnail + identity group of label + stacked `secondary` followers + `description` + trailing [Toggle Button](../button/toggle.md)). **Preset wrapper** — internally this is `<Header /> + <List variant=\"entry\" size=\"large\" divider={false}>`; the wrapper exists to map item descriptors (`name → label`, `followers → secondary`, `active/onToggle → trailingIcon`) and to lock the rung + divider preset for the canonical Follow-able directory shape. **When to reach for the primitive instead:** if you need a different size rung, mix label-only and thumbnail-bearing rows, swap the trailing Toggle for a different affordance (chevron / icon-button / star), or want per-row dividers — drop down to `<Header /> + <List variant=\"entry\" />` directly. Sibling of SuggestionList: same entity-agnostic anatomy but no swipeable pager — the full set is scanned vertically.",
+  "element": "section",
+  "props": {
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when DirectoryList is a direct child of `.chorus-carousel` / `.chorus-feed`), the list enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host."
+    },
+    "label": {
+      "type": "string",
+      "required": true,
+      "description": "Section title."
+    },
+    "headerAction": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, href?, onClick? } — trailing accent Text Button in the header. Extend the header when there's an index page to route to."
+    },
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of entity descriptors: { value, name, followers, description, thumbnail, active?, onToggle? }."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Surface block holding the header above the vertical entry list.",
+      "intrinsic": true
+    },
+    "header": {
+      "required": true,
+      "description": "[Header](../header/header.md) `size=\"large\"` — section label leading, optional `accent` Text Button trailing.",
+      "accepts": ["text", "button"]
+    },
+    "list": {
+      "required": true,
+      "description": "[List](../list/entry.md) `variant=\"entry\"` `size=\"large\"` rendering each follow-able entity. Embedded mode is forced on the inner list so the wrapper section owns the rail. The inter-row hairline divider is suppressed (`divider={false}`); rows tile against the surface fill.",
+      "intrinsic": true
+    },
+    "row": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Single entity rendered as a [list/entry](../list/entry.md) row at the `large` rung. Item descriptors map to entry slots: `name` → `label`, `followers` → `secondary`, `description` → `description`, `thumbnail` → `thumbnail`, `active` + `onToggle` → `trailingIcon` (a Toggle Button). The row body is presentational — the only commit affordance is the trailing toggle.",
+      "accepts": ["row"]
+    },
+    "trailingAction": {
+      "required": true,
+      "description": "[Toggle Button](../button/toggle.md) — the row's only commit affordance, composed into the row's `trailingIcon` slot.",
+      "accepts": ["button"]
+    }
+  },
+  "sizing": {
+    "containerFill": "sys.color.surface",
+    "containerPaddingBlock": "sys.layout.container.lg",
+    "containerPaddingInline": "sys.layout.container.md",
+    "headerToListGap": "sys.layout.stack.md",
+    "labelTypo": "sys.typo.heading.md",
+    "labelColor": "sys.color.onSurface",
+    "headerActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' — link-affordance accent rule.",
+    "rowRung": "list/entry size=\"large\" — 48 avatar, inline.lg gap, label.md primary, label.sm secondary + description.",
+    "rowInlinePaddingNote": "Each row keeps the list/entry native sys.layout.container.md inline padding (the tap target reaches the surface edge) and adds margin-inline: calc(-1 * sys.layout.container.md) so the visible avatar sits flush at the section's content rail — aligned with the header label at 16 from the surface.",
+    "dividerNote": "Inter-row hairline is suppressed via `divider={false}` on the inner List — rows tile against the surface fill rather than carrying a per-row separator. Reach for SuggestionList (xlarge rung) or List/entry directly when the surface needs a separator rule between rows."
+  },
+  "rowProps": {
+    "value": { "type": "string", "required": true },
+    "name": { "type": "string", "required": true },
+    "followers": { "type": "string", "optional": true },
+    "description": { "type": "string", "optional": true },
+    "thumbnail": {
+      "type": "object",
+      "required": true,
+      "agentRequired": true,
+      "omittedBehavior": "error",
+      "description": "Forwarded to Thumbnail verbatim — src, alt, updateDot, logoBadge. Agents MUST pass `src`; fill `/placeholder.png` when no real subject is implied."
+    },
+    "active": { "type": "boolean", "default": false },
+    "onToggle": { "type": "function", "optional": true }
+  },
+  "states": {
+    "note": "Container has no interactive state. Each row's only interactive surface is the trailing Toggle Button (its own state contract). The headerAction is an accent Text Button. The row body is presentational — tapping does not route."
+  },
+  "focusIndicator": {
+    "description": "Row body is presentational; the only row-level focus target is the trailing Toggle Button (Outward ring). headerAction also paints its own Outward ring.",
+    "composition": "inward",
+    "compositionReason": "Rows tile the column with a hairline divider; an outward ring would overlap divider and neighbour row.",
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "headerRequired": "Every DirectoryList carries a label; the optional headerAction extends the header with a trailing accent Text Button.",
+    "verticalScroll": "No pager. The full list scrolls vertically in normal document flow — reach for SuggestionList instead when the surface needs a horizontal peek.",
+    "toggleCommitsInPlace": "Tapping 'Follow' flips the row's button to 'Following' and stays there. State is owned by the consumer via items[i].active + onToggle.",
+    "entityAgnostic": "Same row shape carries channels, people, companies, or topics."
+  },
+  "forbidden": [
+    "row anatomy diverged from the [list/entry](../list/entry.md) visual contract — DirectoryList's row IS an entry-shaped row at the `large` rung; rebuilding the avatar + text column + trailing slot with different typography or geometry is a forbidden divergence",
+    "follow action rendered as button/standard — the follow affordance is button/toggle per the spec",
+    "swipeable pager — DirectoryList is intentionally vertical-only; reach for SuggestionList when a horizontal peek is needed"
+  ]
+}

package/agents/components/divider/divider.family.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "divider",
+  "name": "Divider",
+  "description": "Region separator — a heavy tonal band that splits adjacent regions whose vertical rhythm alone doesn't read as a boundary. Painted with `sys.color.scrimSubtle` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) so the band stays visible on every host surface tier (`surface`, `surfaceContainer`, `surfaceContainerHigh`, hero, …) without colliding with a fixed neutral step. Same scrim used by Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton — Divider is the section-level member of that family. Reserved for *region*-level separation between groups that don't share an enclosing container (a feed segment ending and a followed-channels list beginning, a recents block ending above a single anchored CTA). Not for row-level separators inside a List (the list's own `divider={true}` paints those as a hairline `outlineVariant` rule). Single-spec family.",
+  "useCases": [
+    "between page-level content groups",
+    "between a feed segment and the section below",
+    "between an in-page promo / banner and the list below",
+    "above a single anchored CTA at the bottom of a panel",
+    "wherever vertical rhythm alone doesn't separate two regions clearly"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "Owns nothing but its own block thickness (`sys.layout.stack.xs`, 8) and full-bleed inline footprint. Drop as a direct child of the page-shell `<main>` (or any full-width host column) between two regions. Do NOT wrap in a `padding-inline` div, `className=\"px-*\"`, or `style={{ padding }}` — Divider must touch the page edge to read as a region boundary, and the page rail is already paid once at the shell. Do NOT paint outer `margin-block` or wrap to add vertical breathing — the 8 thickness is the breathing. Inside a bounded surface (Dialog / BottomSheet / SideSheet), apply the negative-margin opt-out — see AGENTS.md § Composition rules.",
+  "usage": {
+    "example": "<Divider />"
+  },
+  "spec": "divider.md",
+  "subcomponents": [
+    {
+      "slug": "divider",
+      "spec": "divider.spec.json",
+      "md": "divider.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/divider/divider.md

@@ -0,0 +1,78 @@
+# Divider
+
+A section-break band — a single full-bleed block painted with `sys.color.scrimSubtle` (~8% inverse-tone overlay — black in light mode, white in dark) at a fixed block thickness of `sys.layout.stack.xs` (8). Reach for it when two adjacent regions don't share an enclosing container and vertical rhythm alone doesn't read as a boundary — a directory of suggested channels ending and a fresh recommendation list beginning, a feed segment ending and a followed-channels list resuming, a promo strip ending and content picking up below.
+
+**Reach for this when** the boundary between two regions is ambiguous because they share the same surface and vertical rhythm — the visitor's eye should *land* on the break, not infer it. **Skip when** the regions already sit on different surfaces (one card, one canvas — the surface change is the break), when one region carries a heading that itself reads as the start of a new block, or when the separation is between *rows of the same list* (List's own `divider={true}` paints those as a hairline `outlineVariant` rule).
+
+**Surface-agnostic by design.** The fill is `sys.color.scrimSubtle` — a ~8% inverse-tone overlay (black in light mode, white in dark) — so the band reads as a tint *darker than the host surface* without pinning to a fixed neutral step. The same band visibly separates regions on `surface`, `surfaceContainerHigh`, a hero panel, or a coloured card without retoning per-host. Same scrim tier as Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton.
+
+**Layout inset.** `full-bleed` — Divider stretches edge-to-edge inside the page-shell content box. It ships **no** inline padding, **no** outer margin, **no** corner radius, **no** stroke; it just paints `scrimSubtle` across a `sys.layout.stack.xs` (8) block. Drop it as a direct child of the page-shell `<main>` (or any full-width host column) between two regions — do not wrap in a `padding-inline` div, `className="px-*"`, or `style={{ padding }}`; the band reading edge-to-edge IS what makes it a region boundary.
+
+**Safe zone — none.** The parent column pays no `gap`, `padding-block`, or `margin-block` around Divider. The 8 of `scrimSubtle` is the breathing. If two regions feel cramped after dropping Divider between them, the fix is to add internal padding to the regions themselves (`layout.container.*`), never to wrap Divider in a spacer or paint outer margin on it.
+
+## Default
+
+The single canonical band. 8 high, full inline width, `scrimSubtle` fill.
+
+```preview
+divider/default
+---
+import { Divider } from '@teamblind-chorus/ui';
+
+<Divider />
+```
+
+## Use cases
+
+### Between adjacent lists
+
+The canonical placement — a region break between two full-bleed lists stacked on the same page. Above: a directory of new channels (DirectoryList, an inert directory). Below: a recommendation set keyed to the visitor (SuggestionList, the pager-flavoured sibling). Both lists own their internal divider hairlines for rows, but the *boundary between the two lists* is a region break — that is the role Divider plays.
+
+```preview
+divider/between-lists
+---
+import { Divider, DirectoryList, SuggestionList } from '@teamblind-chorus/ui';
+
+<div style={{ background: 'var(--sys-color-surface)', display: 'flex', flexDirection: 'column' }}>
+  <DirectoryList
+    label="New channels"
+    items={[
+      { value: 'breadclub', name: 'Sourdough Bakers', followers: '12.4K Followers', description: 'Open-crumb obsession and cold-proof timing.', thumbnail: { src: '/placeholder.png', alt: 'Sourdough Bakers' } },
+      { value: 'indiedevs', name: 'Indie Game Devs', followers: '8,210 Followers', description: 'Shipping logs, postmortems, marketing on a budget.', thumbnail: { src: '/placeholder.png', alt: 'Indie Game Devs' } },
+    ]}
+  />
+  <Divider />
+  <SuggestionList
+    label="Recommended channels"
+    items={[
+      { value: 'plants', name: 'Plant People', followers: '21.7K Followers', description: 'Houseplant troubleshooting and propagation threads.', thumbnail: { src: '/placeholder.png', alt: 'Plant People' } },
+      { value: 'movies', name: 'Movie Talk', followers: '34.2K Followers', description: 'Festival coverage, director threads, link shares.', thumbnail: { src: '/placeholder.png', alt: 'Movie Talk' } },
+    ]}
+  />
+</div>
+```
+
+## Slots
+
+- **container** — the tonal band. `sys.color.scrimSubtle` fill, `sys.layout.stack.xs` (8) block thickness, full inline width, no padding, no border, no corner radius. The native `<hr>` element with all browser defaults reset. `aria-hidden="true"` by default — the band is decorative.
+
+## Anatomy
+
+| Slot       | Token bindings |
+|------------|----------------|
+| container  | `sys.color.scrimSubtle` fill, `sys.layout.stack.xs` (8) block height, 100% inline width, `border: none`, `margin: 0`, `border-radius: 0` |
+
+## Appearance
+
+Single appearance — Divider has no emphasis axis, no orientation axis, and no thickness prop.
+
+| Appearance | Fill                       | When to use                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | `sys.color.scrimSubtle`    | The only mode. Same scrim used by Banner default / Chip-Tag default / Progress track / StatusTag neutral / Skeleton — Divider is the section-level member of that family. |
+
+## Behavior
+
+- **aria-hidden by default.** The band is decorative chrome; screen-reader users navigate by headings and landmarks, not visual breaks. Override `aria-hidden={false}` only when the divider genuinely marks a semantic section change (rare — prefer a heading).
+- **Fixed thickness.** Block thickness is `sys.layout.stack.xs` (8) and is not a prop. Heavier bands compete with content; thinner bands collapse to a hairline (use the host's own `outlineVariant` border for row-level breaks, not Divider).
+- **Full-bleed by contract.** The band must touch the page edge to read as a region boundary. Wrapping Divider in a padding-inline container breaks the affordance — see the AGENTS.md "one gutter, paid once" rule.
+- **Not a row separator.** Inside a List, rows already separate via the list's own `divider={true}` hairline `outlineVariant` rule. Reach for Divider only at the *region* level, between groups that don't share an enclosing container.