@teamblind-chorus/ui 1.0.0

package/agents/components/status-tag/status-tag.spec.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "StatusTag",
+  "family": "status-tag",
+  "description": "Small inline status pill sized for the trailing edge of a row label. Tonal label-style chrome — `surfaceContainerHighest` + `onSurfaceVariant` in `neutral`, `errorContainer` + `onErrorContainer` in `error`. 10px text, 4px inline / 2px block padding, `sys.radius.xs` corners. Decorative — `role='status'` only, never a `<button>`. The two appearances are the only emphasis axis; chromatic primary / accent fills are forbidden so a row never reads as having two competing affordances.",
+  "element": "span",
+  "props": {
+    "appearance": {
+      "type": "enum",
+      "values": ["neutral", "error"],
+      "default": "neutral",
+      "description": "Tonal fill / foreground pair. `neutral` is the quiet informational default; `error` is the rejection / blocked / failed state."
+    },
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "Tag label text. Single line; should be a short word or phrase (≤ 6 chars in Latin, ≤ 4 in CJK). Wraps would push the pill onto two lines and break the inline-with-label rhythm — keep it short instead."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Tonal pill. Carries `role='status'`. Inline-block layout so the host row's baseline aligns with the label next to it.",
+      "intrinsic": true
+    },
+    "label": {
+      "required": true,
+      "description": "Tag text. `ref.fontSize.125` (10px) / Semibold / appearance-bound foreground.",
+      "accepts": ["text"]
+    }
+  },
+  "sizing": {
+    "paddingBlock": "sys.layout.container.3xs",
+    "paddingInline": "sys.layout.container.2xs",
+    "radius": "sys.radius.xs",
+    "labelFontSize": "ref.fontSize.125",
+    "labelFontWeight": "sys.typo.label.md.weight",
+    "labelLineHeight": "1.2",
+    "labelGapFromHostLabel": "sys.layout.container.2xs"
+  },
+  "appearances": {
+    "neutral": {
+      "background": "sys.color.scrimSubtle",
+      "foreground": "sys.color.onSurfaceVariant",
+      "note": "The quiet informational default. Background paints `sys.color.scrimSubtle` — the translucent inverse-tone scrim (~8% black in light, ~8% white in dark) shared with Chip / Tag default, Progress track, and Skeleton — so the pill stays visible against every surface tier in either theme. Pair with statuses that describe an in-progress / awaiting state — 'pending', 'draft', 'queued', 'in review'."
+    },
+    "error": {
+      "background": "sys.color.errorContainer",
+      "foreground": "sys.color.onErrorContainer",
+      "note": "The rejection / blocked / failed state. Pair with statuses that describe a terminal negative outcome — 'rejected', 'failed', 'blocked'. Keep usage scarce — every error pill on a screen competes with the others for attention."
+    }
+  },
+  "states": {
+    "default": { "overlay": null, "note": "StatusTag has no lifecycle state — it is decorative. No hover / pressed / focus / disabled paint." }
+  },
+  "behavior": {
+    "decorativeOnly": "StatusTag never carries `onClick` / `href` / `tabIndex`. It is a label-style mark only; if the consumer needs the state to be tappable, wrap the host row (List row, NavCard) in the interactive surface and keep StatusTag inert.",
+    "ariaRole": "Container carries `role='status'` so screen readers announce the tag as a status update, not as a generic span.",
+    "composition": "Sized to sit next to a List row's label with a `sys.layout.container.2xs` (4px) inline gap (see Use cases). The label column owns the gap, NOT the tag.",
+    "truncationNotWrap": "Container is `inline-block` and `white-space: nowrap` — long content overflows the row layout instead of wrapping the pill onto two lines. Keep labels short."
+  },
+  "forbidden": [
+    "StatusTag rendered as a `<button>` / `<a href>` — the family is decorative; if the state needs to be tappable, the host row owns the click target",
+    "primary / accent / chromatic fill on either appearance — the family carries only `neutral` and `error`; new states (success, warning, info) must land as new appearances in the spec, never as ad-hoc colour overrides",
+    "StatusTag placed inside a chip row as if it were a Chip — visual rung (16px vs 32px) and interaction model (decorative vs selectable / dismissable) are different; chip/filter or chip/tag is the right rung for chip rows",
+    "StatusTag laid out flush against the host label with zero gap — always pay `sys.layout.container.2xs` (4px) of inline whitespace between the row label and the tag",
+    "long phrases wrapped onto a second line inside the pill — container is `nowrap`; if the phrase is long, the label is wrong, not the pill"
+  ]
+}

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

@@ -0,0 +1,46 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "suggestion-list",
+  "name": "SuggestionList",
+  "description": "Swipeable pager of follow-suggestions \u2014 labelled block where each page shows three rows of (avatar + name + meta lines + trailing Follow toggle). Built around the recommendation pattern (suggested channels, suggested people, suggested companies, suggested topics) but the anatomy is content-neutral. Single-spec family. Historically shipped as ChannelList; that name is kept as a deprecated alias.",
+  "useCases": [
+    "suggested entities to follow",
+    "recommendations block",
+    "discover panel",
+    "horizontal-paged suggestion cards"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "Owns its inline rail internally \u2014 the host is full-bleed (no inline padding); its Header pays the 16 rail and the pager re-pays it via padding-left. 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 }} \u2014 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 \u2014 see AGENTS.md \u00a7 Composition rules.",
+  "compositionModes": {
+    "standalone": {
+      "default": true,
+      "chrome": {
+        "background": "sys.color.surface",
+        "padding": "internal block; full-bleed inline — the Header pays the 16 rail and the pager re-pays it via padding-left"
+      },
+      "context": "Direct child of the page shell or any host that pays the page-rail gutter once."
+    },
+    "embedded": {
+      "trigger": "prop `embedded={true}` on <SuggestionList /> 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=\"Recommended\"><SuggestionList embedded /></Carousel>`). Row content takes over from the host's content-box edge."
+    }
+  },
+  "spec": "suggestion-list.md",
+  "usage": {
+    "note": "Also exported as the deprecated alias `ChannelList`. Rows carry `name`/`followers`/`description`, not `label`.",
+    "example": "<SuggestionList label=\"…\" headerAction={{ label, href }} items={[{ value, name, followers, description, thumbnail, active, onToggle }]} />"
+  },
+  "subcomponents": [
+    {
+      "slug": "suggestion-list",
+      "spec": "suggestion-list.spec.json",
+      "md": "suggestion-list.md",
+      "default": true
+    }
+  ]
+}

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

@@ -0,0 +1,91 @@
+# Suggestion list
+
+A vertically-stacked block of follow-able recommendations rendered as a swipeable pager. One page shows three [list/entry](../list/entry.md)-shaped rows at the `xlarge` rung (56px [Thumbnail](../thumbnail/thumbnail.md), label + stacked `secondary` followers + `description`, trailing [Toggle Button](../button/toggle.md)); the next page peeks at the trailing edge to invite the swipe. Anatomy is entity-agnostic — channels, people, companies, topics share one shape.
+
+**Reach for this when** a follow-able set is best surfaced as a peek of three with horizontal paging — recommended channels, people you may know, suggested companies. **Skip when** the full set should scan vertically with no pager (use [DirectoryList](../directory-list/directory-list.md)), the rail is a label-only nav strip ([AvatarRail](../avatar-rail/avatar-rail.md)), or the surface needs fixed-width profile cards ([Profile carousel](../carousel/profile.md)).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell (or any surface that pays the gutter) and stretches edge-to-edge. The container pays **no** inline padding (matches [DirectoryList](../directory-list/directory-list.md)): its [Header](../header/header.md) owns the 16 inline rail and its 24/16 block padding, and the pager re-pays the 16 left rail via `padding-left` while spanning the full-bleed surface so the next-page peek reaches the trailing edge. Each row keeps its list/entry native `16px inline padding` for the tap target and adds a `-16` inline margin so the visible content (avatar / toggle) still sits flush at the page boundaries — net result, the avatar reads at 16 from the surface (aligned with the header label) and the next page's avatar peeks 8 past the surface's right edge. 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
+
+Two-page list (six channels), header label only.
+
+```preview
+suggestion-list/default
+---
+import { SuggestionList } from '@teamblind-chorus/ui';
+
+<SuggestionList
+  label="Recommended channels"
+  items={[
+    { value: 'sourdough', name: 'Sourdough Bakers', followers: '12.4K Followers', description: 'Open-crumb obsession, cold-proof timing, starter help.', thumbnail: { alt: 'Sourdough Bakers' } },
+    { value: 'indiedev',  name: 'Indie Game Devs',  followers: '8,210 Followers', description: 'Shipping logs, postmortems, marketing on a budget.', thumbnail: { alt: 'Indie Game Devs' } },
+    { value: 'plants',    name: 'Plant People',     followers: '21.7K Followers', description: 'Houseplant troubleshooting and propagation threads.', thumbnail: { alt: 'Plant People' } },
+    { value: 'movies',    name: 'Movie Talk',       followers: '34.2K Followers', description: 'Festival coverage, director threads, link shares.', thumbnail: { alt: 'Movie Talk' } },
+    { value: 'mods',      name: 'Community Mods',   followers: '1,840 Followers', description: 'Weekly digests and rules discussion across channels.', thumbnail: { alt: 'Community Mods' } },
+    { value: 'amas',      name: 'AMAs',             followers: '5,120 Followers', description: 'Scheduled Q&A sessions with founders and creators.', thumbnail: { alt: 'AMAs' } },
+  ]}
+/>
+```
+
+## 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
+suggestion-list/with-header-action
+---
+import { SuggestionList } from '@teamblind-chorus/ui';
+
+<SuggestionList
+  label="People you may know"
+  headerAction={{ label: 'See all', href: '/channels' }}
+  items={[
+    { value: 'jordan',  name: 'Jordan Lee',     followers: '342 Followers',  description: 'PM at a logistics startup. Mostly here for the threads on roadmap reviews.', thumbnail: { alt: 'Jordan Lee' } },
+    { value: 'taylor',  name: 'Taylor Brooks',  followers: '1.1K Followers', description: 'Frontend engineer. Writes about the bits between the framework and the user.', thumbnail: { alt: 'Taylor Brooks' } },
+    { 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, 24px block padding, **full-bleed inline** (the Header pays the 16 rail). Holds the header above the pager.
+- **header** — the shared [Header](../header/header.md) component (`size="large"` default): section label leading, optional text-link action trailing. Anchored outside the pager; owns its own 16 inline rail and 24/16 block padding.
+- **label** — Header's section title. `heading.md` (20px / Semibold) / `onSurface`.
+- **headerAction** *(optional)* — Header's trailing [`xsmall` Text Button](../button/text.md), `accent` appearance. Renders as `<a>` when `href` is set.
+- **pager** — horizontally-scrolling track with mandatory inline scroll-snap; native scrollbar hidden. Next page peeks at the trailing edge.
+- **page** — one swipe target. Vertical stack of exactly three rows.
+- **row** — channel suggestion rendered as a [list/entry](../list/entry.md)-shaped row at the `xlarge` rung (56 Thumbnail). Each item descriptor (`name` / `followers` / `description` / `thumbnail` / `active` / `onToggle`) maps to the entry contract (`label` / `secondary` / `description` / `thumbnail` / `trailingIcon`). The row keeps its family-default `container.md` inline padding for the tap target and adds a `-container.md` inline margin so the visible avatar / toggle sit flush at the page boundaries; the row body itself is not clickable — it's presentational. SuggestionList wraps the row with its own bottom-padding + hairline divider (the text-column-anchored rule that ties the divider's left edge to the start of the text column).
+
+## Anatomy
+
+| Slot           | Token bindings |
+|----------------|----------------|
+| container      | `surface` fill, 24px block padding, **full-bleed inline**, vertical stack |
+| header         | Shared [Header](../header/header.md) (`size="large"`). Its `sys.layout.stack.md` (16px) block-end is the header↔pager gap (host gap → 0); its `sys.layout.stack.lg` (24px) block-start replaces the container's leading inset. |
+| label          | Header's label — `heading.md` / Semibold / `onSurface` |
+| headerAction   | Header's trailing `xsmall` [Text Button](../button/text.md), `accent` appearance |
+| pager          | Horizontal scroll, `scroll-snap-type: x mandatory`, scrollbar hidden; `sys.layout.inline.xl` (16/24px) gap. Re-pays the 16 left rail via `padding-left: sys.layout.container.md` (+ matching `scroll-padding-left` snap-port); the full-bleed host means the pager spans the surface so the next-page peek reaches the trailing edge intrinsically (no negative margin). When embedded in a padded host (Feed), the pager re-adds `margin-inline: -sys.layout.container.md` to pierce the host's rail. |
+| page           | `flex: 0 0 calc(100% - sys.layout.inline.xl - sys.layout.inline.md)` so the next page leading edge shows by 8px; `scroll-snap-align: start`; `sys.layout.stack.sm` (12px) between rows |
+| row            | [list/entry](../list/entry.md)-shaped row at `xlarge` rung — 56 avatar, `inline.lg` gap, label.md primary / label.sm `secondary` + `description`. Keeps the list/entry native `container.md` inline padding (tap target) and adds `margin-inline: -container.md` so the visible content (avatar / toggle) sits flush at the page boundaries — the avatar reads at 16 from the surface, aligned with the header label. SuggestionList adds: 12px bottom padding + `::after` divider 1px / `outlineVariant` anchored at the text column (standalone: `container.md` 16 + `ref.space.700` 56 + `inline.lg` 12 = 84px from row left; embedded: 68px since the row's inline padding + margin are zeroed). |
+| 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. Trigger: `:focus-visible`.
+
+## Behavior
+
+- **Header is required.** Every SuggestionList carries a `label`; the optional `headerAction` extends the header with a trailing `accent` Text Button when there's an index page to route to.
+- **Pages of three rows.** A page is exactly three rows; the final page pads with empty space rather than collapsing.
+- **Horizontal scroll-snap.** `scroll-snap-type: x mandatory`; each page declares `scroll-snap-align: start`.
+- **Next-page peek.** The host is full-bleed, so the pager spans the surface and the peek reaches the trailing edge intrinsically; it re-pays the 16 left rail via `padding-left` + `scroll-padding-left` so page 1 snaps at the content rail and the row's leftward tap-area extension stays visible inside the left padding strip. When embedded in a padded host (Feed) the pager re-adds `margin-inline: -sys.layout.container.md` to pierce the host's rail. Page basis composes inter-page gap (`inline.xl`) plus visible peek (`inline.md` = 8px) in one `calc`.
+- **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/suggestion-list/suggestion-list.spec.json

@@ -0,0 +1,178 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "SuggestionList",
+  "family": "suggestion-list",
+  "exportAlias": "ChannelList",
+  "description": "Vertically-stacked block of follow suggestions rendered as a swipeable pager. One page shows three rows that follow the [list/entry](../list/entry.md) visual contract at the `xlarge` rung (56 Thumbnail + identity group of label + stacked `secondary` follower count + `description` + trailing Toggle Button flipping between 'Follow' and 'Following'); the next page peeks at the trailing edge to invite the swipe. Anatomy is entity-agnostic — suggested channels, suggested people, suggested companies, suggested topics all share the same shape.",
+  "element": "div",
+  "props": {
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when SuggestionList 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. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `suggestion-list.family.json`."
+    },
+    "label": {
+      "type": "string",
+      "required": true,
+      "description": "Section title."
+    },
+    "headerAction": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, href? , onClick? } — trailing text link in the header."
+    },
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of channel descriptors: { value, name, followers, description, thumbnail, active?, onToggle? }."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Surface block holding header above the swipeable pager. Full-bleed inline (no host inline padding) — the Header pays the 16 rail.",
+      "intrinsic": true
+    },
+    "header": {
+      "required": true,
+      "description": "The shared [Header](../header/header.md) component (`size='large'`) — section label leading, optional text-link action trailing. Stays anchored while pages scroll; owns its own 16 inline rail and 24/16 block padding.",
+      "intrinsic": true
+    },
+    "label": {
+      "required": true,
+      "description": "Section title. heading.md / Semibold / onSurface.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "headerAction": {
+      "required": false,
+      "description": "Trailing [Text Button](../button/text.md) (`size={'xsmall'}`, `appearance={'accent'}`) — typically 'See all'. Renders as a link-affordance, so it follows the family-wide rule: link-shaped Text Buttons take `accent` for chromatic emphasis (see [text.md](../button/text.md#accent) and rule 8 of the agent contract).",
+      "accepts": [
+        "button"
+      ]
+    },
+    "pager": {
+      "required": true,
+      "description": "Horizontally-scrolling track of pages with mandatory inline scroll-snap; native scrollbar hidden.",
+      "intrinsic": true
+    },
+    "page": {
+      "required": true,
+      "description": "Vertical stack of exactly three rows. Width = container inner width minus a peek amount.",
+      "intrinsic": true
+    },
+    "row": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Single channel suggestion rendered as a [list/entry](../list/entry.md)-shaped row at `xlarge` rung. Item descriptors map to entry slots: `name` → `label`, `followers` → `secondary`, `description` → `description`, `thumbnail` → `thumbnail` (forwarded verbatim at the 56 rung), `active` + `onToggle` → `trailingIcon` (a Toggle Button). SuggestionList wraps the row with its own bottom-padding + hairline divider (text-column anchored).",
+      "accepts": [
+        "row"
+      ]
+    },
+    "trailingAction": {
+      "required": true,
+      "description": "[Toggle Button](../button/toggle.md) — the row's only commit affordance, composed into the row's `trailingIcon` slot. The row body itself is not clickable.",
+      "accepts": [
+        "button"
+      ]
+    }
+  },
+  "sizing": {
+    "containerFill": "sys.color.surface",
+    "containerPaddingBlock": "sys.layout.container.lg",
+    "containerPaddingInline": "0",
+    "containerPaddingInlineNote": "Full-bleed: the host pays no inline padding. The Header pays the 16 inline rail (sys.layout.container.md) and the pager re-pays it via padding-left.",
+    "headerToPagerGap": "sys.layout.stack.md",
+    "headerToPagerGapNote": "Header's own block-end (stack.md = 16) is the header↔pager gap; the host gap collapses to 0 (matches DirectoryList).",
+    "labelTypo": "sys.typo.heading.md",
+    "labelColor": "sys.color.onSurface",
+    "headerActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' — label paints in sys.color.primary via the Text Button accent token.",
+    "headerActionTypo": "sys.typo.label.sm",
+    "headerActionColor": "sys.color.primary",
+    "pageGap": "sys.layout.inline.xl",
+    "pagePeek": "sys.layout.inline.md",
+    "pageRowGap": "sys.layout.stack.sm",
+    "rowComposition": "list/entry-shaped row at `xlarge` rung — avatar 56, row gap inline.lg, label.md / onSurface, stacked `secondary` label.sm / onSurface, `description` label.sm / onSurfaceVariant separated from the identity group by `ref.space.25`. SuggestionList adds the per-row chrome (bottom padding + text-column-anchored divider) on top of that.",
+    "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 / toggle still sit flush at the page boundaries — the avatar reads at 16 from the surface, aligned with the header label, and the trailing toggle ends one inline.xl (16) before the next page's avatar. Embedded mode zeroes both the row padding and the negative margin since the host pays the rail directly (the pager re-adds its both-side bleed there).",
+    "rowBottomPadding": "sys.layout.stack.sm",
+    "rowBottomPaddingNote": "The bottom padding sits between the row's text content and the hairline divider so the divider reads as a separator rather than a baseline rule.",
+    "dividerWidth": "sys.borderWidth.hairline",
+    "dividerColor": "sys.color.outlineVariant",
+    "dividerInset": "calc(sys.layout.container.md + ref.space.700 + sys.layout.inline.lg) = 84px from the row's leading edge in standalone mode — anchors to the start of the row's text column so the divider aligns with the column, not the avatar. Embedded mode re-anchors to 68px (drops the container.md term) since the row's inline padding + negative margin are zeroed."
+  },
+  "rowProps": {
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "name": {
+      "type": "string",
+      "required": true
+    },
+    "followers": {
+      "type": "string",
+      "required": true
+    },
+    "description": {
+      "type": "string",
+      "required": true
+    },
+    "thumbnail": {
+      "type": "object",
+      "required": true,
+      "agentRequired": true,
+      "omittedBehavior": "error",
+      "fallbackOnMissingSrc": "sys.color.surfaceContainerHigh",
+      "description": "Forwarded to Thumbnail verbatim — src, alt, updateDot, logoBadge. Agents MUST pass `src`; fill `/placeholder.png` when no real subject is implied. `fallbackOnMissingSrc` is the runtime safety net for load failures, not a scaffold-time omission license."
+    },
+    "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 a text link (Text links state contract). The row body is presentational — tapping does not route."
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Channel List's own rows are presentational (tap-to-route is not owned by the row body); this contract documents the composition any nested focus target inherits — the trailing Toggle Button paints its own outward ring per its spec, but any forthcoming row-level focus target tiles flush with hairline dividers and would use the Inward composition.",
+    "composition": "inward",
+    "compositionReason": "Rows tile the column with a hairline divider; an outward ring would overlap divider and neighbour row.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the row edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the row edge (the counter-ring just inside the outer stroke)",
+      "implementation": "inset box-shadow constrained strictly inside the row's footprint."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "pagesOfThree": "A page is always exactly three rows. If items is not a multiple of three, the final page is padded with empty space — it never collapses to a shorter page.",
+    "horizontalScrollSnap": "scroll-snap-type: x mandatory; each page declares scroll-snap-align: start.",
+    "nextPagePeek": "The host is full-bleed, so the pager spans the surface and the peek reaches the trailing edge intrinsically (no negative margin); it re-pays the 16 left rail via padding-left + scroll-padding-left so page 1 snaps at the content rail and the row's leftward tap-area extension stays visible inside the left padding strip. When embedded in a padded host (Feed) the pager re-adds margin-inline: -container.md to pierce the host's rail. Page basis composes the inter-page gap (inline.xl) plus the visible peek (inline.md, 8px) into one calc — the 8px peek holds across the responsive breakpoint.",
+    "toggleCommitsInPlace": "Tapping 'Follow' flips the row's button to 'Following' and stays there. State is owned by the consumer via items[i].active + onToggle."
+  },
+  "accessibility": {
+    "region": "the pager is a labelled scroll region: role='group' with aria-roledescription='carousel' and aria-label / aria-labelledby wired to the block's `label` heading, so assistive tech announces a named, swipeable group rather than an unlabelled scroll box.",
+    "keyboardReach": "Rows on pages 2+ MUST stay reachable without swiping: each row's trailing Toggle Button is in the natural tab order, and focusing an off-screen row scrolls its page into the viewport (scroll-into-view on :focus). The pager has no decorative-only navigation that would otherwise strand later pages from the keyboard.",
+    "paddingNotAnnounced": "When the final page is padded to three rows (see behavior.pagesOfThree), the empty padding cells carry aria-hidden='true' so a screen reader does not traverse phantom rows.",
+    "perRowName": "Each row exposes its entity name as its accessible label so the Toggle Button tab stop reads as 'Follow {name}', not a bare 'Follow'."
+  },
+  "forbidden": [
+    "row anatomy diverged from the [list/entry](../list/entry.md) visual contract — SuggestionList's row IS an entry-shaped row at the xlarge rung (56); 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",
+    "pager-style scroll snap removed — the swipeable pager is the family contract",
+    "more than the declared page-of-rows shown at once — overflow is the swipeable affordance, not a wrap"
+  ]
+}

package/agents/components/switch/switch.family.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "switch",
+  "name": "Switch",
+  "description": "Binary on/off control — a pill-shaped track with a circular thumb that translates between the two ends. The off state reads as a muted `surfaceContainerHighest` track; the on state paints the track in `primary` so the contract reads chromatically without an inline label. Use for instant-commit settings where the change applies the moment the thumb moves; reach for a [Button](../button/button.md) when the commit needs a confirmation step. Single-spec family.",
+  "useCases": [
+    "instant-commit settings toggle",
+    "notification on/off",
+    "privacy / visibility toggle",
+    "list row trailing-slot toggle"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "switch.md",
+  "usage": {
+    "note": "Change handler is `onCheckedChange` (not `onChange`); instant commit, no confirmation step. Whole pill is the target — the thumb is decorative.",
+    "example": "<Switch checked={on} onCheckedChange={setOn} aria-label=\"…\" />"
+  },
+  "subcomponents": [
+    {
+      "slug": "switch",
+      "spec": "switch.spec.json",
+      "md": "switch.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/switch/switch.md

@@ -0,0 +1,114 @@
+# Switch
+
+A binary active/inactive control — a pill-shaped track with a circular thumb that translates between ends. **Inactive** reads as a `scrimSubtle` track with an `outlineVariant` hairline and a fixed-white thumb; **active** paints the track in `primary` so the contract reads chromatically without an inline label.
+
+**Reach for this when** a setting commits the moment it changes — notifications, privacy toggles, *show in feed*, instant-commit list trailing. **Skip when** the commit needs confirmation (use [Button](../button/button.md) + [Dialog](../dialog/dialog.md)), when the user picks one of several options ([List/radio](../list/radio.md), [Tabs](../tabs/tabs.md)), or when destructive — Switch carries no undo.
+
+**Layout inset.** inline — ships no padding. Sits next to its label with at least `sys.layout.inline.md` (12px) gap; the host surface pays surrounding padding.
+
+## Inactive
+
+The resting state — a `scrimSubtle` track (inverse-tone ~8% tint: black in light, white in dark) with an `outlineVariant` hairline and a fixed-white thumb at the leading end. The tint stays distinct on any host surface tier. The specimen below is pinned to this type (rendered `checked={false}`); see [Behavior](#behavior) for the live toggle contract.
+
+```preview
+switch/inactive
+---
+import { Switch } from '@teamblind-chorus/ui';
+
+<Switch checked={false} aria-label="Notifications" />
+```
+
+## Active
+
+The committed state — `primary` track with the thumb stepped to `onPrimary` at the trailing end. The outline disappears so the filled track reads as one solid block. Like the inactive specimen, this one is pinned to its type (rendered `checked`).
+
+```preview
+switch/active
+---
+import { Switch } from '@teamblind-chorus/ui';
+
+<Switch checked aria-label="Notifications" />
+```
+
+## Use cases
+
+### With label
+
+The canonical pairing — a visible label to the left, `sys.layout.inline.md` (12px) gap. The label carries the accessible name via `htmlFor` + `id` or `aria-labelledby`; Switch drops `aria-label`.
+
+```preview
+switch/with-label
+---
+import { Switch } from '@teamblind-chorus/ui';
+
+<div
+  style={{
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: 'var(--sys-layout-inline-md)',
+    padding: 'var(--sys-layout-container-xs) var(--sys-layout-container-md)',
+  }}
+>
+  <span id="notif-label" className="sys-typo-body-sm" style={{ color: 'var(--sys-color-onSurface)' }}>
+    Push notifications
+  </span>
+  <Switch checked aria-labelledby="notif-label" />
+</div>
+```
+
+### Focus indicator
+
+Outward 3-layer ring on the track's outer edge, shown on the inactive specimen. The card is pinned to its focused state via `forcedState="focused"`; in production the ring triggers on `:focus-visible` (keyboard / programmatic focus, never a plain mouse click).
+
+```preview
+switch/focused
+---
+import { Switch } from '@teamblind-chorus/ui';
+
+<Switch checked={false} forcedState="focused" aria-label="Notifications" />
+```
+
+## Slots
+
+- **track** — pill container, 52 × 32, fully rounded. Carries click, focus ring, and overlay paint. `role="switch"`; `aria-checked` reflects active/inactive.
+- **thumb** *(decorative)* — 28 × 28 knob that translates between ends on toggle. Never a separate hit target.
+
+## Anatomy
+
+| Slot             | Token bindings |
+|------------------|----------------|
+| track (inactive) | `sys.color.scrimSubtle` fill, hairline `outlineVariant` stroke, fully rounded |
+| track (active)   | `sys.color.primary` fill, no stroke, fully rounded |
+| thumb (inactive) | `ref.palette.white.1000` (fixed white) fill, 28 × 28, fully rounded, 2px inset from leading edge |
+| thumb (active)   | `sys.color.onPrimary` fill, 28 × 28, translated 20px to the trailing end |
+| transition       | 120ms `ease-out` on track-fill, thumb-fill, and thumb-translate |
+
+## Appearance
+
+A single appearance — no emphasis axis. The visible variation is the `data-state="active"` / `"inactive"` contract.
+
+| State    | Track fill          | Track stroke              | Thumb fill                             |
+|----------|---------------------|---------------------------|----------------------------------------|
+| inactive | `sys.color.scrimSubtle` | `outlineVariant` hairline | `ref.palette.white.1000` (fixed white) |
+| active   | `sys.color.primary`     | none                      | `sys.color.onPrimary`                  |
+
+## States
+
+| State      | Overlay                           | Additional |
+|------------|-----------------------------------|------------|
+| `default`  | —                                 | Resting paint per the active/inactive contract. |
+| `hovered`  | label tone at `sys.state.hover`   | Overlay paints across the track. |
+| `pressed`  | label tone at `sys.state.pressed` | Overlay deepens; no other shift. |
+| `disabled` | overlay suppressed                | Container at `sys.state.disabled` opacity; `pointer-events: none`. |
+
+## Focus indicator
+
+Outward 3-layer ring on the track's outer edge via an `::after` overlay. Trigger: `:focus-visible`. Switch sits inline next to siblings with whitespace around it, so outward reads cleanly — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+## Behavior
+
+- **Instant commit.** `onCheckedChange` fires the moment the user releases — no confirmation step.
+- **Whole track is the click target.** The thumb is decorative; it never receives focus or events.
+- **Keyboard.** Space and Enter both toggle when Switch holds focus.
+- **Controlled / uncontrolled.** Pass `checked` + `onCheckedChange`, or `defaultChecked` to let Switch own state.