@teamblind-chorus/ui 1.0.0

package/agents/components/button/toolbar.spec.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Button",
+  "family": "button",
+  "subcomponent": "toolbar",
+  "description": "Dense inline toolbar action — 32px (ref.space.400) capsule, label + optional leading / trailing glyph. Visual chrome delegated verbatim to Filter chip — every visual property (min-height, padding, radius, label rung, icon size, container/border/label colors, state overlays, focus ring) mirrors the chip. The semantic divergence is intent: Toolbar Button fires an action; Filter chip toggles a selection; both render with the same DOM and the same CSS classes (`chorus-chip chorus-chip--filter`).",
+  "delegatesTo": "chip/filter",
+  "element": "button",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "toolbar"
+    },
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "default",
+        "accent",
+        "inverse"
+      ],
+      "default": "default"
+    },
+    "leadingIcon": {
+      "type": "node",
+      "optional": true
+    },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "label": {
+      "required": true,
+      "description": "Required, single line.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "leadingIcon": {
+      "required": false,
+      "description": "Context glyph before the label.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "trailingIcon": {
+      "required": false,
+      "description": "Directional / destination glyph after the label (chevron-down, ×).",
+      "accepts": [
+        "icon"
+      ]
+    }
+  },
+  "sizing": {
+    "$ref": "../chip/filter.spec.json#/sizing"
+  },
+  "appearances": {
+    "default": {
+      "background": "sys.color.surfaceContainerHigh",
+      "label": "sys.color.onSurface",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.outlineVariant"
+      },
+      "note": "The canonical Toolbar Button chrome (mirrors Filter chip's unselected state). The chip-shape signals an inline action that lives within a row of peers (a toolbar, a card footer, a Page bar where the affordance is one of several actions the user might pick)."
+    },
+    "accent": {
+      "background": "sys.color.primary",
+      "label": "sys.color.onPrimary",
+      "border": null,
+      "note": "Brand-blue commit chip — reach for it when the Toolbar Button IS the surface's commit affordance (a Page bar's 'Save', a sheet's 'Confirm', a flow step's 'Done'). The accent fill claims commit-rank attention while keeping the 32px Toolbar Button footprint, so the bar reads at one density even though the action is the screen's most important. Pair sparingly — never two accent Toolbar Buttons in the same row."
+    },
+    "inverse": {
+      "background": "sys.color.inverseSurface",
+      "label": "sys.color.inverseOnSurface",
+      "border": null,
+      "note": "Inverse-toned chip for use inside an inverse host (snackbars, coach-mark surfaces, dark coach overlays). Same chrome geometry as `default`; the colour pair flips to the inverse cluster so the chip reads against the host's `inverseSurface` fill without a per-host tweak."
+    }
+  },
+  "states": {
+    "$ref": "../chip/filter.spec.json#/states"
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the button is in. Visual ring is delegated to Filter chip's composition; this block restates the contract for external readers.",
+    "composition": "outward",
+    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding toolbar row.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset"
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "forbidden": [
+    "Toolbar button without aria-label",
+    "Toolbar button used as a primary commit — toolbar is for dense secondary actions in a row",
+    "Mixing toolbar buttons with non-toolbar variants in the same row — the row geometry is the contract"
+  ]
+}

package/agents/components/carousel/carousel.family.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "carousel",
+  "name": "Carousel",
+  "description": "Page-region wrapper for editorial collections — a labelled block with a leading section heading and an optional trailing `See all` link, hosting a horizontal swipeable rail of cards underneath. Two sub-component shapes ride the same Carousel chrome: **post** — a swipeable rail of compact post cards (curated popular posts, paid / verified-account priority placements); **profile** — a swipeable rail of profile-style cards (channels, user profiles, company channels). Both share the same pager geometry (40px guaranteed trailing peek, leading-padding sticky anchor) so editorial collections of posts and profiles tile cleanly. The Carousel component is exported as `<Carousel>`; the two carousel shapes are accessed via `<Carousel.Post>` / `<Carousel.Profile>` (or legacy aliases `<PostCarousel>` / `<ProfileCarousel>`) and are always composed inside the labelled Carousel host.",
+  "useCases": [
+    "section heading",
+    "labelled editorial collection",
+    "see-all link",
+    "post carousel",
+    "profile carousel",
+    "channel carousel",
+    "company carousel"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "legacyExports": ["Section"],
+  "legacyExportsNote": "The family was renamed from `Section` to `Carousel`. `Section` remains a deprecated runtime alias re-exported from `packages/ui/src/index.js` so existing imports keep compiling; new code should reach for `Carousel`. Consumers may be migrated when convenient — there is no fixed removal date.",
+  "wrapperGuidance": "Owns its inline rail internally — 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 }} — 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.",
+  "usage": {
+    "note": "Carousel is the labelled section *wrapper* (heading + see-all link). The cards are a separate export per sub — there is NO `<CarouselItem>`. Also exported as the deprecated alias `Section`.",
+    "subs": {
+      "post": { "import": "PostCarousel", "example": "<Carousel label=\"…\"><PostCarousel items={[{ avatar, channel, title, body, views, onClick }]} /></Carousel>" },
+      "profile": { "import": "ProfileCarousel", "example": "<Carousel label=\"…\"><ProfileCarousel items={[{ avatar, name, meta, onFollowChange }]} /></Carousel>" }
+    }
+  },
+  "spec": "carousel.md",
+  "subcomponents": [
+    {
+      "slug": "post",
+      "spec": "post.spec.json",
+      "md": "post.md",
+      "default": true
+    },
+    {
+      "slug": "profile",
+      "spec": "profile.spec.json",
+      "md": "profile.md"
+    }
+  ]
+}

package/agents/components/carousel/carousel.md

@@ -0,0 +1,40 @@
+# Carousel
+
+Page-region wrapper for editorial collections — a labelled block with a leading heading and an optional trailing `See all` link, hosting a horizontal swipeable rail underneath. Carousel owns the chrome (surface, padding, header anatomy); each sub owns only its pager + cards.
+
+- **[Post](./post.md)** — a swipeable rail of compact post cards. Surfaces a curated set of popular posts or gives paid / verified accounts priority placement inside the feed column.
+- **[Profile](./profile.md)** — a swipeable rail of profile-style cards (channels, user profiles, company channels). Surfaces "Hot companies right now", recommended channels, or any profile-shaped collection.
+
+Both subs share the same pager geometry — a `ref.space.500` (40px) trailing peek and a leading-padding sticky snap anchor — so editorial collections of posts and profiles tile cleanly side by side.
+
+**Reach for this when** a finite, curated set of cards belongs together under a labelled heading and reads as a horizontal swipeable rail — "Popular posts this week", "Recommended channels", "Hot companies right now". **Skip when** the collection is an open-ended scrolling stream of authored items (use [Feed](../feed/feed.md)), a vertical list of same-kind rows (use [List](../list/list.md)), or a channel directory that needs the channel-specific row chrome (use [SuggestionList](../suggestion-list/suggestion-list.md)). Pick the sub by the card shape: post cards → [Post](./post.md); profile / channel / company cards → [Profile](./profile.md).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell. The host pays **no** inline padding; 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`, reaching the trailing edge of the full-bleed surface. Do **not** wrap it 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).
+
+## Cross-sub contract
+
+### Header anatomy
+
+Every Carousel paints a [Header](../header/header.md) (`size="large"`) at the top:
+
+- **Label** *(required)* — `sys.typo.heading.md` / Semibold / `sys.color.onSurface`. Leading position.
+- **headerAction** *(optional)* — trailing [Text Button](../button/text.md) (`size={'xsmall'}`, `appearance={'accent'}`) per the link-affordance rule. Extends the header when there's an index page to route to.
+
+Carousel forwards `label` and `headerAction` to [Header](../header/header.md) verbatim; the header anatomy lives in Header's spec. Other hosts (in-sheet sub-sections, bounded cards, [SuggestionList](../suggestion-list/suggestion-list.md)) reach for `<Header />` directly — Carousel is the labelled-region host, Header the leading-row primitive it composes.
+
+### Surface + padding
+
+Both subs compose inside a single Carousel surface: `sys.color.surface` fill, `sys.layout.container.lg` block padding, **full-bleed inline** (no host inline padding — the Header pays the 16 inline rail and the pager re-pays it via `padding-left`), `sys.layout.stack.lg` between header and pager body. The sub itself paints no surface and no padding.
+
+### Pager geometry
+
+Both subs use the same pager: `scroll-snap-type: x mandatory`, `scroll-snap-align: start` on each card, leading `padding-left` = `sys.layout.container.md` (the 16 rail) with a matching `scroll-padding-left` snap anchor so page 1 lands on the rail, and — because the host is full-bleed — the pager reaches the trailing surface edge intrinsically (no negative margin), giving the guaranteed `ref.space.500` (40px) peek at the trailing edge.
+
+### Card count
+
+Each sub renders **at most 5 cards** — `items.slice(0, 5)`. Editorial / ops mistakes never blow out the carousel.
+
+## Sub-components
+
+- **[Post](./post.md)** — compact post cards for curated / priority placements.
+- **[Profile](./profile.md)** — fixed-shape profile cards for follow-able entities.

package/agents/components/carousel/post.md

@@ -0,0 +1,148 @@
+# Post
+
+Sub-component of the [Carousel](./carousel.md) family. Horizontally-scrolling pager of up to 5 compact post cards — surfaces curated popular posts or gives paid / verified accounts priority placement inside the [Post](../feed/post.md) feed column. The section heading and `See all` link live on the [Carousel](./carousel.md) wrapper — PostCarousel is the *content* only.
+
+**Reach for this when** spotlighting a small set (≤5) of curated or sponsored posts inside a feed column. **Skip when** the surface is a single feed stream ([Feed · Post](../feed/post.md)) or an entity directory ([List/entry](../list/entry.md)).
+
+**Layout inset.** full-bleed — sits as a direct child of the page shell (typically inside a [Carousel](./carousel.md)). The pager re-pays its own 16 left rail via `padding-left` (`sys.layout.container.md`) — the Carousel host is full-bleed — and the trailing card flushes to the page edge so the horizontal-scroll affordance reads cleanly; do **not** wrap it 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
+
+Carousel header (label only) above three cards with verified marks, follow actions, and pagination dots.
+
+```preview
+carousel/post-default
+---
+import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
+
+<Carousel label="Trending right now">
+<PostCarousel
+  items={[
+    {
+      avatar: { src: '/placeholder.png', alt: 'Channel' },
+      channel: 'Engineering',
+      verified: true,
+      followAction: true,
+      title: 'Which cushion brand still works on combo skin in summer?',
+      body: 'Slightly dehydrated combo skin — coverage is nice but not required. Anything that holds for a workday without sliding off? Pore-blurring a plus.',
+      mention: '@beauty, @skincare-talk',
+      views: '5K',
+    },
+    {
+      avatar: { src: '/placeholder.png', alt: 'Channel' },
+      channel: 'Compensation',
+      verified: true,
+      followAction: true,
+      title: 'L5 → L6 promo packet review — what worked, what nearly killed it',
+      body: 'I shipped two cross-team launches in the year, but my packet still came back with "scope of influence unclear" twice before it cleared. Sharing the rewrites.',
+      mention: '@career, @big-tech',
+      views: '12K',
+    },
+    {
+      avatar: { src: '/placeholder.png', alt: 'Channel' },
+      channel: 'Plant People',
+      verified: false,
+      followAction: true,
+      title: 'Monstera dropping aerial roots — repot or train?',
+      body: 'Two-year-old monstera, roots crawling out of the drainage holes. Light and watering are dialed in. Looking for the lazy-but-right answer.',
+      mention: '@plant-parents',
+      views: '3K',
+    },
+  ]}
+/>
+</Carousel>
+```
+
+## Use cases
+
+### With header action
+
+Extend the header with a trailing `accent` Text Button when there's an index page to route to. Lifts the `headerAction` prop on the `<Carousel>` wrapper.
+
+```preview
+carousel/post-with-header-action
+---
+import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
+
+<Carousel label="Trending right now" headerAction={{ label: 'See all', href: '#' }}>
+  <PostCarousel
+    items={[
+      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Engineering',  verified: true, followAction: true, title: 'The migration that finally landed after three quarters', body: 'Internal postmortem turned editorial — the scaffolding that held the rewrite together when the timeline did not.', mention: '@infra-talk', views: '14K' },
+      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Compensation', verified: true, followAction: true, title: 'Equity refresh negotiations — what actually moves',       body: 'A read on the conversations that get an actual refresh on the calendar versus the ones that get a polite no.',   mention: '@career',     views: '9K'  },
+      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Plant People', verified: false, followAction: true, title: 'Monstera dropping aerial roots — repot or train?',          body: 'Two-year-old monstera, roots crawling out of the drainage holes. Light and watering are dialed in.',              mention: '@plant-parents', views: '3K' },
+    ]}
+  />
+</Carousel>
+```
+
+### Editorial cards (no follow, no verified)
+
+Cards drop `verified` and `followAction` — each card's header collapses to avatar + channel name. Reach for it on editorial collections where the card is informational only (round-ups, archives, *what we're reading*); the surface should not invite a per-card commit.
+
+```preview
+carousel/post-editorial
+---
+import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
+
+<Carousel label="Editor picks">
+  <PostCarousel
+    items={[
+      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Career',       title: 'The quiet math of staying versus leaving',                body: 'Salary checks, offer evaluations, and the long thread that runs longer than any single conversation can.',                       views: '18K' },
+      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Compensation', title: 'Equity refresh negotiations — what actually moves',       body: 'A read on the conversations that get an actual refresh on the calendar versus the ones that get a polite no.',                     views: '9K'  },
+      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Engineering',  title: 'The migration that finally landed after three quarters', body: 'Internal postmortem turned editorial — the scaffolding that held the rewrite together when the timeline did not.',                 views: '14K' },
+    ]}
+  />
+</Carousel>
+```
+
+## Slots
+
+- **container** — wraps pager + pagination dots. No fill / padding — the surrounding [Carousel](../carousel/carousel.md) provides the chrome.
+- **pager** — horizontal scroll-snap track. `scroll-snap-type: x mandatory`; native scrollbar hidden.
+- **card** — one compact post card per page; outline-only surface.
+  - **avatar** — [Thumbnail](../thumbnail/thumbnail.md) `size={40}`, every prop (`src`, `alt`, `updateDot`, `logoBadge`) forwarded verbatim.
+  - **verified** *(optional)* — `VerifiedFillIcon` (`sys.icon.md`, `sys.color.primary`) to the LEFT of the channel name so the trust signal reads first.
+  - **channel** — channel / author name. `sys.typo.label.md` / Semibold / `sys.color.onSurface`.
+  - **followAction** *(optional)* — trailing [Text Button](../button/text.md) (`xsmall`). `accent` inactive (link-affordance) → `default` active (recedes). Same trailing-Text-Button shape as [List/entry](../list/entry.md)'s [attribution-row case](../list/entry.md#with-trailing-text-button-compact-attribution-row) — see the Behavior note below.
+  - **title** — `sys.typo.label.md` / Semibold / `sys.color.onSurface`. Single line, truncates.
+  - **body** — `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. Three-line clamp.
+  - **mention** *(optional)* — `sys.typo.body.sm` / `sys.color.primary` (not italic).
+  - **footer** — leading 'See more' [Text Button](../button/text.md) (`xsmall` / `secondary`) + trailing view count (`EyeIcon` + count `<span>`).
+- **pagination** — one dot per card; active `sys.color.onSurface`, rest `sys.color.outlineVariant`. Decorative (`aria-hidden`).
+
+## Anatomy
+
+| Slot              | Token bindings |
+|-------------------|----------------|
+| container         | No fill / padding — surrounding [Carousel](../carousel/carousel.md) provides chrome; `sys.layout.stack.md` pager→dots gap |
+| pager             | `gap: sys.layout.inline.md`, `padding-left: sys.layout.container.md` + `scroll-padding-left: sys.layout.container.md` (the 16 rail; full-bleed host → trailing edge reached intrinsically, no negative margin), `scroll-snap-type: x mandatory`, `scrollbar-width: none` |
+| card              | `flex: 0 0 calc(100% - sys.layout.inline.md - ref.space.500)`; `sys.color.surface` fill, `sys.radius.md`, `sys.borderWidth.hairline sys.color.outlineVariant` outline (inset box-shadow), `sys.layout.container.md` padding, `sys.layout.stack.sm` between blocks, `scroll-snap-align: start` |
+| header            | Row: avatar + verified mark + name + spacer + follow action; `align-items: center`; `sys.layout.inline.md` gap |
+| avatar / verified | [Thumbnail](../thumbnail/thumbnail.md) `size={40}` delegated verbatim · `VerifiedFillIcon` at `sys.icon.md` / `sys.color.primary` (resolves to `ref.palette.blue.500`), leading of the channel name |
+| channel / title   | `sys.typo.label.md`, `sys.color.onSurface`, single-line truncate |
+| body / mention    | `sys.typo.body.sm` / `sys.color.onSurfaceVariant` (three-line clamp) · mention in `sys.color.primary` |
+| followAction      | [Text Button](../button/text.md) `size={'xsmall'}`, `appearance={'accent'}` inactive → `appearance={'default'}` active; state tokens delegate to Text Button |
+| footer            | Row: leading 'See more' Text Button (`xsmall` / `secondary`) + trailing view count `<span>`; `justify-content: space-between` |
+| pagination dot    | 6 × 6, `sys.radius.full`; active `sys.color.onSurface`, inactive `sys.color.outlineVariant`; `sys.layout.inline.sm` row gap |
+
+## Sizes
+
+A single rung. The carousel stretches to its column width (`width: 100%`); on web a feed column typically caps at `comp-content-max`. Card basis is computed from the pager's inner width, so the peek width holds across breakpoints.
+
+## States
+
+Not itself interactive — commit lives in the header action, each card's follow action / more link, and any card-level `onClick`. Each follows its own spec's state contract. The carousel surface has no hover / pressed / focused treatment.
+
+## Focus indicator
+
+Inward — cards tile inside a horizontal scroll viewport with hairline outlines; an outward ring would collide with the next-card peek. Each focusable child paints its own ring per its spec.
+
+## Behavior
+
+- **Max 5 cards.** Items beyond index 4 are silently dropped (`items.slice(0, 5)`).
+- **Section header anatomy delegates to SuggestionList.** The *wrapper* header — label + headerAction — retunes at the [SuggestionList](../suggestion-list/suggestion-list.md) spec.
+- **Card header renders the shared `EntryRow`.** The avatar + optional verified mark + channel label + trailing follow [Text Button](../button/text.md) row pinned to the top of each *card* is **the same `EntryRow` atom that [List/entry](../list/entry.md) rows render** — not a look-alike, the literal shared component. The carousel passes `verified` (the inline `VerifiedFillIcon`, left of the label), a 40-rung `thumbnail`, and a `xsmall` follow Text Button (`accent` inactive → `default` active) into `EntryRow`'s trailing slot; the leading→label gap (12), identity column, and trailing-action pin all live on `EntryRow`. Only the surrounding card chrome (`chorus-post-carousel__card-header` wrapper) is carousel-specific. Retune the attribution shape on `EntryRow` / at [List/entry](../list/entry.md), not here.
+- **One card per page, scroll-snap.** `scroll-snap-type: x mandatory`; each card declares `scroll-snap-align: start`. The pager re-pays the 16 left rail via `padding-left` and, as a full-bleed child, reaches the trailing edge intrinsically so the peek isn't clipped.
+- **Guaranteed 40px peek.** Trailing-edge visibility of the next card pins to `ref.space.500` — raw ref step so the floor is fixed-pixel across breakpoints. Card basis is `calc(100% - sys.layout.inline.md - ref.space.500)`. After every swipe, the snapped card aligns flush with the container's left padding; the trailing edge always holds the 40px peek.
+- **Pagination dots are decorative.** Dots reflect scroll position via `IntersectionObserver`; tapping a dot does not scroll. Active dot paints `sys.color.onSurface`, the rest `sys.color.outlineVariant`.
+- **Cards route via `onClick`.** When an item carries `onClick`, the card surface becomes the click target; header (follow action) and footer (more link) intercept the tap so each routes independently.

package/agents/components/carousel/post.spec.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "PostCarousel",
+  "family": "carousel",
+  "subcomponent": "post",
+  "description": "Horizontally-scrolling pager of up to 5 compact post cards — sub-component of the [Carousel](./carousel.md) family. Used to surface a curated set of popular posts, or to give paid / verified accounts priority placement, inside the same scrolling feed column the default Feed card lives in. Editorial / ops control inserts a Carousel + PostCarousel pair between regular Feed cards based on placement policy. PostCarousel is the **content** — the section heading and trailing 'See all' link live on the [Carousel](./carousel.md) wrapper. Compose `<Carousel label='…' headerAction={…}><PostCarousel items={…} /></Carousel>`. The pager is a one-card-per-page horizontal scroll-snap track with a `ref.space.500` (40px) peek at the trailing edge inviting the swipe; pagination dots sit below the pager, one per card.",
+  "element": "div",
+  "props": {
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of up to 5 compact post cards. Each item: { id?, avatar, channel, verified?, followAction?, followed?, onFollowChange?, title, body, mention?, views, moreLabel?, onClick? }. Items beyond index 4 are dropped — the section enforces the 5-card maximum.",
+      "maxItems": 5
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Wraps the pager and pagination dots. `sys.layout.stack.md` pager→dots gap. No surface fill / padding of its own — the surrounding [Carousel](./carousel.md) provides the page-region chrome.",
+      "intrinsic": true
+    },
+    "pager": {
+      "required": true,
+      "description": "Horizontally-scrolling track of cards with `scroll-snap-type: x mandatory`; native scrollbar hidden. Re-pays the 16 left rail via `padding-left: sys.layout.container.md` (+ `scroll-padding-left`) now that the Carousel host is full-bleed; the pager spans the full surface width so the next-card peek reaches the trailing edge intrinsically (no negative margin).",
+      "intrinsic": true
+    },
+    "card": {
+      "required": true,
+      "description": "One compact post card per page. `flex: 0 0 calc(100% - sys.layout.inline.md - ref.space.500)` so a 40px peek of the next card always surfaces at the trailing edge. `scroll-snap-align: start`. Inner padding `sys.layout.container.md`, `sys.color.surface` fill, `sys.radius.md` corner, `sys.borderWidth.hairline` outline in `sys.color.outlineVariant`.",
+      "intrinsic": true
+    },
+    "header": {
+      "required": true,
+      "description": "Top row of the card: avatar (Thumbnail size 40) + channel name + optional VerifiedIcon (size sys.icon.md, sys.color.primary) + trailing follow affordance. Rendered by the **shared `EntryRow` atom** — the same component [List/entry](../list/entry.md) rows render — wrapped in a carousel-specific `chorus-post-carousel__card-header`. See `behavior.headerReusesEntryCombo`.",
+      "intrinsic": true
+    },
+    "avatar": {
+      "required": true,
+      "description": "Channel / author avatar — rendered by the [Thumbnail](../thumbnail/thumbnail.md) component at `size={40}`. Every Thumbnail prop (`src`, `alt`, `updateDot`, `logoBadge`) is forwarded verbatim. The carousel does not paint its own circular crop — Thumbnail owns the corner shape and the image-area fallback.",
+      "accepts": [
+        "thumbnail"
+      ],
+      "rendersAs": "thumbnail:40"
+    },
+    "verified": {
+      "required": false,
+      "description": "Inline `VerifiedFillIcon` at `sys.icon.md`, painted in `sys.color.primary` (resolves to `ref.palette.blue.500`). Sits to the **LEFT** of the channel name so the reader's eye lands on the trust signal first, then the name. Decorative — pair with a textual affordance elsewhere if the verified status itself is meaningful.",
+      "accepts": [
+        "icon"
+      ],
+      "defaultIcon": "VerifiedFillIcon",
+      "defaultIconColor": "sys.color.primary"
+    },
+    "channel": {
+      "required": true,
+      "description": "Channel / author name. `sys.typo.label.md` / Semibold / `sys.color.onSurface`. Single line; truncates. Sits to the right of the optional `verified` mark inside the channel-row sub-container.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "followAction": {
+      "required": false,
+      "description": "[Text Button](../button/text.md) (`size={'xsmall'}`) at the trailing edge of the card header — the trailing-Text-Button half of the [List/entry](../list/entry.md) attribution combo (see `behavior.headerReusesEntryCombo`). **Inactive** (`Follow`) uses `appearance={'accent'}` — the follow action is a navigation-shaped commit on the card, and the link-affordance rule applies. **Active** (`Following`) flips to `appearance={'default'}` so the followed state recedes into the body and the unfollowed alternative remains the visually loudest call. The carousel does not paint its own follow chrome — every state binding (rest, hover, pressed, focus) lives on the Text Button family.",
+      "accepts": [
+        "button"
+      ],
+      "rendersAs": "button:text:xsmall:accent (inactive) / button:text:xsmall:default (active)"
+    },
+    "title": {
+      "required": true,
+      "description": "Post title. `sys.typo.label.md` / Semibold / `sys.color.onSurface`. One line; truncates with ellipsis.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "body": {
+      "required": true,
+      "description": "Post excerpt. `sys.typo.body.sm` / Regular / `sys.color.onSurfaceVariant`. Three-line clamp with trailing ellipsis.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "mention": {
+      "required": false,
+      "description": "Tap-anywhere mention / tag line below the body. `sys.typo.body.sm` / `sys.color.primary` (no italic — the carousel card reads tags as part of its body block, unlike the Feed · Post card which italicises a single mention).",
+      "accepts": [
+        "text"
+      ]
+    },
+    "footer": {
+      "required": true,
+      "description": "Bottom row: leading `more` affordance + trailing view count. The 'See more' label renders as a [Text Button](../button/text.md) (`size={'xsmall'}`, `appearance={'secondary'}`) — same family as the card-header follow action — so both card affordances share one state contract. The view count renders as a non-interactive `<span>` matching the same `xsmall` rhythm (`EyeIcon` at `sys.icon.md` + `sys.typo.label.sm` / `sys.color.onSurfaceVariant`).",
+      "intrinsic": true
+    },
+    "pagination": {
+      "required": true,
+      "description": "Row of dots below the pager — one per card. Active dot paints `sys.color.onSurface`, the rest paint `sys.color.outlineVariant`. Decorative (`aria-hidden`); the active index updates from the pager's scroll position via IntersectionObserver.",
+      "intrinsic": true
+    }
+  },
+  "sizing": {
+    "containerFill": "none — provided by surrounding Carousel",
+    "containerPadding": "none — provided by surrounding Carousel",
+    "pagerToPaginationGap": "sys.layout.stack.md",
+    "pageGap": "sys.layout.inline.md",
+    "pagePeek": "ref.space.500",
+    "pagePeekNote": "Guaranteed minimum visibility of the next card at the trailing edge. Pinned to `ref.space.500` (40px) — a raw ref step rather than a responsive sys-layout rung — because the carousel wants a fixed-pixel visibility floor independent of the responsive sys-layout shift. The card's flex-basis is `calc(100% - sys.layout.inline.md - ref.space.500)`, so the inter-card gap plus the peek subtract from the pager's inline space in lock-step.",
+    "pageSnapAnchor": "Cards stick to the leading edge of the pager (the pager's own `padding-left: sys.layout.container.md`, the 16 rail). `scroll-snap-align: start` on each card plus the pager's `scroll-padding-left: sys.layout.container.md` together guarantee that, after every swipe, the snapped card aligns flush with the 16 rail — and the trailing edge holds the 40px peek of the next card.",
+    "cardFill": "sys.color.surface",
+    "cardOutline": "sys.borderWidth.hairline sys.color.outlineVariant",
+    "cardRadius": "sys.radius.md",
+    "cardPadding": "sys.layout.container.md",
+    "cardStackGap": "sys.layout.stack.sm",
+    "cardHeaderGap": "sys.layout.inline.md",
+    "cardAvatarSize": 40,
+    "cardAvatarRendersAs": "Thumbnail at size 40 — the carousel does not paint its own circular crop or fallback; both come from the Thumbnail family.",
+    "cardChannelTypo": "sys.typo.label.md",
+    "cardChannelColor": "sys.color.onSurface",
+    "cardVerifiedIcon": "VerifiedFillIcon",
+    "cardVerifiedSize": "sys.icon.md",
+    "cardVerifiedColor": "sys.color.primary",
+    "cardVerifiedColorResolved": "ref.palette.blue.500",
+    "cardVerifiedPosition": "Leading — sits to the LEFT of the channel name inside the channel-row sub-container.",
+    "cardFollowActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' (inactive — link-affordance rule) → appearance='default' (active — followed state recedes). All state tokens delegate to the Text Button family.",
+    "cardMoreActionRendersAs": "Button variant='text' size='xsmall' appearance='secondary'. Same Text Button rung as the follow action so the card's two affordances share one state contract.",
+    "cardTitleTypo": "sys.typo.label.md",
+    "cardTitleColor": "sys.color.onSurface",
+    "cardBodyTypo": "sys.typo.body.sm",
+    "cardBodyColor": "sys.color.onSurfaceVariant",
+    "cardBodyLineClamp": 3,
+    "cardMentionTypo": "sys.typo.body.sm",
+    "cardMentionColor": "sys.color.primary",
+    "cardFooterTypo": "sys.typo.label.sm",
+    "cardFooterColor": "sys.color.onSurfaceVariant",
+    "cardFooterIcon": "EyeIcon",
+    "cardFooterIconSize": "sys.icon.md",
+    "paginationDotSize": "ref.space.75",
+    "paginationDotGap": "sys.layout.inline.sm",
+    "paginationActiveColor": "sys.color.onSurface",
+    "paginationInactiveColor": "sys.color.outlineVariant"
+  },
+  "itemProps": {
+    "id": {
+      "type": "string",
+      "optional": true
+    },
+    "avatar": {
+      "type": "object",
+      "required": true,
+      "description": "Forwarded to Thumbnail verbatim at size 40."
+    },
+    "channel": {
+      "type": "string",
+      "required": true
+    },
+    "verified": {
+      "type": "boolean",
+      "default": false
+    },
+    "followAction": {
+      "type": "boolean",
+      "default": false
+    },
+    "followed": {
+      "type": "boolean",
+      "default": false
+    },
+    "onFollowChange": {
+      "type": "function",
+      "optional": true
+    },
+    "title": {
+      "type": "string",
+      "required": true
+    },
+    "body": {
+      "type": "string",
+      "required": true
+    },
+    "mention": {
+      "type": "string",
+      "optional": true
+    },
+    "views": {
+      "type": "string",
+      "required": true
+    },
+    "moreLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Trailing 'see more' label in the card footer. Defaults to 'See more'."
+    },
+    "onClick": {
+      "type": "function",
+      "optional": true
+    }
+  },
+  "states": {
+    "note": "Container has no interactive state. Each card's commit affordances (the optional follow action, the 'see more' link) follow their own state contracts. The card body is presentational by default — pass `onClick` on an item to route the entire card."
+  },
+  "focusIndicator": {
+    "description": "PostCarousel itself is not a focus target. Each focusable child (header action, card follow action, card body when `onClick` is wired) paints its own ring per its own spec. Cards tile horizontally in a scroll viewport; the Inward composition is preferred for any card-level ring so the stroke does not collide with the next-card peek.",
+    "composition": "inward",
+    "trigger": ":focus-visible"
+  },
+  "behavior": {
+    "maxFiveCards": "PostCarousel renders at most five cards. Items beyond index 4 are silently dropped — `items.slice(0, 5)` — so editorial / ops mistakes never blow out the section.",
+    "headerDelegatesToSuggestionList": "The *wrapper* (section) header's anatomy (label + optional trailing text-link action) is the same contract as [SuggestionList](../suggestion-list/suggestion-list.md). Bindings stay in lock-step — retune at the SuggestionList spec, not here.",
+    "headerReusesEntryCombo": "The *card* header renders the **shared `EntryRow` atom** (`packages/ui/src/EntryRow.jsx`, class `chorus-entry-row`) — the same component each [List/entry](../list/entry.md) row renders, not a look-alike. The carousel passes `verified` (inline VerifiedFillIcon, LEFT of the label), a 40-rung `thumbnail`, and a `xsmall` follow Text Button (`accent` inactive → `default` active) into EntryRow's trailing slot. The leading→label gap (12), identity column, and trailing-action pin live on EntryRow; only the `chorus-post-carousel__card-header` wrapper is carousel-specific. Retune the attribution shape on EntryRow / at List/entry, not here.",
+    "horizontalScrollSnap": "scroll-snap-type: x mandatory; each card declares scroll-snap-align: start.",
+    "nextCardPeek": "The Carousel host is full-bleed, so the pager spans the full surface width and reaches the trailing edge intrinsically (no negative margin); it re-pays the 16 left rail via `padding-left: sys.layout.container.md`. Card basis composes the inter-card gap (`sys.layout.inline.md`) plus the visible peek (`ref.space.500`, 40px) into one calc — a minimum of 40px of the next card is guaranteed to remain visible at the trailing edge whenever a card is snapped to the leading edge. The peek is pinned to a raw ref step rather than a responsive sys-layout rung so the visibility floor is fixed-pixel and does not shift at the responsive breakpoint.",
+    "stickyToLeadingPadding": "After every swipe, the snapped card aligns flush with the pager's left padding (the 16 rail) — it 'sticks' to the leading edge of the pager. `scroll-snap-align: start` plus the pager's `scroll-padding-left: sys.layout.container.md` together produce this behavior. The trailing edge of the same snap state always holds the 40px peek of the next card; the two are one geometry contract, not two independent rules.",
+    "paginationDecorative": "Dots are decorative (`aria-hidden`). They reflect the scroll position only; tapping a dot does not scroll. Active state updates via IntersectionObserver on the pager's snap targets.",
+    "cardClickRoutes": "When an item carries `onClick`, the card surface becomes the click target. Header affordances (follow action) and footer affordances (more link) intercept the tap so each can route independently.",
+    "insertionPolicy": "Editorial / ops control inserts the carousel between regular Feed cards according to placement policy — the component does not own that decision."
+  },
+  "accessibility": {
+    "region": "the pager is a labelled scroll region: it carries role='group' (or 'region') with aria-roledescription='carousel' and aria-label wired to the Carousel wrapper's `label` (aria-labelledby pointing at the wrapper heading) so assistive tech announces it as a named carousel, not an unlabelled scroll box.",
+    "keyboardReach": "Because the pagination dots are decorative and non-interactive, the cards on pages 2+ MUST stay reachable another way: each card's focusable contents (card onClick target, follow / more actions) are in the natural tab order, and focusing an off-screen card scrolls it into the viewport (scroll-into-view on :focus). Without this, swipe is the only way to reach later cards and the carousel is keyboard-inaccessible.",
+    "paginationHidden": "The dots are aria-hidden (presentational position indicator only) — see behavior.paginationDecorative.",
+    "perCardName": "Each card exposes its own accessible name via its heading / author so the tab stop is announced meaningfully, not as a bare 'link'."
+  },
+  "forbidden": [
+    "card outline painted as a raw `border:` — outline is an inset box-shadow on the card",
+    "later cards reachable by swipe only — focusing an off-screen card MUST scroll it into view so a keyboard user can reach every card",
+    "Carousel heading composed inside the carousel — header + see-all link live on the Carousel wrapper, never on the carousel itself",
+    "card width altered from the spec'd footprint — every post card paints the same width regardless of card count"
+  ]
+}