@teamblind-chorus/ui 1.0.0

package/agents/catalog.md

@@ -0,0 +1,232 @@
+# Catalog — intent → component
+
+Reverse index from natural-language intent to family + sub-component. Read *before* opening any spec to narrow candidates. Authoritative shape lives in `schema/components/<family>/<sub>.spec.json`; this file is a routing layer.
+
+> **How to import / use a family → `usage.json`.** This catalog names families as `family / sub`. The React access pattern differs per family: a named import (`profile-header` → `import { ProfileHeader }`), a `variant=` prop (`button / fab` → `<Button variant="fab">` — there is **no** `<Fab>` export), a separate export (`carousel / post` → `PostCarousel`), or a data array (`list / entry` → `<List items={[…]}>` — there is **no** `<ListItem>`). `usage.json` is the authoritative, build-time **parity-checked** map of every family to its exact usage. **A failed `import { X }` for one component never means the catalog is unreliable or a family is "missing at runtime" — look it up in `usage.json` and use the access it specifies. Never fall back to assembling a family from token primitives.**
+
+## How intent binding works
+
+Each family declares `visualReuse: "open" | "locked"` in its `<family>.family.json`. The catalog respects that flag.
+
+- **Open (default, 27 families)** — `avatar-rail`, `badge`, `banner`, `bubble`, `button`, `carousel`, `chip`, `directory-list`, `divider`, `feed`, `header`, `list`, `metadata`, `nav-card`, `nav-list`, `navigation-bar`, `page-shell`, `profile-header`, `progress`, `side-sheet`, `skeleton`, `status-tag`, `suggestion-list`, `switch`, `tab-bar`, `tabs`, `thumbnail`. The intent table is the *first* suggestion, but the agent MAY reach for these on visual-fit grounds even when the brief's intent does not match the row verbatim — e.g. `<Feed>` as a generic article-card surface, `<Banner>` as a tonal aside outside a literal "notice", `<Carousel>` as any labelled editorial block. Anatomy invariants (slot grammar, token bindings, intrinsic geometry) still apply.
+- **Locked (5 families)** — `dialog`, `bottom-sheet`, `toast`, `tooltip`, `form-field`. MUST only be used when the brief's intent matches a row. Their contract IS the interaction — focus trap, auto-dismiss, ARIA live region, form semantics, hover/focus trigger. Borrowing the visual shape without the role breaks behavior. Marked *(locked)* below.
+
+When in doubt: open families are recipes, locked families are rules.
+
+## Top bars
+
+**Layout**: every entry is `layoutInset: full-bleed` — direct child of `<main>`, no wrapper `padding-inline`.
+
+| Intent                                | Family + sub                       |
+| ------------------------------------- | ---------------------------------- |
+| landing screen header, title bar      | `navigation-bar / main`            |
+| post / content detail header, back + wordmark + action cluster | `navigation-bar / main` (drill-in: pass `onBack`) |
+| drill-in screen header, back + centred title | `navigation-bar / sub`       |
+| search screen header, input fills bar | `navigation-bar / search`          |
+| profile / channel detail page identity (cover + avatar + name + follow) | `profile-header` |
+
+**Disambiguate**: never stack two NavigationBars. Pick by *screen kind*, not *content kind*. `profile-header` is not a bar — it's the page-level identity block (cover, avatar, name, follow) at the top of a profile detail route; pair it with a transparent overlay `navigation-bar / sub` when the route is a drill-in.
+
+## Action commits
+
+**Layout**: every entry is `layoutInset: inline` — an atom that needs grouping (action row, toolbar, button group) to sit at page level. Exception: `button / fab` is viewport-anchored fixed-position chrome and lives outside the page's normal stack.
+
+| Intent                                     | Family + sub                  |
+| ------------------------------------------ | ----------------------------- |
+| primary inline commit (Save, Continue)     | `button / standard`           |
+| canonical floating commit (Compose, New)   | `button / fab`                |
+| icon-only inline commit                    | `button / icon`               |
+| link-shaped commit, low emphasis           | `button / text`               |
+| option toggle next to a primary commit     | `button / check`              |
+| reversible state (mute/unmute, follow)     | `button / toggle`             |
+| dense action inside a toolbar              | `button / toolbar`            |
+| destructive primary commit                 | `button / standard` with `flavor: "destructive"` (inside a Dialog) |
+
+**Disambiguate**: FAB = the **single** canonical commit per screen. Destructive primary commits go in `dialog`/`bottom-sheet`, not on a FAB.
+
+## Structure & layout
+
+**Layout**: mixed. `page-shell`, `divider`, and `header` are `full-bleed` — direct children of `<main>` (or the host column), no wrapper `padding-inline`. Both `header` members (`header / main` = `<Header>`, `header / sub` = `<SubHeader>`) own their own `container.md` (16) inline rail and a transparent background, so they align with the rows / feed items they head and paint on whatever surface tier hosts them.
+
+| Intent                                                  | Family + sub  | layoutInset   |
+| ------------------------------------------------------- | ------------- | ------------- |
+| app screen scaffold that pins the top + bottom bars     | `page-shell`  | `full-bleed`  |
+| labelled block heading + optional trailing "See all"    | `header / main` | `full-bleed`  |
+| quiet group label above a stack of rows ("Following")   | `header / sub`  | `full-bleed`  |
+| heavy tonal band splitting two page regions             | `divider`     | `full-bleed`  |
+
+**Disambiguate**: `page-shell` is the only screen-level scaffold — it pins `navigation-bar` (top) + `tab-bar` (bottom) so a long scrolling body never pushes the bars off-screen; never re-implement pinning with `position: fixed` + body padding. `header / main` (`<Header>`) = a leading title + a single trailing action ("See all"), composed at the head of a list / carousel / feed / card / sheet section — it's the title atom, not screen chrome (`navigation-bar` is the bar). `header / sub` (`<SubHeader>`) = the same family's quieter member, a 14px muted label that *names* a group of rows beneath it (at most a single Text Button action). `divider` = a heavy `scrimSubtle` region band for when vertical rhythm alone doesn't separate two regions — NOT a hairline between list rows (that's built into `List`), and NOT the thin shadcn `<Separator>` (see name-translation table).
+
+## Vertical content surfaces
+
+**Layout**: most entries below are `layoutInset: full-bleed` — direct child of `<main>`, no wrapper `padding-inline`. When nested inside `<Carousel>` / `<Feed>` (another full-bleed host that pays its own chrome), pass `embedded` so background + padding defer to the host — see [`AGENTS.md` § Composition rules](../AGENTS.md#composition-rules). The `nav-card` row is the exception — it's `layoutInset: inline` (an inline card with its own padding + outline + radius that fills the host column; the host owns the surrounding inset).
+
+| Intent                                       | Family + sub             | layoutInset    |
+| -------------------------------------------- | ------------------------ | -------------- |
+| settings / menu / picker rows                | `list / standard`        | `full-bleed`   |
+| single-select option group                   | `list / radio`           | `full-bleed`   |
+| avatar-anchored rows (channels, DMs)         | `list / entry`           | `full-bleed`   |
+| drill-in rows with trailing chevron          | `list / standard` (or `/ entry`, `/ radio`) with `nav: true` | `full-bleed`   |
+| standalone drill-in card (single row)        | `nav-card`               | **`inline`**   |
+| expandable titled sections (FAQ, T&C)        | `accordion`              | `full-bleed`   |
+| authored content stream (posts, comments)    | `feed / feed`            | `full-bleed`   |
+| follow suggestions block (swipeable peek)    | `suggestion-list`        | `full-bleed`   |
+| follow directory (full vertical scroll)      | `directory-list`         | `full-bleed`   |
+| label-only nav list with chevron rows        | `nav-list`               | `full-bleed`   |
+
+**Disambiguate**: `feed` = authored content (author, body, footer). `list` = menus/settings/pickers (stacked rows, hairline divider). `nav-card` = a SINGLE drill-in row as its own bounded outlined card — reach for it when one drill-in needs to read as its own affordance, not one entry in a stack. `accordion` = stacked rows that EXPAND in place rather than drill-in — for short content the user opens to read (FAQ, T&C, expandable filter). `suggestion-list` = labelled swipeable block of follow-suggestions (channels, people, companies, topics — same anatomy). `directory-list` = the same row anatomy at the `large` (48) rung but rendered as a full vertical scroll (no pager) — reach for it when the surface should expose the whole follow-able set. `nav-list` = a labelled vertical list of label-only chevron rows; same wrapper-of-Header + List composition, but for route navigation rather than follow.
+
+### Entity directory rows + author attribution
+
+| Intent                                                            | Family + sub             | Layout       |
+| ----------------------------------------------------------------- | ------------------------ | ------------ |
+| generic entity row (channel / person / company / topic + commit)  | `list / entry`           | `full-bleed` |
+| compact directory entry (channel / topic / playlist + count)      | `list / entry` at `size="small"` | `full-bleed` |
+| follow-suggestion swipeable page-of-three                          | `suggestion-list`        | `full-bleed` |
+| author / brand attribution at the head of a Feed card             | `metadata / standard`    | `inline`     |
+| one-line comment / reply author attribution (company · nickname · time) | `metadata / compact` | `inline`     |
+
+**Disambiguate**: `list/entry` is the single home for every entity-row case — directory entries, follow rows, member rosters, mention / recipient pickers, entity search results. The list ships its own `16px inline / 8px block` row padding and tiles rows full-bleed with hairline dividers; the row itself supports identity group (label + optional inline `count` Badge + optional stacked `secondary` line) + optional single-line `description` (separated by `ref.space.25` (2)) + optional trailing affordance. Pick the leading Thumbnail rung via `size="small|medium|large|xlarge"` (32 / 40 / 48 / 56). `suggestion-list` wraps the same row contract in a swipeable page-of-three for the follow-suggestion block. `metadata` is the only `inline` atom in this group, in two shapes: `standard` — fixed 32-rung Thumbnail, primary line is name + optional inline timestamp + optional follow toggle (middot-separated), secondary line is a `meta` link row OR a `Sponsored` subtitle — composed at the head of `feed / post` and `feed / ad`; `compact` (`variant="compact"`) — the secondary-line grammar standing alone, one text line, no avatar: company name · nickname (optional role badge) · trailing plain timestamp, for comment / reply rows. Reach for `list/entry` for every entity-presentation row; reach for `metadata` only at Feed card heads (standard) or comment / reply attributions (compact).
+
+## Horizontal content surfaces
+
+**Layout**: every entry is `layoutInset: full-bleed` — direct child of `<main>`, no wrapper `padding-inline`. When nested inside `<Carousel>` / `<Feed>`, pass `embedded` so chrome defers to the host — see [`AGENTS.md` § Composition rules](../AGENTS.md#composition-rules).
+
+| Intent                                  | Family + sub             |
+| --------------------------------------- | ------------------------ |
+| compact horizontal entity quick-nav      | `avatar-rail`           |
+| section tabs with sliding indicator     | `tabs / underline`       |
+| chip-shaped tab row with leading icons  | `tabs / rounded`         |
+| in-place mode toggle (List ↔ Grid)      | `tabs / segmented`       |
+
+## Modal surfaces
+
+**Layout**: mixed — column below. `bounded-surface` floats *above* the page (portal-mounted, viewport-anchored, owns its safe area). `banner` is the outlier — it's `inline` (an inline card that fits the host column with no outer margin) and lives **in** the content column, not above it; it's listed here only because it's the in-flow alternative to a modal prompt.
+
+| Intent                                              | Family + sub                                                | layoutInset       |
+| --------------------------------------------------- | ----------------------------------------------------------- | ----------------- |
+| short focused commit anchored to bottom of viewport | `bottom-sheet` *(locked)*                                   | `bounded-surface` |
+| confirmation prompt, centered                       | `dialog` *(locked)*                                         | `bounded-surface` |
+| destructive confirmation                            | `dialog` *(locked)* with destructive primary action         | `bounded-surface` |
+| inline notice inside the content column             | `banner / accent` or `/ default` (not modal — in-flow aside)| **`inline`** ⚠ |
+| transient post-action confirmation (saved, copied)  | `toast` *(locked)* — non-modal, auto-dismiss                | `bounded-surface` |
+| trigger-anchored hint over a hovered/focused control | `tooltip` *(locked)* — non-modal, hover/focus-driven       | `bounded-surface` |
+| off-canvas navigation / filter drawer (left or right edge) | `side-sheet` (anchor `left` / `right`)                  | `bounded-surface` |
+
+**Disambiguate**: `bottom-sheet`/`dialog` are modal — require a trigger elsewhere. `banner` is not modal; lives in the content column. `toast` is non-modal and self-dismissing — reach for it only when the action has landed and no decision is needed. `tooltip` is non-modal and floats over a specific trigger — only when the message describes a hovered/focused control. `side-sheet` is the off-canvas anchor sibling of `bottom-sheet` (open, not locked) — a drawer for navigation / channel directory / filter rail; compose `Header` (medium) + compact `List` inside `SideSheetGroup`. Top anchor is out of scope.
+
+## Inputs
+
+**Layout**: every entry in the table below is `layoutInset: inline` — `<FormField>` wraps inline within a form column. The Search sub-table further down mixes layouts (NavBar vs FormField).
+
+| Intent                                | Family + sub               |
+| ------------------------------------- | -------------------------- |
+| labeled single-line text field        | `form-field / input` *(locked)* |
+| bare pill search input                | `form-field / search` *(locked)* |
+
+**Disambiguate**: `form-field` is *(locked)* — only for real text entry. For an Input-shaped read-only display row, reach for a `list / standard` row or a token-faithful primitive rather than borrowing the form-field shell (the `<input>` semantics, label binding, and a11y plumbing would lie).
+
+### Search affordance — three candidates, pick by surface
+
+"Search" maps to three different Chorus rungs by where the field sits. Do NOT default to the first that comes to mind — and do NOT fall back to a hand-rolled `<input>`. All three exist and are typed in `dist/index.d.ts`:
+
+| Surface (where the field lives)                                | Component                                            | layoutInset    | Why                                                                                                                          |
+| -------------------------------------------------------------- | ---------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Top bar takes the whole row** (search mode of a screen)       | `<NavigationBar variant="search">`                   | `full-bleed`   | The bar IS the field. Owns back chevron + bare input + clear button as one chrome unit. Use when entering "search mode" of a screen. |
+| **Inline filter / list-top / sheet-top** (chrome, not a form)   | `<FormField variant="search">`                       | `inline`       | The bare pill — leading magnifier glyph, focus-only clear button, no label / helper / maxLength. The affordance is the glyph. |
+| **Inside a real form** (search-shaped input that needs a label) | `<FormField variant="input" leadingIcon={<SearchIcon/>} label="…" helper="…">` | `inline` | Use when the field needs a visible label, helper text, error appearance, or character count — `search` has none of those.    |
+
+Each row resolves to a typed React component — `<FormField variant="search" placeholder="…" onChange={…}>` autocompletes from `dist/index.d.ts`. IDE shows `ComponentType<any>`? You're reading a stale shim — delete it and re-resolve.
+
+## Compact controls
+
+**Layout**: every entry is `layoutInset: inline` — sits inside another component's slot (List leading, Banner trailing, Feed footer, Thumbnail corner), never at page level on its own.
+
+| Intent                                       | Family + sub      |
+| -------------------------------------------- | ----------------- |
+| toggle chip for facet selection              | `chip / filter`   |
+| informational / dismissable metadata pill    | `chip / tag`      |
+| numeric unread / update count                | `badge / update`  |
+| role / title mark beside a user's nickname   | `badge / role`    |
+| inline image (avatar, list leading, channel) | `thumbnail`       |
+| instant-commit on/off toggle                 | `switch`          |
+| inline status mark next to a row label       | `status-tag`      |
+| always-on annotation pill anchored to a UI element | `bubble`     |
+
+**Disambiguate**: `switch` = single binary on/off that commits the moment it flips (notifications, privacy). For multi-option pickers use `list / radio`; for actions needing confirmation use `button` + `dialog`; for "selected" facet state in a chip row use `chip / filter`. `status-tag` = SMALL (16-rung, 10px text) decorative status pill inline next to a row label — "pending", "rejected", "draft". For a 32-rung interactive chip use `chip / tag`; for a numeric count attached to an icon/thumbnail use `badge / update`; for a role / title mark beside a user's nickname (Channel owner / Verified / PRO) use `badge / role` — identity, where `status-tag` is workflow state. `bubble` = a labelled pill with a tail that points at a specific element to flag attention *at rest* (new-feature nudge, keyword/campaign promo next to a top-bar icon or search bar) — vs `badge` (numeric count / dot, no tail) and `status-tag` (status mark on a row label).
+
+## Loading & Placeholder
+
+**Layout**: every entry is `layoutInset: inline` — placed where the real content will land, taking the slot's footprint.
+
+| Intent                                                | Family + sub          |
+| ----------------------------------------------------- | --------------------- |
+| in-flight content placeholder (mirrors content shape) | `skeleton`            |
+| linear progress for a known long-running task          | `progress`            |
+
+**Disambiguate**: `skeleton` = *in-flight* tonal block previewing where content will land. For loading data the host would otherwise paint as empty. NOT for empty states (no data yet) — those use illustration + body copy. `progress` = slim track for a *long-running, identifiable* task with a known ratio (upload, onboarding step, background sync). For sub-300ms or opaque waits use neither (a brief blank surface or a spinner reads better).
+
+## Shadcn / Lovable name translation
+
+When an AI agent (or designer paging in from shadcn) reaches for a shadcn-named component, this is the Chorus surface to render. Direct React `export` aliases live in `packages/ui/src/index.js` where the name doesn't already collide (`Sheet`, `Drawer`, `Alert`, `Avatar`, `AppBar`, `BottomNav`); the table below covers the rest — including where Chorus splits one shadcn shape into multiple intent-bound surfaces.
+
+| Shadcn / Lovable name              | Chorus surface to render                                                            | Notes |
+|-----------------------------------|------------------------------------------------------------------------------------|-------|
+| `<Alert variant="default">`        | `<Banner appearance="default">`                                                     | Already aliased — `import { Alert } from '@teamblind-chorus/ui'`. |
+| `<Alert variant="destructive">`    | `<Banner appearance="destructive">`                                                 | Use the destructive appearance. |
+| `<AlertDialog>` (confirm prompt)   | `<Dialog>`                                                                          | Same locked modal-confirmation contract (focus trap, primary/secondary actions). |
+| `<Badge variant="…">` *(text pill)* | `<StatusTag appearance="neutral \| error">`                                          | Chorus `Badge` defaults to the numeric/dot count marker — same name, different intent. Text-pill `<Badge>` calls translate to `StatusTag` when they carry workflow state, or to `<Badge variant="role">` when they name a user's role / title. |
+| `<Avatar>` (image+fallback compound) | `<Thumbnail src=… alt=… />`                                                         | Already aliased. Use Thumbnail's `imageFallbackImage` / `imageFallbackText` props instead of the `<AvatarFallback>` child. |
+| `<Card>` (generic bordered block)  | One of: `<Carousel>` (labelled editorial block), `<Feed>` (authored content), `<NavCard>` (drill-in row), `<Banner>` (tonal aside) | Chorus splits "Card" by intent — pick by what the block carries, not by the chrome. |
+| `<Carousel>` (wrapper)             | `<Carousel><PostCarousel /></Carousel>` (cards) or `<Carousel><ProfileCarousel /></Carousel>` (avatar-anchored) | Pick the sub by content rung. |
+| `<Checkbox>` (single)              | `<Button variant="check">`                                                          | Chorus `Button` `check` sub IS the checkbox — leading 24px checkbox glyph + label. List-row multi-select uses `<Chip variant="filter">`. |
+| `<Command>` (command palette)      | `<FormField variant="search">` + `<BottomSheet>` + `<List>` pattern                 | Composition, not a single primitive. Mobile-first translation of the desktop command palette. |
+| `<ContextMenu>` (right-click menu) | `<BottomSheet>` with a `List`                                                       | Same as `<DropdownMenu>` — right-click on mobile becomes a one-thumb sheet. |
+| `<DropdownMenu>` (floating menu)   | `<BottomSheet>` with a `List`                                                       | Mobile-first — floating menus collide with one-thumb reach. |
+| `<HoverCard>` / `<Popover>`        | `<Tooltip>` (short text) or `<BottomSheet>` (multi-line / actionable)               | Hover-anchored surfaces don't translate to mobile. |
+| `<Label>` (standalone form label)  | `<FormField>`'s `label` slot                                                        | No standalone `<Label>`. Every input label lives on its host `<FormField>` via the `label` prop — keeps label/field/helper triplet locked. For non-input labels (settings group title, drawer column heading), use `<Header size="medium">`. |
+| `<NavigationMenu>` (top-level nav) | `<NavigationBar>` (page chrome) / `<TabBar>` (bottom app nav) / `<NavCard>` (drill-in row) | Chorus splits "navigation" by surface role. |
+| `<RadioGroup>` + `<RadioGroupItem>` | `<List variant="radio" items={[…]} onChange=… />`                                    | Chorus's only radio surface IS the list row. |
+| `<Separator>` (horizontal rule)    | `<Divider>` for a heavy region split; otherwise built into the host (`List` row divider, `Carousel` block gap, `BottomSheet` action rail border) | Hairlines between rows come from the host's anatomy, not a standalone rule — vertical rhythm comes from `sys.layout.stack.*`. For a heavier band between two page-level regions, use `<Divider>` (the `divider` family). Do NOT hand-roll a hairline `<Separator>`. |
+| `<Sheet side="bottom">`            | `<BottomSheet>`                                                                     | Aliased. |
+| `<Sheet side="left">` / `<Sheet side="right">` | `<SideSheet anchor="left">` / `<SideSheet anchor="right">`              | Off-canvas navigation drawer / side panel. Compose with `Header` (medium) + `List` (thumbnail, compact) inside `SideSheetGroup`. Aliased — `import { SideDrawer } from '@teamblind-chorus/ui'`. Top is out of scope. |
+| `<Sidebar>` (off-canvas app nav)   | `<SideSheet anchor="left">`                                                         | Desktop persistent sidebar becomes the off-canvas drawer. Compose with `SideSheetGroup` (Header + List compact) for the channel-directory shape. |
+| `<Sonner>` / `toast()` imperative  | `<Toast>` declarative                                                               | Chorus toast is declarative — render `<Toast>` from the host; no imperative `toast()` call. |
+| `<ToggleGroup type="single">`      | `<Tabs variant="segmented">`                                                        | In-place mode toggle. |
+| `<ToggleGroup type="multiple">`    | A row of `<Chip variant="filter">`                                                  | Multi-select facet selection. |
+
+### Chorus gaps — flag, do not improvise
+
+These shadcn primitives have no Chorus equivalent and no on-pattern mobile substitution. When a brief demands one, **stop and flag a "Chorus gap"** — do NOT improvise a wrapper, re-introduce shadcn, or hardcode raw values. Maintainers add the missing family; agents wait or work around.
+
+| Shadcn / Lovable name | Mobile use case (when it WOULD be needed) | Status |
+|-----------------------|--------------------------------------------|--------|
+| `<Calendar>` (date picker) | Birthday, schedule, calendar event picker.    | **Gap**. Workaround: pair `<FormField variant="select">` with native `<input type="date">` inside a `<BottomSheet>`; flag the gap. |
+| `<Chart>` (data viz)    | Analytics, finance, fitness charts.            | **Gap**. Workaround: external `recharts`/`chart.js`, but every color/typography MUST resolve through Chorus tokens (`var(--sys-*)`); flag the gap. |
+| `<Slider>` (range)      | Price-range filter, volume/brightness.        | **Gap**. Workaround: native `<input type="range">` styled via tokens; flag the gap. |
+| `<InputOTP>` (OTP code) | Verification code entry (auth flows).         | **Gap**. Workaround: row of `<FormField variant="input">` with `maxLength=1`; flag the gap. |
+
+### Out of mobile scope — substitute the mobile pattern
+
+These shadcn primitives are desktop-first or web-OS conventions Chorus deliberately omits because the mobile equivalent is a different shape. Agents MUST substitute the listed pattern instead of re-introducing the shadcn primitive.
+
+| Shadcn / Lovable name | Out of scope because | Mobile substitute |
+|-----------------------|----------------------|--------------------|
+| `<Breadcrumb>`        | Mobile is deep-link / drill-in; no horizontal trail.            | `<NavigationBar variant="sub">` (back + title). |
+| `<Menubar>`           | Persistent app menubar is desktop chrome.                       | `<NavigationBar>` for top chrome + `<BottomSheet>` for action overflow. |
+| `<Pagination>`        | Mobile feeds are infinite-scroll, not paged.                              | Infinite scroll inside `<Feed>` / `<List>` (consumer wires the loader). |
+| `<Resizable>`         | Adjustable split panels are desktop.                         | None — single-pane mobile layout. Flag a "Chorus gap" if a tablet split view is required. |
+| `<Table>` (data grid) | Wide rows don't fit one-thumb column.                                   | `<List variant="standard">` or `<Feed>` rows. For tabular data, render one row per item with `label` + `supportingText`. |
+| `<ScrollArea>`        | Custom-styled scrollbars fight native mobile scroll.                       | Native scroll on the host element. Do NOT introduce a styled track. |
+
+## Disambiguation cheat sheet
+
+*First-pass* defaults for open families; *hard rules* for locked families.
+
+- **Filter chip vs Toggle button** (both open): `chip/filter` for facet selection in a chip row; `button/toggle` for standalone reversible state. Either visual shape may be reused outside canonical intent.
+- **Tag chip vs Badge vs StatusTag** (open): `chip/tag` = 32-rung selectable text metadata; `badge / update` = numeric count/dot attached to a host icon or thumbnail; `badge / role` = 16-rung tonal role / title pill beside a user's name (identity); `status-tag` = 16-rung decorative inline status pill next to a row label (workflow state).
+- **List vs Feed** (both open): same-kind rows → List, authored content stream → Feed *as default*. Either may be reused for a different content shape — e.g. a `Feed`-style card hosting a non-post summary, or a `List` row hosting an editorial item.
+- **BottomSheet vs Dialog** (both locked): short/actionable/one-thumb → BottomSheet; confirmation or image-led → Dialog. **Never** borrow either for non-modal — dismiss/focus contracts are the point.
+- **Banner vs BottomSheet**: in-flow context → `banner` (open, reusable as a generic tonal block). Demands a commit before continuing → `bottom-sheet` *(locked)*.
+- **Toast vs Tooltip vs Banner**: all three describe "short message", but `toast` *(locked)* is auto-dismissing and `tooltip` *(locked)* is trigger-anchored — visual reuse outside those roles is forbidden. For a static "small message" in the reading flow, reach for `banner` (open).
+- **Skeleton vs Progress**: `skeleton` previews *where content will land* (placeholder that swaps out atomically). `progress` shows *how far a task has advanced* (value-bound or busy indicator). Sub-300ms waits: neither.

package/agents/components/avatar-rail/avatar-rail.family.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "avatar-rail",
+  "name": "AvatarRail",
+  "description": "Compact horizontal strip of avatar entry points \u2014 each item routes to an entity (channel, person, brand, topic) with a single tap. The rail sits above a feed or inside a sidebar and gives the visitor a quick switcher across the entities they follow. Single-spec family. Historically shipped as ChannelRail; that name is kept as a deprecated alias.",
+  "useCases": [
+    "followed entities rail",
+    "horizontal avatar switcher",
+    "story-style quick nav",
+    "one-thumb entity nav"
+  ],
+  "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 }} \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": "sys.layout.container.sm sys.layout.container.md"
+      },
+      "context": "Direct child of the page shell or any host that pays the page-rail gutter once. The rail owns its own row chrome."
+    },
+    "embedded": {
+      "trigger": "prop `embedded={true}` on <AvatarRail /> (renders as `data-embedded=\"true\"`) OR direct child of `.chorus-carousel` / `.chorus-feed` (DOM-ancestry safety net via `:where()` in styles.css).",
+      "chrome": {
+        "background": "transparent",
+        "padding": "0"
+      },
+      "context": "Composed inside another rail-responsible host (e.g. `<Carousel label=\"Shortcuts\"><AvatarRail embedded /></Carousel>`) that already pays the gutter and background. Row items take over from the host's content-box edge, so the same vertical rail aligns through host header and rail items. Use the `embedded` prop explicitly so the composition is readable in JSX; the ancestry safety net handles the case where the prop is omitted."
+    }
+  },
+  "spec": "avatar-rail.md",
+  "usage": {
+    "note": "Also exported as the deprecated alias `ChannelRail`. Items route via `href`; the update dot lives on `thumbnail.updateDot`.",
+    "example": "<AvatarRail aria-label=\"…\" items={[{ value, label, href, thumbnail }]} trailingAction={{ label, href }} />"
+  },
+  "subcomponents": [
+    {
+      "slug": "avatar-rail",
+      "spec": "avatar-rail.spec.json",
+      "md": "avatar-rail.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/avatar-rail/avatar-rail.md

@@ -0,0 +1,103 @@
+# Avatar rail
+
+A horizontal strip of channel entry points — each item routes to a channel or company page. Composes a [Thumbnail](../thumbnail/thumbnail.md) (optional `updateDot`) and a single-line label; an optional trailing action lives at the end.
+
+**Reach for this when** the row is a label-only nav strip of subscribed or saved entities — *Subscribed channels*, *Saved companies*, *My topics*. **Skip when** rows carry follower counts or descriptions (use [DirectoryList](../directory-list/directory-list.md) / [SuggestionList](../suggestion-list/suggestion-list.md)), the surface is fixed-width profile cards ([Profile carousel](../carousel/profile.md)), or rows commit in place rather than route ([Toggle Button](../button/toggle.md) cluster).
+
+**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 family owns its own internal row / header padding via `layout.container.*`; do **not** wrap in another `padding-inline` / `px-*` / `style={{ padding: … }}` div, or the page rail double-pays. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+A four-channel rail with a trailing "View all" action.
+
+```preview
+avatar-rail/default
+---
+import { AvatarRail } from '@teamblind-chorus/ui';
+
+<AvatarRail
+  aria-label="Subscribed channels"
+  items={[
+    { value: 'hyundai',  label: 'Hyundai Motor',  href: '/channels/hyundai',  thumbnail: { alt: 'Hyundai', updateDot: true } },
+    { value: 'samsung',  label: 'Samsung',        href: '/channels/samsung',  thumbnail: { alt: 'Samsung', updateDot: true } },
+    { value: 'naver',    label: 'Naver',          href: '/channels/naver',    thumbnail: { alt: 'Naver' } },
+    { value: 'mobis',    label: 'Hyundai Mobis',  href: '/channels/mobis',    thumbnail: { alt: 'Hyundai Mobis', updateDot: true } },
+  ]}
+  trailingAction={{ label: 'View all', href: '/channels' }}
+/>
+```
+
+## Use cases
+
+### With overflow
+
+When the rail carries more items than the container fits, it scrolls horizontally.
+
+```preview
+avatar-rail/overflow
+---
+import { AvatarRail } from '@teamblind-chorus/ui';
+
+<AvatarRail
+  aria-label="Subscribed channels"
+  items={[
+    { value: 'hyundai',   label: 'Hyundai Motor',   href: '/channels/hyundai',   thumbnail: { alt: 'Hyundai', updateDot: true } },
+    { value: 'samsung',   label: 'Samsung',         href: '/channels/samsung',   thumbnail: { alt: 'Samsung', updateDot: true } },
+    { value: 'naver',     label: 'Naver',           href: '/channels/naver',     thumbnail: { alt: 'Naver' } },
+    { value: 'mobis',     label: 'Hyundai Mobis',   href: '/channels/mobis',     thumbnail: { alt: 'Hyundai Mobis', updateDot: true } },
+    { value: 'kakao',     label: 'Kakao',           href: '/channels/kakao',     thumbnail: { alt: 'Kakao' } },
+    { value: 'lg',        label: 'LG Electronics',  href: '/channels/lg',        thumbnail: { alt: 'LG', updateDot: true } },
+    { value: 'sk',        label: 'SK Hynix',        href: '/channels/sk',        thumbnail: { alt: 'SK Hynix' } },
+    { value: 'kia',       label: 'Kia',             href: '/channels/kia',       thumbnail: { alt: 'Kia' } },
+  ]}
+  trailingAction={{ label: 'View all', href: '/channels' }}
+/>
+```
+
+## Slots
+
+- **container** — horizontal flex strip over `surface`. Overflows horizontally; scrollbar hidden. Never wraps.
+- **item** — channel entry, rendered as `<a href>`. Stacks Thumbnail above label.
+- **avatar** — [Thumbnail](../thumbnail/thumbnail.md) at the 48 rung. Forwards every other Thumbnail prop verbatim.
+- **label** — channel name. `label.sm` / Regular / `onSurface`. Single line; truncates.
+- **trailingAction** *(optional)* — [`small` Text Button](../button/text.md), `accent` appearance per the link-affordance rule. Renders as `<a>` when `href` is set. Vertically centred against the avatar row.
+
+## Anatomy
+
+| Slot           | Token bindings |
+|----------------|----------------|
+| container      | `surface` fill, `sys.layout.container.sm` / `sys.layout.container.md` (12 / 16px) padding, `sys.layout.inline.xl` (16→24px) gap between track and trailing action, scrollbar hidden |
+| track          | Trailing-edge `mask-image` fade over the rightmost `ref.space.600` (48px), painted only when the track overflows |
+| item           | Flex column, items centred; 8px avatar↔label; 16px between item columns |
+| avatar         | [Thumbnail](../thumbnail/thumbnail.md) `size={48}` |
+| label          | `label.sm` / Regular / `onSurface`, max-width 80px (matches avatar) |
+| trailingAction | `small` [Text Button](../button/text.md), `accent` appearance, vertically centred against avatar row |
+
+## Sizes
+
+A single rung. Rail width follows its container and overflows horizontally when content exceeds the box.
+
+## States
+
+Container has no interactive state. Each item is a text-link affordance obeying the [Text links](../../DESIGN.md#text-links) contract — underline is the affordance, colour does not change on hover or press.
+
+| State      | Overlay                    | Additional |
+|------------|----------------------------|------------|
+| `default`  | —                          | Label `onSurface`, no underline. |
+| `hovered`  | —                          | 1px same-colour underline; label colour unchanged. |
+| `pressed`  | `sys.state.pressed`        | Underline persists; pressed overlay tints. |
+| `disabled` | overlay suppressed         | Item at `sys.state.disabled` opacity; underline suppressed. |
+
+The trailing action is a `small` Text Button (rendered as `<a>` when `href` is set) — Text Button hover overlay + standard three-layer focus ring. Mirrors the Channel List header action; the only difference is the rung.
+
+## Focus indicator
+
+Standard ring painted around the item's outer edge (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)). Trigger: `:focus-visible`.
+
+## Behavior
+
+- **Items are anchors.** Each item is `<a href>`; routing belongs to the host framework's link integration.
+- **Horizontal scroll only.** Overflowing items scroll horizontally; the rail never wraps.
+- **Edge fade (conditional).** Trailing 48px fade via `mask-image`, painted only while overflow is present. Same `useScrollOverflow` hook Tabs uses.
+- **No selection state.** Navigation, not a picker — no `value` / `onChange`. "Current channel" highlighting is the host's job via Thumbnail props.
+- **Trailing action floats with the row.** Stays at the end of rail content; scrolling reveals it like the last item.

package/agents/components/avatar-rail/avatar-rail.spec.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "AvatarRail",
+  "family": "avatar-rail",
+  "exportAlias": "ChannelRail",
+  "description": "Horizontal strip of avatar entry points — each item routes to an entity (channel, person, brand, topic) page. The rail sits above a feed or inside a sidebar and gives the visitor one tap to jump into the entities they follow. Every item composes a Thumbnail (with optional updateDot) and a single-line label; an optional trailing action ('View all', 'Manage') lives at the end of the row.",
+  "element": "div",
+  "props": {
+    "aria-label": {
+      "type": "string",
+      "required": true,
+      "description": "Accessible name for the rail."
+    },
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of channel entries: { value, label, href, thumbnail }."
+    },
+    "trailingAction": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, href? , onClick? } — trailing [Text Button](../button/text.md) (`size={'small'}`, `appearance={'accent'}`) at the end of the rail (typically 'View all' / 'Manage'). Link-affordance rule: link-shaped Text Buttons take `accent` for chromatic emphasis."
+    },
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when the AvatarRail is a direct child of `.chorus-carousel` / `.chorus-feed`), the rail 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 `avatar-rail.family.json`."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Horizontal flex strip over a surface fill; overflows horizontally with native scrollbar hidden. Never wraps to a second row.",
+      "intrinsic": true
+    },
+    "track": {
+      "required": true,
+      "description": "The horizontally-scrolling track of items. Carries the Edge fade affordance — a trailing-edge mask-image gradient when overflow is present.",
+      "intrinsic": true
+    },
+    "item": {
+      "required": true,
+      "description": "Single channel entry point. Rendered as <a href> — the entire item is the click target.",
+      "intrinsic": true
+    },
+    "avatar": {
+      "required": true,
+      "description": "Thumbnail at size 48 — every Thumbnail prop forwarded verbatim.",
+      "accepts": [
+        "thumbnail"
+      ]
+    },
+    "label": {
+      "required": true,
+      "description": "Channel name. label.sm / Regular / onSurface. Single line; truncates with ellipsis. max-width matches the avatar (80px).",
+      "accepts": [
+        "text"
+      ]
+    },
+    "trailingAction": {
+      "required": false,
+      "description": "Trailing [Text Button](../button/text.md) (`size={'small'}`, `appearance={'accent'}`). Vertically centred against the avatar row, not the full item. Link-affordance rule applies.",
+      "accepts": [
+        "button"
+      ]
+    }
+  },
+  "sizing": {
+    "containerFill": "sys.color.surface",
+    "containerPaddingBlock": "sys.layout.container.sm",
+    "containerPaddingInline": "sys.layout.container.md",
+    "containerActionGap": "sys.layout.inline.xl",
+    "fadeWidth": "ref.space.600",
+    "itemColumnGap": "sys.layout.inline.md",
+    "itemAvatarLabelGap": "sys.layout.stack.xs",
+    "avatarSize": 48,
+    "labelTypo": "sys.typo.label.sm",
+    "labelColor": "sys.color.onSurface",
+    "labelMaxWidth": "ref.space.1000",
+    "trailingActionRendersAs": "Button variant='text' size='small' appearance='accent' — label paints in sys.color.primary via the Text Button accent token.",
+    "trailingActionTypo": "sys.typo.label.md",
+    "trailingActionColor": "sys.color.primary"
+  },
+  "itemProps": {
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "label": {
+      "type": "string",
+      "required": true
+    },
+    "href": {
+      "type": "string",
+      "required": true
+    },
+    "thumbnail": {
+      "type": "object",
+      "required": true,
+      "description": "Forwarded to Thumbnail verbatim — src, alt, updateDot, logoBadge."
+    }
+  },
+  "states": {
+    "default": {
+      "decoration": "none",
+      "label": "sys.color.onSurface"
+    },
+    "hovered": {
+      "description": "1px same-color underline under the label. Color does not change — the underline is the affordance.",
+      "textDecoration": "underline",
+      "textDecorationThickness": "sys.borderWidth.hairline",
+      "textUnderlineOffset": "ref.space.25",
+      "cursor": "pointer"
+    },
+    "pressed": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.pressed"
+      },
+      "note": "Underline persists."
+    },
+    "disabled": {
+      "containerOpacity": "sys.state.disabled",
+      "suppressUnderline": true,
+      "pointerEvents": "none"
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the item is in. The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
+    "composition": "inward",
+    "compositionReason": "Horizontal scroller; an outward ring would clip at the rail's top/bottom edges.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the item edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the item edge (the counter-ring just inside the outer stroke)",
+      "implementation": "inset box-shadow on the item's `::after` overlay. Constrained strictly inside the item's footprint and never exceeds it."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "itemsAreAnchors": "Each item renders as <a href> so open-in-new-tab / drag-to-bookmark works. The component does not intercept clicks.",
+    "horizontalScrollOnly": "Overflowing items scroll horizontally; the rail never wraps to a second row. Native scrollbar hidden.",
+    "edgeFade": "When the track overflows, its trailing 48px (ref.space.600) fades to transparent via a mask-image linear-gradient. Painted only while overflow is present — useScrollOverflow hook (shared with Tabs) toggles data-overflow-end='true' on the track.",
+    "noSelectionState": "The rail is navigation, not a picker. No value / onChange contract. Highlighting 'the current channel' is the host page's job.",
+    "trailingActionFloats": "The optional trailingAction stays at the end of the rail content; when the rail overflows, scrolling reveals it."
+  },
+  "forbidden": [
+    "rail item rendered with sys.color.brand as the fill — avatar-rail items inherit the underlying Thumbnail family contract",
+    "rail wrapped in a horizontal-padding div — avatar-rail is full-bleed by family declaration",
+    "label below 12px — rail labels use sys.typo.label.sm (12px), never finer",
+    "rail items reflowing — the rail snap-scrolls horizontally with a fixed item width"
+  ]
+}

package/agents/components/badge/badge.family.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "badge",
+  "name": "Badge",
+  "description": "Small non-interactive mark attached to a host label. Two subs share the anchored-to-a-host anatomy and `radius.full` corner but diverge on intent and tone: `update` is the brand-tone activity indicator (numeric count pill or labelless dot) flagging unread / new activity; `role` is the tonal primary-container pill naming a user's role or title ('Channel owner', 'Verified') riding the bare nickname at the end of the user-metadata meta row — one badge per nickname; the 'inverse' appearance is reserved for the paid-expert 'PRO' mark.",
+  "useCases": [
+    "unread count",
+    "update count",
+    "numeric indicator",
+    "host attachment",
+    "user role mark",
+    "title / position annotation",
+    "paid-expert PRO mark"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "badge.md",
+  "usage": {
+    "note": "Both forms are the single `Badge` export selected by the `variant` prop — there is NO `<UpdateBadge>` or `<RoleBadge>` export. Default variant is `update`: count via children or `count`; render a dot (no number) with a `dot-*` size — there is no separate `Dot` element.",
+    "example": "<Badge size=\"medium\" count={3} />",
+    "subs": {
+      "update": {
+        "variant": "update",
+        "example": "<Badge size=\"medium\" count={3} />"
+      },
+      "role": {
+        "variant": "role",
+        "example": "<Badge variant=\"role\">Verified</Badge>"
+      }
+    }
+  },
+  "subcomponents": [
+    {
+      "slug": "update",
+      "spec": "update.spec.json",
+      "md": "update.md",
+      "default": true
+    },
+    {
+      "slug": "role",
+      "spec": "role.spec.json",
+      "md": "role.md"
+    }
+  ]
+}

package/agents/components/badge/badge.md

@@ -0,0 +1,10 @@
+# Badge
+
+A small, non-interactive mark anchored to a host label — badge-shaped annotation for two roles. **Update** is the brand-tone activity indicator: a numeric count pill or a labelless corner dot flagging unread / new activity (3 unread, `99+`, a dot on a [Thumbnail](../thumbnail/thumbnail.md)). **Role** is the tonal identity pill: a pale `primaryContainer` mark naming the user's role or title — Channel owner (채널장), Verified (현직자) — riding the bare nickname at the end of their metadata's meta row. The two share the anchored anatomy, the `radius.full` corner, and the never-interactive contract; they diverge on tone (brand vs primary-container) and on what they say about the host (*what's new* vs *who this is*). Both are reached through the single `Badge` export — `variant="update"` (default) / `variant="role"`.
+
+**Layout inset.** `inline` — slot atom. A Badge has no page-rail responsibility; the host places it (Thumbnail corner, List row label, [Metadata](../metadata/metadata.md) trailing edge). Never a sibling of `full-bleed` page rows.
+
+## Sub-components
+
+- **[Update](./update.md)** — Brand-tone activity indicator. **Numeric** count pill (`medium` / `small`) for counts that carry meaning, or labelless **Dot** (`dot-md` / `dot-sm`) when the presence of activity is the whole signal. The default variant.
+- **[Role](./role.md)** — Tonal role / title pill (English labels: Channel owner, Verified). `primaryContainer` fill, `onPrimaryContainer` 10px label, 16-rung; rides the bare nickname at the end of the metadata meta row. Identity, not state — workflow status belongs to [Status tag](../status-tag/status-tag.md).