@teamblind-chorus/ui 1.0.0

package/agents/components/carousel/profile.md

@@ -0,0 +1,184 @@
+# Profile
+
+Sub-component of the [Carousel](./carousel.md) family. Horizontally-scrolling rail of fixed-width (176px) profile cards — channels, user profiles, or company channels grouped under a single editorial heading. Each card carries a cover band, an overlapping 64-rung avatar, entity name + follower count, a metrics row or two-line description, and a trailing follow [Toggle Button](../button/text.md).
+
+**Reach for this when** an editorial collection groups follow-able entities under a single heading — hot companies, recommended channels, suggested people. **Skip when** the rail carries content posts ([Post carousel](./post.md)), the surface needs the full list scanned vertically ([SuggestionList](../suggestion-list/suggestion-list.md) / [DirectoryList](../directory-list/directory-list.md)), or the rung is a label-only nav strip ([AvatarRail](../avatar-rail/avatar-rail.md)).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell so the rail can bleed off the trailing edge into the swipe zone. The pager re-pays its own `16px` left rail via `padding-left` (`sys.layout.container.md`) — the Carousel host is full-bleed; 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
+
+Three profile cards under a Carousel heading (label only).
+
+```preview
+carousel/profile-default
+---
+import { Carousel, ProfileCarousel } from '@teamblind-chorus/ui';
+
+<Carousel label="Hot companies right now">
+  <ProfileCarousel
+    items={[
+      {
+        avatar: { src: '/placeholder.png', alt: 'Amazon' },
+        name: 'Amazon',
+        followers: '1,678 followers',
+        metrics: [
+          { icon: 'star', value: '4.1' },
+          { icon: 'pulse', value: '81.1' },
+          { icon: 'heart', value: '81%' },
+        ],
+      },
+      {
+        avatar: { src: '/placeholder.png', alt: 'Tesla' },
+        name: 'Tesla',
+        followers: '1.4K followers',
+        metrics: [
+          { icon: 'star', value: '4.7' },
+          { icon: 'pulse', value: '86' },
+          { icon: 'heart', value: '85.3%' },
+        ],
+        followed: true,
+      },
+      {
+        avatar: { src: '/placeholder.png', alt: 'Stripe' },
+        name: 'Stripe',
+        followers: '2.1K followers',
+        metrics: [
+          { icon: 'star', value: '4.5' },
+          { icon: 'pulse', value: '92.4' },
+          { icon: 'heart', value: '88%' },
+        ],
+      },
+    ]}
+  />
+</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/profile-with-header-action
+---
+import { Carousel, ProfileCarousel } from '@teamblind-chorus/ui';
+
+<Carousel label="Hot companies right now" headerAction={{ label: 'See all', href: '#' }}>
+  <ProfileCarousel
+    items={[
+      {
+        avatar: { src: '/placeholder.png', alt: 'Amazon' },
+        name: 'Amazon',
+        followers: '1,678 followers',
+        metrics: [
+          { icon: 'star', value: '4.1' },
+          { icon: 'pulse', value: '81.1' },
+          { icon: 'heart', value: '81%' },
+        ],
+      },
+      {
+        avatar: { src: '/placeholder.png', alt: 'Tesla' },
+        name: 'Tesla',
+        followers: '1.4K followers',
+        metrics: [
+          { icon: 'star', value: '4.7' },
+          { icon: 'pulse', value: '86' },
+          { icon: 'heart', value: '85.3%' },
+        ],
+        followed: true,
+      },
+      {
+        avatar: { src: '/placeholder.png', alt: 'Stripe' },
+        name: 'Stripe',
+        followers: '2.1K followers',
+        metrics: [
+          { icon: 'star', value: '4.5' },
+          { icon: 'pulse', value: '92.4' },
+          { icon: 'heart', value: '88%' },
+        ],
+      },
+    ]}
+  />
+</Carousel>
+```
+
+### With description
+
+The metrics row swaps out for a two-line description. Use for editorial collections where the value of each profile is best explained in copy (channel topic, hot pitch) rather than numeric signals. The description block is fixed to the same two-line height as the metrics row, so cards stay flush across both modes even when description copy clamps with an ellipsis.
+
+```preview
+carousel/profile-with-description
+---
+import { Carousel, ProfileCarousel } from '@teamblind-chorus/ui';
+
+<Carousel label="Recommended channels">
+  <ProfileCarousel
+    items={[
+      {
+        avatar: { src: '/placeholder.png', alt: 'Engineering' },
+        name: 'Engineering',
+        followers: '12.4K followers',
+        description: 'Hands-on threads about systems, infra, and the work behind the launch.',
+      },
+      {
+        avatar: { src: '/placeholder.png', alt: 'Compensation' },
+        name: 'Compensation',
+        followers: '8.1K followers',
+        description: 'Salary checks, offer evaluations, and the quiet math of staying versus leaving — the channel that runs longer than any single conversation can.',
+        followed: true,
+      },
+      {
+        avatar: { src: '/placeholder.png', alt: 'Career' },
+        name: 'Career',
+        followers: '5.3K followers',
+        description: 'Promotion packets, scope debates, and the rewrites that actually cleared.',
+      },
+    ]}
+  />
+</Carousel>
+```
+
+## Slots
+
+- **container** — wraps the pager and pagination dots. No fill / padding — the surrounding [Carousel](./carousel.md) provides the chrome.
+- **pager** — horizontal scroll-snap track. `scroll-snap-type: x mandatory`; native scrollbar hidden.
+- **card** — one profile card per page; fixed at **176px** wide.
+  - **cover** — top band; 88px tall image-area slot. Renders an `<img>` defaulting to `/placeholder.png` (universal Chorus placeholder). `object-fit: cover` crops to fill the band; `sys.color.surfaceContainerHigh` underlies as the no-image fallback. Consumers override via `items[i].cover.src`.
+  - **avatar** — [Thumbnail](../thumbnail/thumbnail.md) `size={64}` with [`outlined={true}`](../thumbnail/thumbnail.md#with-surface-outline), centered and overlapping the cover band's bottom edge. The 2-token (`sys.borderWidth.thin`) `surface`-tone outset halo separating the circle from the cover image is owned by Thumbnail's outlined case — the carousel forwards the prop instead of painting a halo on its own wrapper.
+  - **name** — entity name; `sys.typo.label.md` / Semibold / `sys.color.onSurface`; centered, single line truncate.
+  - **followers** — follower count; `sys.typo.label.sm` / `sys.color.onSurfaceVariant`; centered.
+  - **metrics** *(optional)* — row of `icon + value` chips: `star → StarFillIcon (sys.color.icon.yellow)`, `pulse → PulseFillIcon (sys.color.success)`, `heart → HeartFillIcon (sys.color.icon.red)`. Mutually exclusive with `description`.
+  - **description** *(optional)* — two-line clamped paragraph that replaces the metrics row when present. Block height fixed to two lines of `sys.typo.label.sm` regardless of copy length, so card height stays consistent across metrics-carrying and copy-carrying cards.
+  - **followAction** — full-width [Toggle Button](../button/text.md) (`variant={'toggle'}`); `Follow` (inactive) / `Following` (active).
+- **pagination** — one dot per card. Active dot paints `sys.color.onSurface`; rest paint `sys.color.outlineVariant`. Decorative.
+
+## Anatomy
+
+| Slot           | Token bindings |
+|----------------|----------------|
+| 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` |
+| card           | Fixed `width: 176px`, `sys.color.surface` fill, `sys.radius.md`, inset hairline outline, `scroll-snap-align: start` |
+| cover          | 88px tall image-area slot. Default `src` = `/placeholder.png` (universal image placeholder), `object-fit: cover`, `sys.color.surfaceContainerHigh` underlay |
+| avatar         | [Thumbnail](../thumbnail/thumbnail.md) `size={64}` `outlined`, vertical center on cover's bottom edge. The 2-token `surface`-tone halo separating the circle from the cover image is painted by Thumbnail's `outlined` case (outset `box-shadow: 0 0 0 sys.borderWidth.thin sys.color.surface`) — wrapper has no halo of its own |
+| name           | `sys.typo.label.md`, `sys.color.onSurface`, centered |
+| followers      | `sys.typo.label.sm`, `sys.color.onSurfaceVariant`, centered |
+| metrics row    | `sys.layout.inline.md` gap, centered. Fixed-height slot — `calc(sys.typo.label.sm.size * sys.typo.label.sm.line * 2)` so the row always reserves two lines of `label.sm` regardless of content. |
+| metric chip    | `sys.icon.md` glyph + `sys.typo.label.sm` value; star → `StarFillIcon` (`sys.color.icon.yellow`), pulse → `PulseFillIcon` (`sys.color.success`), heart → `HeartFillIcon` (`sys.color.icon.red`) |
+| description    | `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, centered, two-line clamp with trailing ellipsis. Two-layer DOM — outer container owns the same fixed-height slot as `metrics row` (min/max-height = 2 label.sm lines); inner `<p>` owns the `-webkit-line-clamp: 2` truncation. Split sidesteps a Chrome quirk where `display: -webkit-box` and explicit `height` on one element break the third-line clip. |
+| followAction   | [Toggle Button](../button/text.md) (Chip-toggle anatomy), stretched to full card width |
+| pagination dot | 6×6, `sys.radius.full`; active `sys.color.onSurface`, inactive `sys.color.outlineVariant` |
+
+## States
+
+ProfileCarousel is not itself interactive — commit lives in each card's Toggle Button follow affordance (and the optional card-level `onClick`). Each follows its own spec's state contract.
+
+## Behavior
+
+- **Max 5 cards.** Items beyond index 4 are silently dropped.
+- **Fixed 176px card width.** Cards do not reflow to the viewport — the rail always paints the same footprint and scrolls horizontally.
+- **Header lives on Carousel.** ProfileCarousel does not paint its own section heading or 'See all' link.
+- **Sticks to the pager's left padding on swipe.** Same geometry contract as [Post carousel](./post.md) — `scroll-snap-align: start` + the pager's `scroll-padding-left` (the 16 rail).
+- **Guaranteed 40px peek.** A minimum of `ref.space.500` (40px) of the next card is always visible at the trailing edge.
+- **Follow toggle commits in place.** Tapping `Follow` flips the card's Toggle Button to `Following` and stays there. Consumer owns state via `items[i].followed` + `onFollowChange`.

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

@@ -0,0 +1,219 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "ProfileCarousel",
+  "family": "carousel",
+  "subcomponent": "profile",
+  "description": "Horizontally-scrolling rail of profile-style cards — sub-component of the [Carousel](./carousel.md) family. Each card is a fixed-shape profile module (cover band + centered overlapping avatar + name + followers + metric row + Toggle-Button follow), used to surface channels, user profiles, or company channels in a curated editorial collection. The 'profile-card' shape names what the carousel actually carries — every card is a follow-able profile, regardless of whether the entity is a community channel, an individual user, or a company. Composed inside a [Carousel](./carousel.md) wrapper that owns the editorial heading and the optional 'See all' link. The pager geometry mirrors [Post carousel](./post.md) — same `ref.space.500` (40px) trailing peek, same leading-padding sticky anchor — so editorial collections of posts and profiles read as one family.",
+  "element": "div",
+  "props": {
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of profile-card descriptors. Each item: { id?, avatar, cover?, name, followers, metrics?, description?, followed?, onFollowChange?, followLabel?, followingLabel?, onClick? }. `metrics` and `description` are mutually exclusive — when `description` is present, it replaces the metrics row. Items beyond index 4 are dropped — the rail enforces a hard 5-card maximum.",
+      "maxItems": 5
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Wraps the pager and pagination dots. No fill / padding of its own — the surrounding [Carousel](./carousel.md) provides the page-region chrome.",
+      "intrinsic": true
+    },
+    "pager": {
+      "required": true,
+      "description": "Horizontal scroll-snap track. `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 profile card per page. **Width is fixed at 176px** — every card paints the same footprint regardless of how many entries the rail carries. Vertical stack: cover band → avatar (overlapping) → name → followers → metrics row → follow toggle. `sys.color.surface` fill, `sys.radius.md` corner, `sys.borderWidth.hairline sys.color.outlineVariant` inset outline. `scroll-snap-align: start`.",
+      "intrinsic": true
+    },
+    "cover": {
+      "required": true,
+      "description": "Cover band at the top of the card — 88px tall, full card width. **Image-area slot, same contract as `.chorus-thumbnail` and `.chorus-feed-ad__media`**: a `<img>` paints the band, falling back to the universal Chorus placeholder PNG (`/placeholder.png`) when no `cover.src` is provided. The placeholder is *also* wired as the runtime CSS `background-image` on the band, so a missing/failed `<img>` still resolves to the placeholder rather than an empty surface tone. The image is `object-fit: cover` — aspect ratio preserved, cropped to fill — so the lowercase 'blind' wordmark centered in the placeholder stays visually centered in the band.",
+      "assetType": "image",
+      "placeholder": "/placeholder.png",
+      "intrinsic": true
+    },
+    "avatar": {
+      "required": true,
+      "description": "Centered circular avatar overlapping the cover band's bottom edge. Renders via the [Thumbnail](../thumbnail/thumbnail.md) component at `size={64}` with `outlined={true}` — the 2-token (`sys.borderWidth.thin`) `surface`-tone halo that separates the avatar from the cover image is owned by Thumbnail's outlined case (see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline)), not by the carousel's own wrapper. Every other Thumbnail prop is forwarded verbatim; the carousel does not paint its own crop or image-area fallback.",
+      "accepts": [
+        "thumbnail"
+      ],
+      "rendersAs": "thumbnail:64 (outlined)"
+    },
+    "name": {
+      "required": true,
+      "description": "Entity name (channel / profile / company). `sys.typo.label.md` / Semibold / `sys.color.onSurface`. Centered; single line, truncates with ellipsis.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "followers": {
+      "required": true,
+      "description": "Follower count line. `sys.typo.label.sm` / Semibold / `sys.color.onSurfaceVariant`. Centered; single line.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "metrics": {
+      "required": false,
+      "description": "Row of metric chips below the name / followers stack. Each chip is `icon + value` painted in `sys.typo.label.sm` / `sys.color.onSurface`. Three default kinds: { icon: 'star', … } → `StarFillIcon` in `sys.color.icon.yellow`; { icon: 'pulse', … } → `PulseFillIcon` in `sys.color.success`; { icon: 'heart', … } → `HeartFillIcon` in `sys.color.icon.red`. Consumers may pass custom { icon: <ReactNode>, value, color? } entries for other shapes. Mutually exclusive with `description` — when both are present `description` wins.",
+      "intrinsic": true
+    },
+    "description": {
+      "required": false,
+      "description": "Two-line clamped descriptive paragraph that replaces the metrics row when present. `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, centered. The slot reserves a fixed height of two `label.sm` lines so card height stays consistent across cards that carry metrics and cards that carry copy — extra content clamps with a trailing ellipsis.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "followAction": {
+      "required": true,
+      "description": "Trailing full-width [Toggle Button](../button/text.md) at the foot of the card. `Follow` (inactive) → `Following` (active). The carousel does not paint its own follow chrome — every state binding lives on the Toggle Button (Chip-toggle) contract, which paints `sys.color.primary` while inactive and a `transparent` fill with a hairline outline while active so the followed state recedes against the card's own `surface` tier without re-painting a tone that would clash.",
+      "accepts": [
+        "button"
+      ],
+      "rendersAs": "button:toggle (full-width inside card)"
+    },
+    "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": {
+    "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 40px (ref.space.500). Identical contract to PostCarousel.",
+    "pageSnapAnchor": "Cards stick to the leading edge of the pager (the pager's own `padding-left`, the 16 rail). `scroll-snap-align: start` plus the pager's `scroll-padding-left: sys.layout.container.md` produce this anchor.",
+    "cardFill": "sys.color.surface",
+    "cardOutline": "sys.borderWidth.hairline sys.color.outlineVariant",
+    "cardOutlineComposition": "overlay",
+    "cardOutlineCompositionNote": "Painted on a dedicated `::after` overlay layer (`position: absolute; inset: 0; z-index: 2; pointer-events: none`), not as an inset `box-shadow` on the card box itself. The card hosts an opaque full-bleed cover band at the top; an inset shadow on the card would be masked by that fill at the top edge. Same overlay idiom DESIGN.md prescribes for the focus ring — so the stroke renders above every child regardless of edge-painting content.",
+    "cardRadius": "sys.radius.md",
+    "cardWidth": "176px",
+    "cardWidthNote": "Fixed pixel width — every profile card paints the same 176px footprint regardless of card count or screen width. The pager scrolls horizontally so the 176px footprint never reflows.",
+    "cardStackGap": "sys.layout.stack.sm",
+    "coverHeight": "88px",
+    "coverFill": "sys.color.surfaceContainerHigh (background underlay — the placeholder image paints on top via `object-fit: cover`)",
+    "coverImageSource": "Same `/placeholder.png` asset every Chorus image-area slot falls back to. Cropped to fill the 88px band via `object-fit: cover` — the placeholder's centered 'blind' wordmark stays visually centered. Decorative — `aria-hidden`. Consumers can override per-item via `items[i].cover.src` (any image URL preserving the same `object-fit: cover` crop).",
+    "avatarSize": 64,
+    "avatarOverlap": "Avatar's vertical center sits on the cover band's bottom edge — the bottom half of the avatar bleeds onto the card surface. The 2-token (`sys.borderWidth.thin`) `sys.color.surface` halo separating the avatar from the cover band is owned by Thumbnail's `outlined={true}` case (see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline)) — outset `box-shadow`, not a wrapper border. Same contract as ProfileHeader's avatar.",
+    "nameTypo": "sys.typo.label.md",
+    "nameColor": "sys.color.onSurface",
+    "followersTypo": "sys.typo.label.sm",
+    "followersColor": "sys.color.onSurfaceVariant",
+    "metricsRowGap": "sys.layout.inline.md",
+    "metricChipTypo": "sys.typo.label.sm",
+    "metricChipColor": "sys.color.onSurface",
+    "metricIconSize": "sys.icon.md",
+    "metricIconStar": "StarFillIcon — sys.color.icon.yellow",
+    "metricIconPulse": "PulseFillIcon — sys.color.success",
+    "metricIconHeart": "HeartFillIcon — sys.color.icon.red",
+    "midSlotHeight": "calc(sys.typo.label.sm.size * sys.typo.label.sm.line * 2)",
+    "midSlotHeightNote": "Shared fixed height for the metrics row and the description slot — exactly two `label.sm` lines (12 × 1.5 × 2 ≈ 36px). Cards that carry metrics and cards that carry a description paint the same outer height.",
+    "descriptionTypo": "sys.typo.label.sm",
+    "descriptionColor": "sys.color.onSurfaceVariant",
+    "descriptionLineClamp": 2,
+    "descriptionOverflow": "Two-line clamp with trailing ellipsis; copy exceeding two lines truncates so the slot height stays fixed.",
+    "followActionRendersAs": "Button variant='toggle' — Chip-toggle anatomy. Stretched to full card width via a wrapper rule. All state tokens delegate to the Toggle Button (Chip) family.",
+    "cardPaddingBlock": "sys.layout.stack.sm",
+    "cardPaddingInline": "sys.layout.container.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 64."
+    },
+    "cover": {
+      "type": "object",
+      "optional": true,
+      "description": "{ src?, alt? } — image-area override for the cover band. `src` accepts any URL; falls back to `/placeholder.png` (the universal Chorus image-area placeholder) when omitted. The slot is image-typed (same contract as `Thumbnail.src` / `FeedAd.media.src`) — `object-fit: cover` preserves aspect ratio and crops to the band's intrinsic 88px height."
+    },
+    "name": {
+      "type": "string",
+      "required": true
+    },
+    "followers": {
+      "type": "string",
+      "required": true
+    },
+    "metrics": {
+      "type": "node",
+      "optional": true,
+      "description": "Array of { icon, value, color? } where `icon` is one of 'star' | 'pulse' | 'heart' or a custom ReactNode. Mutually exclusive with `description` — when both are passed, `description` wins."
+    },
+    "description": {
+      "type": "string",
+      "optional": true,
+      "description": "Two-line clamped paragraph that replaces the metrics row. Fixed-height slot — extra copy ellipsizes."
+    },
+    "followed": {
+      "type": "boolean",
+      "default": false
+    },
+    "onFollowChange": {
+      "type": "function",
+      "optional": true
+    },
+    "followLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Inactive label. Defaults to 'Follow'."
+    },
+    "followingLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Active label. Defaults to 'Following'."
+    },
+    "onClick": {
+      "type": "function",
+      "optional": true
+    }
+  },
+  "states": {
+    "note": "ProfileCarousel is not itself interactive — commit lives in each card's Toggle Button follow affordance and the optional card-level `onClick`. Each follows its own spec's state contract."
+  },
+  "focusIndicator": {
+    "description": "ProfileCarousel is not a focus target. Each focusable child (Toggle Button follow, card body when `onClick` is wired) paints its own ring per its spec. Cards tile inside a horizontal scroll viewport; the Inward composition is preferred so the stroke does not collide with the next-card peek.",
+    "composition": "inward",
+    "trigger": ":focus-visible"
+  },
+  "behavior": {
+    "maxFiveCards": "ProfileCarousel renders at most five cards — `items.slice(0, 5)`. Editorial / ops mistakes never blow out the rail.",
+    "headerLivesOnCarousel": "ProfileCarousel does not paint its own section heading or 'See all' link — those live on the [Carousel](./carousel.md) wrapper. Compose `<Carousel label='…' headerAction={…}><ProfileCarousel items={…} /></Carousel>`.",
+    "fixedCardWidth": "Every profile card paints a fixed 176px footprint — the carousel never reflows the card to fit the available inline width. The trailing peek (`ref.space.500`, 40px) of the next card is always visible regardless of viewport.",
+    "horizontalScrollSnap": "scroll-snap-type: x mandatory; each card declares scroll-snap-align: start.",
+    "stickyToLeadingPadding": "After every swipe, the snapped card aligns flush with the pager's left padding (the 16 rail) — same geometry contract as PostCarousel.",
+    "paginationDecorative": "Dots are decorative; tapping a dot does not scroll. Active state updates via IntersectionObserver on the snap targets.",
+    "followToggleCommitsInPlace": "Tapping Follow flips the card's Toggle Button to Following and stays there. State is owned by the consumer via items[i].followed + onFollowChange.",
+    "cardClickRoutes": "When an item carries `onClick`, the card surface becomes the click target. The follow toggle intercepts the tap so it routes independently."
+  },
+  "accessibility": {
+    "region": "the pager is a labelled scroll region: role='group' (or 'region') with aria-roledescription='carousel' and aria-label wired to the Carousel wrapper's `label` (aria-labelledby on the wrapper heading), so assistive tech announces a named carousel rather than an unlabelled scroll box.",
+    "keyboardReach": "Dots are decorative, so cards on pages 2+ MUST stay reachable: each card's focusable contents (card onClick target, follow Toggle Button) 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.",
+    "paginationHidden": "The dots are aria-hidden (presentational position indicator only) — see behavior.paginationDecorative.",
+    "perCardName": "Each card exposes its own accessible name via the profile name so the tab stop is announced meaningfully."
+  },
+  "forbidden": [
+    "card outline painted as a raw `border:` — outline is an `::after` overlay layer because the card hosts a full-bleed cover band",
+    "later cards reachable by swipe only — focusing an off-screen card MUST scroll it into view so a keyboard user can reach every card",
+    "cover band painted as an inline SVG wordmark — cover uses /placeholder.png via the image-area contract, object-fit: cover",
+    "Carousel heading composed inside the carousel — header + see-all link live on the Carousel wrapper",
+    "metrics row mixed with description in the same card — the spec declares them mutually exclusive (description replaces metrics when present)",
+    "fixed 176px card width altered — the carousel never reflows the card"
+  ]
+}

package/agents/components/chip/chip.family.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "chip",
+  "name": "Chip",
+  "description": "Compact capsule control family. `filter` is a selectable toggle chip used for facet selection; `tag` is an informational chip used for metadata badges and dismissable opt-outs. The two share the capsule footprint but diverge on radius, tone, and intent.",
+  "useCases": [
+    "facet selection",
+    "filter toggle",
+    "tag",
+    "metadata pill",
+    "dismissable opt-out"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "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.",
+  "spec": "chip.md",
+  "usage": {
+    "note": "Both forms are the single `Chip` export selected by the `variant` prop — there is NO `<FilterChip>` or `<Tag>` export.",
+    "subs": {
+      "filter": { "variant": "filter", "example": "<Chip variant=\"filter\" selected leadingIcon={<CheckedIcon />}>Selected</Chip>" },
+      "tag": { "variant": "tag", "example": "<Chip variant=\"tag\" trailingIcon={<XIcon />}>Newsletter</Chip>" }
+    }
+  },
+  "subcomponents": [
+    {
+      "slug": "filter",
+      "spec": "filter.spec.json",
+      "md": "filter.md",
+      "default": true
+    },
+    {
+      "slug": "tag",
+      "spec": "tag.spec.json",
+      "md": "tag.md"
+    }
+  ]
+}

package/agents/components/chip/chip.md

@@ -0,0 +1,10 @@
+# Chip
+
+A small, content-shaped control or label — chip-shaped affordance for two anchoring roles. **Filter** is the selectable, capsule-shaped choice the user toggles to refine a set (search filters, taxonomy switches, faceted lists). **Tag** is the static, square-cornered label naming attached metadata (categories on a card, attributes on a profile, opt-in/out tokens on a settings row). Each family carries its own slot vocabulary, geometry, and tone; the cross-family contract is limited to the shared label rung (12px Semibold, 4px block padding, 4px label-slot inset producing the visible icon-to-label rhythm) and the Chorus-wide color / state / focus tokens in [`DESIGN.md`](../../DESIGN.md). The two diverge on min-height and horizontal padding by role — **Filter** sits at 32 / 12 (tappable affordance, shared verbatim with [Toolbar Button](../button/toolbar.md) and [Tabs Segmented](../tabs/segmented.md)); **Tag** tightens to 24 / 8 (passive metadata that should not invite touch).
+
+**Layout inset.** `inline` — slot atom. A single Chip has no page-rail responsibility; the surrounding container places it (List row leading, Feed footer, FormField suffix). A Chip *group* — multiple Filter chips arranged as a filter rail — is rail-responsible: place the group as a direct child of the page shell (no `padding-inline` / `px-*` wrapper) and let its outer container pay the gutter once, so the first chip's leading edge aligns with section H2s and list-row leading content. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Sub-components
+
+- **[Filter](./filter.md)** — Selectable filter chip. Capsule (`radius.full`), `surfaceContainerHigh` raised tone with a hairline `outlineVariant` stroke at rest, swaps to an inverse fill when selected. Optional leading and trailing icons.
+- **[Tag](./tag.md)** — Informational tag chip. Square-cornered (`radius.sm`), `secondaryContainer` fill that sits one tonal step *below* the lifted Filter so the label reads as attached metadata rather than a tappable choice. Optional trailing icon only — typically the dismiss "×" for opt-out flows.