@teamblind-chorus/ui 1.0.0

package/agents/components/divider/divider.spec.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Divider",
+  "family": "divider",
+  "description": "Section-break band — a single full-bleed block painted with `sys.color.scrimSubtle` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) at a fixed block thickness of `sys.layout.stack.xs` (8). The translucent fill stays visible on every host surface tier, so the band reads as a region boundary whether it sits on plain page surface, an elevated container, a hero band, or a coloured card — without retoning per-host. No appearance axis, no thickness prop, no orientation prop: Divider ships one canonical band. The host paints no margin / padding / gap around it — the 8 of scrimSubtle IS the breathing.",
+  "element": "hr",
+  "props": {
+    "aria-hidden": {
+      "type": "boolean",
+      "optional": true,
+      "description": "Defaults to `true`. The band is decorative chrome — screen readers should not announce it as a thematic break. Override to `false` only when the divider genuinely marks a semantic section change (rare; prefer a heading instead)."
+    },
+    "className": {
+      "type": "string",
+      "optional": true,
+      "description": "Composes with the component's own class. Use sparingly — Divider exposes no tokens to override and any sizing / colour override breaks the surface-agnostic contract."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "The tonal band itself. `sys.color.scrimSubtle` fill, `sys.layout.stack.xs` (8) block thickness, full inline width, no inline padding, no corner radius, no border. The native `<hr>` element with all browser defaults reset (no margin, no border, no background-image).",
+      "intrinsic": true
+    }
+  },
+  "sizing": {
+    "background": "sys.color.scrimSubtle",
+    "thickness": "sys.layout.stack.xs",
+    "inlineWidth": "100%",
+    "border": "none",
+    "radius": "0",
+    "margin": "0"
+  },
+  "appearance": {
+    "background": "sys.color.scrimSubtle",
+    "note": "The only fill tone — Divider has no emphasis axis. Painted as a translucent ~8% inverse-tone overlay (black in light, white in dark) so the band stays visible on every host surface tier without colliding with a fixed neutral step. Mirrors the `scrimSubtle` contract used by Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton."
+  },
+  "behavior": {
+    "ariaHidden": "Defaults to `aria-hidden=\"true\"` because the band is decorative chrome — screen-reader users navigate by headings and landmarks, not visual breaks.",
+    "fullBleed": "Inline width is 100% of the host's content box. Divider claims the page rail in full and must not be wrapped in a padding-inline container — the band reading edge-to-edge IS what makes it a region boundary.",
+    "thicknessFixed": "Block thickness is fixed at `sys.layout.stack.xs` (8) and is not a prop. Heavier bands would compete with content; thinner bands collapse to a hairline (use the host's own `outlineVariant` border for row-level breaks, not Divider)."
+  },
+  "forbidden": [
+    "divider used as a row separator inside a List — the list's own `divider={true}` paints those as a hairline `outlineVariant` rule",
+    "divider painted with `outlineVariant` / a fixed neutral step instead of `sys.color.scrimSubtle` — fixed steps collide with the surface ladder and the divider stops reading on raised surfaces",
+    "divider wrapped in a padding-inline div or `style={{ marginInline }}` — Divider is full-bleed and must touch the page edge to read as a region boundary",
+    "divider given outer `margin-block` / surrounding `padding-block` to fake more breathing — the 8 thickness is the breathing, and the parent column never pays a gap around Divider",
+    "divider painted with a corner radius or stroke — the band is a paint, not a card",
+    "divider used inside a Banner / Section header to break up content — that role belongs to body copy structure, not a region break"
+  ]
+}

package/agents/components/feed/ad.md

@@ -0,0 +1,108 @@
+# Ad
+
+Sub-component of the [Feed](./feed.md) family. A sponsored placement riding the same scrolling column as [Feed · Post](./post.md). The header trades a channel/author row for a brand row (32-rung [Thumbnail](../thumbnail/thumbnail.md) + brand name + `Sponsored` subtitle + trailing close affordance); the body stays the same shape as Feed's title + excerpt; hero media and CTA bond into a single rounded slab at the foot. No engagement row — ads are not authored content.
+
+**Reach for this when** a sponsored placement must ride inline in the feed column alongside authored posts — a promoted brand post, an in-feed ad unit. **Skip when** the content is authored by a user (use [Feed · Post](./post.md)) or the promotion belongs in a dedicated surface outside the feed stream.
+
+**Required slots.** Every FeedAd carries an explicit `brand.name` (the ad's legal attribution surface) and a hero `media` block with a non-empty `src`. When scaffolding, fill `media.src` with `/placeholder.png` rather than omitting `media` — the runtime `surfaceContainerHigh` fallback is a load-failure safety net, not a design-time opt-out.
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell. Pays its own `16px inline / 12px block` padding via `layout.container.*`; 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
+
+Brand row (no dismiss), headline, body excerpt, and hero + CTA slab. Dismiss is opt-in; the CTA fill plumbs through the advertiser's brand Hex via `cta.color`.
+
+```preview
+feed/ad-default
+---
+import { FeedAd } from '@teamblind-chorus/ui';
+
+<FeedAd
+  brand={{
+    name: 'Acme Coffee',
+    avatar: { src: '/placeholder.png', alt: 'Acme Coffee logo' },
+  }}
+  title="Your morning brew, on us."
+  body="Sign up this week and your first bag of single-origin beans ships free — no subscription required."
+  media={{
+    src: '/placeholder.png',
+    alt: 'A flat-lay of freshly roasted coffee beans',
+  }}
+  cta={{ label: 'Claim your free bag', color: '#3DB1A3' }}
+/>
+```
+
+## Use cases
+
+### With dismiss
+
+Wire `onDismiss` to render the trailing close icon for placements that give the reader a dismiss path.
+
+```preview
+feed/ad-with-dismiss
+---
+import { FeedAd } from '@teamblind-chorus/ui';
+
+<FeedAd
+  brand={{
+    name: 'Lumen Fitness',
+    avatar: { src: '/placeholder.png', alt: 'Lumen Fitness logo' },
+  }}
+  onDismiss={() => {}}
+  title="Train smarter, not longer."
+  body="Personalized 20-minute workouts that adapt to your recovery — free for the first 30 days, no card required."
+  media={{ src: '/placeholder.png', alt: 'An athlete mid-workout in a sunlit studio' }}
+  cta={{ label: 'Start your free trial', color: '#5E4BDB' }}
+/>
+```
+
+## Slots
+
+- **brand** *(required)* — leading row: 32-rung [Thumbnail](../thumbnail/thumbnail.md) + brand name (`label.md` / `onSurface`) + `Sponsored` subtitle (`label.sm` / `onSurfaceVariant`) stacked. `brand.name` MUST be non-empty. Subtitle defaults to `Sponsored`; consumers may override but cannot drop it.
+- **dismiss** *(optional)* — trailing 16px close icon, only rendered when `onDismiss` is wired.
+- **title** *(optional)* — single-line headline (`heading.sm` / `onSurface`).
+- **body** *(optional)* — two-line clamped excerpt (`body.sm` / `onSurfaceVariant`).
+- **cta-group** *(required)* — foot slab. Hero **media** required; CTA optional but typical. Media (16:10) and the full-width [Standard Button](../button/standard.md) sit flush inside a single `radius.md` clip with no internal gap. `cta.color` accepts an advertiser-supplied Hex swapping the button fill and border; other token bindings stay intact.
+- **media** *(required)* — hero creative inside cta-group. Image asset (PNG / JPG / WebP / SVG); fill `src` with `/placeholder.png` when scaffolding.
+
+## Anatomy
+
+| Slot             | Token bindings |
+|------------------|----------------|
+| container        | `surface` fill, `radius.md`, `sys.layout.container.lg` (24px mobile / 32px web) block × `sys.layout.container.md` (16px) inline padding, `sys.layout.stack.md` between blocks |
+| brand row        | [Thumbnail](../thumbnail/thumbnail.md) + text column as a row, `sys.layout.inline.md` (8px) gap, `align-items: center` |
+| brand avatar     | [Thumbnail](../thumbnail/thumbnail.md) `size={32}` — delegated verbatim |
+| brand name       | `sys.typo.label.md` (14 / Semibold), `onSurface` |
+| brand subtitle   | `sys.typo.label.sm` (12 / Semibold), `onSurfaceVariant`. Defaults to `Sponsored`. |
+| dismiss          | 16px `XIcon` inside a 24-rung hit area, `onSurfaceVariant` glyph, no chrome at rest |
+| title → body     | 8px vertical gap (`sys.layout.stack.xs`) |
+| title            | `heading.sm` (16 / Semibold), `onSurface`, single-line truncate |
+| body             | 14 / Regular, `onSurfaceVariant`, two-line clamp |
+| bottom divider   | `sys.borderWidth.hairline` × `sys.color.outlineVariant` — `border-bottom` on the card so a sponsored placement drops into a Post stream without breaking the inter-card seam rhythm. |
+| cta-group        | `radius.md` (8px) clip wrapping media + CTA, `overflow: hidden`, no internal gap |
+| media            | Full inline width, 16:10 aspect ratio, no own radius (the group clips). Runtime fallback when `src` is missing or fails to load: `background-image: url('/placeholder.png')` over a `surfaceContainerHigh` base. |
+| cta              | [Standard Button](../button/standard.md) — `fullWidth`, `medium`, `primary` by default, **`border-radius: 0`** so the squared bottom edge meets the group's clip. `cta.color` overrides the surface fill with a free-form Hex. |
+
+## Sizes
+
+A single rung. The card stretches to its column (`width: 100%`); on web an ad column inherits the same `comp-content-max` cap as Feed.
+
+## States
+
+FeedAd is not itself interactive — commit lives in the dismiss and CTA. The card surface has no hover/pressed/focused treatment.
+
+## Focus indicator
+
+FeedAd is not a focus target; each focusable child (dismiss button, CTA) paints its own ring per its spec.
+
+## Behavior
+
+- **Brand name is required.** Every FeedAd carries an explicit `brand.name` — the row is the ad's legal attribution surface. Generators must never drop it.
+- **Hero media is required.** Every FeedAd carries a `media` block with a non-empty `src`. The `surfaceContainerHigh` fallback is a runtime safety net; use `/placeholder.png` when scaffolding.
+- **Brand subtitle is always present.** Defaults to `Sponsored`. Consumers may override copy but cannot omit the row.
+- **Hero media and CTA are one slab.** Share a `radius.md` clip with no internal gap; the CTA's own corner radius is zeroed so its squared bottom edge meets the group's outer round.
+- **Free-form CTA color.** `cta.color` accepts any Hex from the ad client. Only button fill and border swap — typography, size, and full-width geometry stay on Standard Button tokens.
+- **Slot omission collapses without a gap.** `title`, `body`, and `dismiss` are opt-in; `brand.name` and `media` are required.
+- **Truncation, not wrap.** `title` truncates; `body` clamps to two lines.
+- **Dismiss is opt-in.** Default placements omit it; the trailing X only renders when `onDismiss` is wired.
+- **At most one CTA.** No engagement row — the cta-group, when present, carries a single full-width Standard Button.

package/agents/components/feed/ad.spec.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "FeedAd",
+  "family": "feed",
+  "description": "In-feed sponsored placement. Rides the same scrolling column as the default Feed card but trades the channel/author header for a brand row (32-rung Thumbnail + brand name + a `Sponsored` subtitle + an opt-in dismiss), drops the engagement footer, and bonds the hero media and a single full-width CTA into one rounded slab at the foot.",
+  "element": "article",
+  "props": {
+    "brand": {
+      "type": "object",
+      "required": true,
+      "description": "{ name, subtitle?, avatar? } — leading brand row. `name` is **required** — every sponsored placement MUST carry an explicit brand name; never render the row with an empty / missing name (the row exists specifically to attribute the ad to a buyer). `avatar` is forwarded to Thumbnail verbatim at size 32. `subtitle` defaults to the literal `Sponsored`; override but cannot omit.",
+      "fields": {
+        "name": {
+          "type": "string",
+          "required": true,
+          "description": "Brand display name. Must be a non-empty string — the ad row is the legal attribution surface and cannot ship without it."
+        },
+        "subtitle": {
+          "type": "string",
+          "optional": true,
+          "description": "Override for the `Sponsored` subtitle. Cannot be empty."
+        },
+        "avatar": {
+          "type": "object",
+          "optional": true,
+          "description": "{ src, alt } — forwarded to Thumbnail at size 32."
+        }
+      }
+    },
+    "onDismiss": {
+      "type": "function",
+      "optional": true,
+      "description": "Fires when the trailing close (X) is tapped. Omit to render the card without a dismiss affordance."
+    },
+    "dismissLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label for the trailing close button. Defaults to 'Dismiss ad'."
+    },
+    "title": {
+      "type": "string",
+      "optional": true,
+      "description": "Ad headline. heading.sm (16 / Semibold) / onSurface. Single line; truncates with ellipsis."
+    },
+    "body": {
+      "type": "string",
+      "optional": true,
+      "description": "Ad body copy. body.sm (14 / Regular) / onSurfaceVariant. Two-line clamp with trailing ellipsis."
+    },
+    "media": {
+      "type": "object",
+      "required": true,
+      "description": "{ src, alt } — hero media block. **Required** for every FeedAd placement: an ad without a hero image collapses to a brand row + text wall, which is not a shipped FeedAd shape. Renders at 16:10 inside the cta-group's `radius.md` clip. When generating mock / scaffold placements without a real ad creative, fill `src` with `/placeholder.png` rather than omitting `media` — the `surfaceContainerHigh` fallback is a runtime safety net for load failures, not a design-time omission.",
+      "fields": {
+        "src": {
+          "type": "string",
+          "assetType": "image",
+          "required": true,
+          "description": "URL of the hero creative — a raster (PNG / JPG / WebP) or vector (SVG) image asset. Must be present at design time.",
+          "placeholder": "/placeholder.png",
+          "example": "/placeholder.png"
+        },
+        "alt": {
+          "type": "string",
+          "required": true,
+          "description": "Accessible description of the creative."
+        }
+      }
+    },
+    "cta": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, onClick?, color? } — the single full-width Standard Button at the foot. `color` accepts a free-form Hex supplied by the ad client; only the button fill and border swap, every other Standard Button token binding stays intact."
+    },
+    "className": {
+      "type": "string",
+      "optional": true
+    }
+  },
+  "slots": {
+    "brand": {
+      "required": true,
+      "description": "Top row painted by the shared [Metadata](../metadata/metadata.md) cluster (32-rung Thumbnail + brand name + `Sponsored` subtitle + optional trailing dismiss). Brand name MUST be non-empty — the row is the ad's legal attribution surface and cannot ship without it. The row is non-interactive at the container level — the only commit in this region is the trailing close button.",
+      "accepts": [
+        "thumbnail",
+        "text"
+      ]
+    },
+    "dismiss": {
+      "required": false,
+      "description": "Trailing 16px XIcon rendered as a bare icon button. Appears only when `onDismiss` is wired. Inherits Icon Button's 24-rung hit area without painting Icon Button chrome — the row reads as a flat brand strip.",
+      "accepts": [
+        "button"
+      ]
+    },
+    "title": {
+      "required": false,
+      "description": "Ad headline. heading.sm / onSurface. Single line; truncates.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "body": {
+      "required": false,
+      "description": "Ad body excerpt. body.sm / onSurfaceVariant. Two-line clamp.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "cta-group": {
+      "required": true,
+      "description": "Hero media + CTA bonded into one `radius.md` (8) clip with `overflow: hidden` and no internal gap. Media is required; the CTA is optional but typical."
+    },
+    "media": {
+      "required": true,
+      "description": "Hero image inside the cta-group. 16:10 aspect ratio, full inline width, no own corner radius (the group clips). **Required** for every placement — the surfaceContainerHigh fallback is a runtime safety net for load failures, not a design-time omission. When no real creative is available at scaffold time, fill with `/placeholder.png`.",
+      "accepts": [
+        "image"
+      ],
+      "assetType": "image",
+      "placeholder": "/placeholder.png"
+    },
+    "cta": {
+      "required": false,
+      "description": "Full-width Standard Button at the foot of the cta-group. `appearance` is `primary`, `size` is `medium`, `border-radius` is `0` (the group clips). `cta.color` overrides the button fill with a free-form advertiser Hex."
+    }
+  },
+  "sizing": {
+    "containerFill": "sys.color.surface",
+    "containerPaddingBlock": "sys.layout.container.lg",
+    "containerPaddingInline": "sys.layout.container.md",
+    "containerRadius": "sys.radius.md",
+    "interBlockGap": "sys.layout.stack.md",
+    "brandRowGap": "sys.layout.inline.md",
+    "brandAvatarSize": 32,
+    "brandNameTypo": "sys.typo.label.md",
+    "brandNameColor": "sys.color.onSurface",
+    "brandSubtitleTypo": "sys.typo.label.sm",
+    "brandSubtitleColor": "sys.color.onSurfaceVariant",
+    "brandSubtitleDefault": "Sponsored",
+    "dismissIconSize": "sys.icon.md",
+    "dismissColor": "sys.color.onSurfaceVariant",
+    "dismissHitArea": 24,
+    "titleTypo": "sys.typo.heading.sm",
+    "titleColor": "sys.color.onSurface",
+    "containerBottomDividerWidth": "sys.borderWidth.hairline",
+    "containerBottomDividerColor": "sys.color.outlineVariant",
+    "bodyTypo": "sys.typo.body.sm",
+    "bodyColor": "sys.color.onSurfaceVariant",
+    "bodyLineClamp": 2,
+    "titleBodyGap": "sys.layout.stack.xs",
+    "ctaGroupRadius": "sys.radius.md",
+    "mediaAspectRatio": "16 / 10",
+    "mediaFallbackFill": "sys.color.surfaceContainerHigh",
+    "mediaFallbackImage": "/placeholder.png",
+    "mediaFallbackImageRendering": "background-image, cover, center — sits under the runtime <img>; visible only when the inline image is missing or fails to load, so the hero block still resolves to an image rather than an empty surface tone.",
+    "ctaAppearance": "primary",
+    "ctaSize": "medium",
+    "ctaFullWidth": true,
+    "ctaRadius": "0",
+    "ctaColorSource": "Free-form Hex passed via `cta.color`; ad clients ship with their own brand palette."
+  },
+  "states": {
+    "note": "FeedAd container is not itself an interactive primitive — commit lives in the trailing close affordance and the foot CTA. Each follows its own spec's state contract."
+  },
+  "focusIndicator": {
+    "description": "Container is not a focus target; each nested control (dismiss, CTA) paints its own ring per its own spec.",
+    "composition": "inward"
+  },
+  "behavior": {
+    "brandNameRequired": "Every FeedAd MUST carry an explicit `brand.name`. Lovable / mock generators must never drop it — the row is the ad's legal attribution surface, and a placement without a brand name is not a valid FeedAd.",
+    "mediaRequired": "Every FeedAd MUST carry a hero `media` block with a non-empty `src`. The `surfaceContainerHigh` fallback is a runtime safety net for load failures, not a design-time omission — at scaffold time, use the bundled `/placeholder.png` rather than omitting `media`.",
+    "brandSubtitleAlwaysPresent": "The brand subtitle defaults to `Sponsored` so every placement reads as sponsored content. Consumers may override the copy but cannot omit the row.",
+    "ctaGroupBondsMediaAndCta": "Hero media and the CTA share a `radius.md` clip with no internal gap; the CTA's own `border-radius` is zeroed so its squared bottom edge meets the group's outer round.",
+    "ctaColorIsFreeFormHex": "`cta.color` accepts any Hex string supplied by the ad client. Only the button surface fill and border swap — typography, size, and full-width geometry stay on the Standard Button tokens.",
+    "slotOmissionCollapses": "`title`, `body`, and `dismiss` are opt-in — when any is absent the layout reflows without reserved whitespace. `brand.name` and `media` are required and may NOT be omitted.",
+    "containerBottomDivider": "Each Ad card carries the same hairline bottom divider as a Post (`sys.borderWidth.hairline` × `sys.color.outlineVariant`) so a sponsored placement drops into a Post stream without breaking the inter-card seam rhythm.",
+    "truncationNotWrap": "`title` truncates; `body` clamps to two lines.",
+    "dismissOptIn": "Default placements omit the trailing X; it only renders when `onDismiss` is wired.",
+    "ctaCommitsAlone": "FeedAd has no engagement row. The cta-group, when present, carries a single full-width Standard Button — never two CTAs."
+  },
+  "forbidden": [
+    "ad media slot rendered as a raw <img> outside the chorus-feed-ad__media slot wrapper — the slot owns the placeholder fallback and aspect ratio",
+    "ad CTA group placed outside the spec'd cta-group slot — the CTA row geometry is fixed",
+    "thumbnail-sized media — feed-ad media uses the larger hero-style footprint, distinct from feed/post thumbnail"
+  ]
+}

package/agents/components/feed/feed.family.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "feed",
+  "name": "Feed",
+  "description": "The scrolling-stream card family. Two shapes ride the same column \u2014 `post` (the authored content card: channel header, body block, optional inline modules, engagement footer) and `ad` (the in-feed sponsored placement: brand row, optional headline + body, a hero + CTA slab, no engagement row). Editorial collections of popular posts ride alongside Feed cards via the [Section \u00b7 Post Carousel](../carousel/post.md) sub of the Section family \u2014 that pair owns the curated-collection placement, not Feed itself. Both Feed shapes share the same container surface and padding rung so authored posts and sponsored placements tile cleanly side by side.",
+  "useCases": [
+    "content stream",
+    "authored posts",
+    "comments stream",
+    "discussion thread",
+    "timeline",
+    "sponsored post",
+    "in-feed ad",
+    "promotion card",
+    "brand placement"
+  ],
+  "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.",
+  "usage": {
+    "note": "`feed / post` IS the `Feed` export; `feed / ad` is a separate `FeedAd` export. Every affordance threads through props — there is NO `<FeedItem>` child element.",
+    "subs": {
+      "post": { "import": "Feed", "example": "<Feed channel=\"…\" thumbnail={{ src }} title=\"…\" body=\"…\" onClick={() => router.push(href)} />" },
+      "ad": { "import": "FeedAd", "example": "<FeedAd brand=\"…\" title=\"…\" media={{ src }} cta={…} />" }
+    }
+  },
+  "spec": "feed.md",
+  "accessibility": {
+    "articleSemantics": "Each Feed card (post / ad) is an `<article>` with its own accessible name (the card's author / headline) — the unit element required by the APG feed pattern.",
+    "feedContainer": "When the stream is a dynamically-loaded / paginated / infinite feed, the scroll container that holds the article cards carries role='feed'. Each article inside carries aria-posinset (1-based position), aria-setsize (the known total, or -1 when unknown), and aria-labelledby pointing at its heading. The container flips aria-busy='true' while new cards load in and back to 'false' when settled. This is the canonical APG feed contract for an authored, paginated stream — see https://www.w3.org/WAI/ARIA/apg/patterns/feed/.",
+    "feedGroupVsFeed": "role='feed' is the live, navigable stream container. `<FeedGroup>` (role='region' + aria-label, see post.md) is a different, smaller construct — a labelled *bundle* of a few thread- / topic-grouped Posts inside the stream, not the stream itself. A FeedGroup may sit inside a role='feed' container; it does not replace it.",
+    "keyboard": "When role='feed' is used: Page Down / Page Up move reading focus between articles, Ctrl+End / Ctrl+Home jump to the last / first loaded article, and focus is never trapped inside the feed.",
+    "staticStreamException": "A short, static, non-paginated list of cards (e.g. a fixed comments block that never lazy-loads) MAY omit role='feed' and render as a plain sequence of articles. Document the choice at the call site; default to role='feed' for any stream that grows on scroll."
+  },
+  "subcomponents": [
+    {
+      "slug": "post",
+      "spec": "post.spec.json",
+      "md": "post.md",
+      "default": true
+    },
+    {
+      "slug": "ad",
+      "spec": "ad.spec.json",
+      "md": "ad.md"
+    }
+  ]
+}

package/agents/components/feed/feed.md

@@ -0,0 +1,30 @@
+# Feed
+
+The unit of a scrolling stream. The family covers two card shapes that ride the same column: **[Post](./post.md)** — the authored content card (channel header, title + body, optional thumbnail / poll / offer / citation / mention, engagement footer); **[Ad](./ad.md)** — the sponsored placement (brand row, optional title + body, a hero + CTA slab, no engagement row).
+
+Editorial collections of popular posts ride alongside Feed cards via the [Section · Post Carousel](../carousel/post.md) sub of the [Carousel](../carousel/carousel.md) family — that pair owns the curated-collection placement, not Feed itself.
+
+**Reach for this when** the column is an open-ended stream of authored items (posts, comments, discussion threads, timeline entries) or a sponsored placement that needs to tile cleanly into that stream. **Skip when** the rows are same-kind chrome with no author voice (use [List](../list/list.md)), the collection is a finite curated set rendered horizontally (use [Section · Post Carousel](../carousel/post.md)), or the entries are channel / profile cards (use [Section · Profile Carousel](../carousel/profile.md) or [SuggestionList](../suggestion-list/suggestion-list.md)). Pick the sub by the commit surface: authored content with engagement row → [Post](./post.md); sponsored placement with hero + CTA slab → [Ad](./ad.md).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell. Both subs pay their own `sys.layout.container.md` (16px) inline padding via the card chrome; do **not** wrap the Feed in another `padding-inline` / `px-*` / `style={{ padding: … }}` div, or the feed-item author block lands at a different inset than the section headings and list rows around it. 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
+
+Both subs share a column so authored posts and sponsored placements tile cleanly in the same stream.
+
+### Column geometry
+
+Same container surface (`sys.color.surface`), `sys.layout.container.md` (16px) inline padding, `sys.layout.stack.md` between blocks, column-width contract (`width: 100%`; on web both inherit the `comp-content-max` cap).
+
+### Brand row vs author row
+
+Both subs lead with a 32-rung [Thumbnail](../thumbnail/thumbnail.md) + stacked text column. Post binds channel + timestamp + follow affordance; Ad binds brand name + `Sponsored` subtitle + opt-in dismiss. Same anatomy rung, different commit surface.
+
+### No engagement row on sponsored content
+
+Ad omits the engagement footer — ads are not authored content; the only commit is the CTA. Post keeps the Likes / Comments / Views row.
+
+## Sub-components
+
+- **[Post](./post.md)** — the authored content card. Default of the family.
+- **[Ad](./ad.md)** — the in-feed sponsored placement.