@teamblind-chorus/ui 1.0.0

package/agents/components/feed/post.md

@@ -0,0 +1,240 @@
+# Post
+
+Sub-component of the [Feed](./feed.md) family. The authored-content card — the unit of a scrolling feed. Composes a flag, author row, body block (title + clamped excerpt + optional thumbnail), optional inline modules (poll, offer, citation, mention), and an engagement footer.
+
+**Reach for this when** rendering a single user-authored entry — text post, poll, offer evaluation, link share. **Skip when** the placement is sponsored ([Feed · Ad](./ad.md)) or the row is a metric summary rather than authored content.
+
+**Layout inset.** full-bleed — Post contributes its own surface padding (`container.lg` block × `container.md` inline) and a hairline bottom divider, so a stream of Posts tiles edge-to-edge inside the feed column. Drop `Feed` as a direct child of the page-shell `<main>` (or any host that pays the gutter once); do **not** wrap it in a `padding-inline` / `px-*` / `style={{ padding }}` div and do **not** pass it inline padding — Post already pays its own `container.md` inline inset, so an outer pad double-pays the page rail and the author block lands at a different inset than sibling full-bleed rows. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Channel header, title, two-line body, thumbnail, mention, engagement footer. No `flag`.
+
+```preview
+feed/post-default
+---
+import { Feed } from '@teamblind-chorus/ui';
+
+<Feed
+  avatar={{ alt: 'Channel' }}
+  channel="Channel"
+  timestamp="Now"
+  followAction
+  meta={['Company', 'Job Function', 'Username']}
+  title="Title"
+  body="Body textBody textBody textBody textBody textBody textBody…"
+  thumbnail={{ alt: 'Cover', stacked: true }}
+  mention="@Mention"
+  engagement={{ likes: 999, comments: 999, views: 999 }}
+/>
+```
+
+## Use cases
+
+### With flag
+
+Optional single-word editorial label (`HOT`, `NEW`, `PINNED`). Use sparingly.
+
+```preview
+feed/post-with-flag
+---
+import { Feed } from '@teamblind-chorus/ui';
+
+<Feed
+  flag="HOT"
+  avatar={{ alt: 'Channel' }}
+  channel="Channel"
+  timestamp="Now"
+  followAction
+  meta={['Company', 'Job Function', 'Username']}
+  title="Title"
+  body="Body textBody textBody textBody textBody textBody textBody…"
+  thumbnail={{ alt: 'Cover', stacked: true }}
+  mention="@Mention"
+  engagement={{ likes: 999, comments: 999, views: 999 }}
+/>
+```
+
+### With poll
+
+Inline poll module between body and mention/footer. Leading `PollFillIcon` + label paint in `sys.color.brand`; label constrained to the literal `Poll`.
+
+```preview
+feed/post-with-poll
+---
+import { Feed } from '@teamblind-chorus/ui';
+
+<Feed
+  flag="HOT"
+  channel="Channel"
+  timestamp="Now"
+  followAction
+  meta={['Company', 'Job Function', 'Username']}
+  title="Title"
+  body="Body textBody textBody textBody textBody textBody textBody…"
+  thumbnail={{ alt: 'Cover' }}
+  poll={{ label: 'Poll', participants: 'Number' }}
+  mention="@Mention"
+  engagement={{ likes: 999, comments: 999, views: 999 }}
+/>
+```
+
+### With offer evaluation
+
+Same chrome as `poll`; leading glyph swaps to `CompensationFillIcon` and both glyph and label paint in `sys.color.success`. Label constrained to the literal `Offer`.
+
+```preview
+feed/post-with-offer
+---
+import { Feed } from '@teamblind-chorus/ui';
+
+<Feed
+  flag="HOT"
+  channel="Channel"
+  timestamp="Now"
+  followAction
+  meta={['Company', 'Job Function', 'Username']}
+  title="Title"
+  body="Body textBody textBody textBody textBody textBody textBody…"
+  thumbnail={{ alt: 'Cover' }}
+  offer={{ label: 'Offer', participants: 'Number' }}
+  mention="@Mention"
+  engagement={{ likes: 999, comments: 999, views: 999 }}
+/>
+```
+
+### With citation
+
+Citation module naming an external source. Hero image flush-left at 120px wide; title clamps to two lines.
+
+```preview
+feed/post-with-citation
+---
+import { Feed } from '@teamblind-chorus/ui';
+
+<Feed
+  channel="Channel"
+  timestamp="Now"
+  meta={['Company', 'Job Function', 'Username']}
+  title="Title"
+  body="Body textBody textBody textBody textBody textBody textBody…"
+  citation={{
+    title: 'Keep subject area text on two lines or less.',
+    source: 'Source',
+  }}
+  engagement={{ likes: 999, comments: 999, views: 999 }}
+/>
+```
+
+### Group
+
+Three (or more) Post cards bundled inside `<FeedGroup>` for thread-grouped or topic-bundled feeds. The wrapper adds no chrome — inner Posts keep their padding and divider; the wrapper carries intent (`role="region"` + optional `aria-label`).
+
+```preview
+feed/post-group
+---
+import { Feed, FeedGroup } from '@teamblind-chorus/ui';
+
+<FeedGroup label="Today's top discussions">
+  <Feed
+    channel="Channel"
+    timestamp="2h"
+    title="First post in the bundle"
+    body="Short excerpt for the first post. Two lines max before the clamp kicks in."
+    engagement={{ likes: 240, comments: 12, views: 1840 }}
+  />
+  <Feed
+    channel="Channel"
+    timestamp="3h"
+    title="Second post — same topic, different angle"
+    body="Another excerpt. The wrapper carries the bundle intent so the posts read as one continuous slice."
+    engagement={{ likes: 96, comments: 4, views: 720 }}
+  />
+  <Feed
+    channel="Channel"
+    timestamp="5h"
+    title="Third post wraps the bundle"
+    body="Final excerpt. The last post's bottom divider closes the bundle the same way a standalone Post would."
+    engagement={{ likes: 58, comments: 2, views: 410 }}
+  />
+</FeedGroup>
+```
+
+### Full composition
+
+Every optional slot present.
+
+```preview
+feed/post-full
+---
+import { Feed } from '@teamblind-chorus/ui';
+
+<Feed
+  flag="HOT"
+  channel="Channel"
+  timestamp="Now"
+  followAction
+  meta={['Company', 'Job Function', 'Username']}
+  title="Title"
+  body="Body textBody textBody textBody textBody textBody textBody…"
+  thumbnail={{ alt: 'Cover', stacked: true }}
+  poll={{ label: 'Poll', participants: 'Number' }}
+  citation={{
+    title: 'Keep subject area text on two lines or less.',
+    source: 'Source',
+  }}
+  mention="@Mention"
+  engagement={{ likes: 999, comments: 999, views: 999 }}
+/>
+```
+
+## Slots
+
+- **flag** *(optional)* — single-word editorial label.
+- **avatar** — channel thumbnail at the 32 rung.
+- **channel** + **timestamp** + **followAction** *(optional)* — header row.
+- **meta** — middot-separated author metadata links; single line, truncates.
+- **title** + **body** — title (single line, truncates) over a two-line clamped excerpt.
+- **thumbnail** *(optional at runtime, agent-required at scaffold time)* — 80 × 80 trailing image; overlays `SquareStackIcon` when `stacked`. Agents MUST always pass this slot — fill `src` with a real subject photo when implied, `/placeholder.png` otherwise. Runtime omission-collapse is a safety net, not a license to skip the slot at generation time.
+- **poll** / **offer** *(optional)* — inline banners sharing chrome. Label constrained to `Poll` or `Offer`.
+- **citation** *(optional)* — inline link-share card with leading hero and source mark.
+- **mention** *(optional)* — tap-anywhere `@Mention` line under the body.
+- **engagement** — footer row of `xsmall` [Text Buttons](../button/text.md) — Likes / Comments commit, Views non-interactive.
+- **bottom divider** *(intrinsic)* — hairline `outlineVariant` seam at the card's bottom edge.
+
+## Anatomy
+
+| Slot         | Token bindings |
+|--------------|----------------|
+| container    | `surface` fill, `sys.layout.container.lg` (24/32) block × `sys.layout.container.md` (16) inline padding, `sys.layout.stack.md` between blocks |
+| flag         | `label.sm` / Semibold, `brand` foreground |
+| avatar       | [Thumbnail](../thumbnail/thumbnail.md) `size={32}` — delegated verbatim |
+| channel      | 12 / Semibold, `onSurface`. `<a>`; hover underline; focus = hairline `sys.color.focus` at `sys.radius.xs` |
+| timestamp    | 12 / Semibold, `outline` |
+| followAction | 12 / Semibold, `primary` (inactive) → `onSurfaceVariant` (active) |
+| meta         | 12 / Semibold, `onSurfaceVariant`. Each `<a>`; middot at `sys.layout.inline.sm` (4px), decorative |
+| title        | `heading.sm` (16 / Semibold), `onSurface`, single-line truncate. 8px to body |
+| body         | 14 / Regular, `onSurfaceVariant`, two-line clamp |
+| thumbnail    | 80 × 80, `radius.sm`, `surfaceContainerHigh` fallback. `stacked` overlays `SquareStackIcon` at `sys.icon.md`, `ref.palette.white.1000`, 4px top-right inset |
+| poll / offer | `surfaceVariant` fill, `radius.md`, 12 × 16 padding, 48px min-height, 14px body. Leading icon + label at 4px gap, 12px to divider, 12px to count. `poll` paints `brand`; `offer` paints `success` (`ref.palette.green.500`) |
+| citation     | Text-column `surfaceVariant`, `radius.md`, 120px-wide hero. 12px padding, 8px gap title↔source. All text 12px. Source mark 16 × 16 at 4px radius, 4px to source name |
+| mention      | `body.sm`, `primary`, italic |
+| engagement   | `xsmall` [Text Buttons](../button/text.md) + static `<span>` (Views). 16px glyph + 12 / Semibold label, 4 × 8 padding, 4px gap. Row gap 12px. Active Like retones label to `sys.color.brand` with `HeartFillIcon` |
+| bottom divider | `sys.borderWidth.hairline` × `sys.color.outlineVariant` — `border-bottom` on the card |
+
+## States
+
+Feed is not itself interactive — interaction lives in the controls it carries. The card surface has no hover/pressed/focused treatment.
+
+## Focus indicator
+
+Feed itself is not a focus target; each focusable control paints its own ring per its spec. Trigger: `:focus-visible`.
+
+## Behavior
+
+- **Slot omission collapses without a gap.** Optional blocks drop out entirely.
+- **Truncation, not wrap.** `meta` / `title` truncate; `body` clamps to two lines; thumbnail is a flex sibling so the clamp computes against reduced inline width.
+- **Like is a toggle.** Tapping swaps `HeartIcon` → `HeartFillIcon` in `sys.color.brand` via `--button-text-label` and increments the count. Controlled (`liked` + `onLikeChange`) or uncontrolled. Aligns via Text Button's [optical alignment](../button/text.md#optical-alignment).
+- **Comments commits; Views does not.** Views is a non-interactive `<span>`.
+- **Channel and meta are independent links.** Middot separators decorative (`aria-hidden`), outside link hit areas.
+- **`<FeedGroup>` bundles consecutive Posts.** Semantic wrapper only — inner Posts keep their own padding and bottom divider.

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

@@ -0,0 +1,361 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Feed",
+  "family": "feed",
+  "description": "Vertically-stacked content card — the unit of a scrolling feed. One Feed entry composes a flag, an author row, a body block (title + clamped excerpt + optional thumbnail), optional inline modules (poll banner, offer-evaluation banner, source citation, mention line), and an engagement footer (reactions and view count). Slots are independent — every block beyond the author row is optional, so the same component renders a plain text post, a poll, an offer evaluation, or a link share without forking the variant axis.",
+  "element": "article",
+  "props": {
+    "flag": {
+      "type": "string",
+      "optional": true,
+      "description": "Editorial label — 'HOT', 'NEW', 'PINNED'. Opt-in; most posts render without one."
+    },
+    "avatar": {
+      "type": "object",
+      "optional": true,
+      "description": "Forwarded to Thumbnail verbatim at size 32."
+    },
+    "channel": {
+      "type": "string",
+      "required": true
+    },
+    "channelHref": {
+      "type": "string",
+      "optional": true,
+      "description": "Destination URL for the channel link. Defaults to '#' (preview-stub)."
+    },
+    "timestamp": {
+      "type": "string",
+      "required": true
+    },
+    "followAction": {
+      "type": "boolean",
+      "optional": true,
+      "description": "When present, renders an inline text affordance after the timestamp."
+    },
+    "meta": {
+      "type": "node",
+      "optional": true,
+      "description": "Array of independently-linked metadata items. Pass plain strings for stub links, or `{ label, href }` objects to route."
+    },
+    "liked": {
+      "type": "boolean",
+      "optional": true,
+      "description": "Controlled active state for the Like toggle. Omit (uncontrolled) and the component manages its own active state."
+    },
+    "onLikeChange": {
+      "type": "function",
+      "optional": true,
+      "description": "Fires with the next `liked` value when the Like Text Button is tapped."
+    },
+    "title": {
+      "type": "string",
+      "optional": true
+    },
+    "body": {
+      "type": "string",
+      "optional": true
+    },
+    "thumbnail": {
+      "type": "object",
+      "optional": true,
+      "agentRequired": true,
+      "description": "80×80 trailing image; { src, alt, stacked? }. **Agents must always pass this slot at scaffold / generation time** — fill `src` with a real subject photo when implied, the bundled `/placeholder.png` otherwise. The `optional` flag and the `slotOmissionCollapses` rule are RUNTIME contracts (a Feed still reflows cleanly when a downstream consumer drops thumbnail for a verified text-only post); they are NOT a license for agents to omit the slot. See `forbidden` below — omission at scaffold time is forbidden. When `stacked === true` (2+ images attached), the thumbnail overlays a `SquareStackIcon` glyph at its top-right corner — see `sizing.thumbnailMultipleBadge` for the full anatomy."
+    },
+    "poll": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, participants } — inline poll banner. `label` is constrained to the literal `\"Poll\"` (the banner is editorial — see `tagBanner.labelEnum`); `participants` is the participant count shown after the divider.",
+      "fields": {
+        "label": {
+          "type": "enum",
+          "values": [
+            "Poll"
+          ],
+          "default": "Poll",
+          "description": "Constrained — the poll banner only ever shows the literal `Poll`. Omit to use the default; do not pass a free-form string."
+        },
+        "participants": {
+          "type": "string",
+          "required": true
+        }
+      }
+    },
+    "offer": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, participants } — inline offer-evaluation banner. Same chrome as `poll` (surfaceVariant slab, leading glyph + label + divider + participant count), but the leading icon is `CompensationFillIcon` and the glyph + label paint in `sys.color.success` (resolves to `ref.palette.green.500`). Surfaces a 'compensation / offer evaluation' post — the author publishes their current salary or a competing offer and asks the community for better-option signals. `label` is constrained to the literal `\"Offer\"` (see `tagBanner.labelEnum`); `participants` is the participant count shown after the divider.",
+      "fields": {
+        "label": {
+          "type": "enum",
+          "values": [
+            "Offer"
+          ],
+          "default": "Offer",
+          "description": "Constrained — the offer banner only ever shows the literal `Offer`. Omit to use the default; do not pass a free-form string."
+        },
+        "participants": {
+          "type": "string",
+          "required": true
+        }
+      }
+    },
+    "citation": {
+      "type": "object",
+      "optional": true,
+      "description": "{ title, source, src? } — inline link-share card."
+    },
+    "mention": {
+      "type": "string",
+      "optional": true
+    },
+    "engagement": {
+      "type": "object",
+      "optional": true,
+      "description": "{ likes, comments, views } — footer counters."
+    },
+    "onClick": {
+      "type": "function",
+      "optional": true,
+      "description": "Whole-card navigation. When present the card surface becomes the click target (an <article role=\"button\">), and interior affordances (channel link, Follow, Like, Comments, citation, mention) route independently — a click originating on any inner <a>/<button> is ignored. This is the in-contract way to make a post navigable; do NOT wrap Feed in an external <Link>/<a> — that re-pays the page rail as a gutter and misaligns the card with NavigationBar / TabBar."
+    }
+  },
+  "slots": {
+    "flag": {
+      "required": false,
+      "description": "Single-word editorial label at the top of the card. brand foreground, no fill. Opt-in.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "avatar": {
+      "required": false,
+      "description": "Thumbnail at size 32 — delegated verbatim. Painted by the shared [Metadata](../metadata/metadata.md) cluster (avatar + channel name + timestamp + meta row).",
+      "accepts": [
+        "thumbnail"
+      ]
+    },
+    "channel": {
+      "required": true,
+      "description": "Channel / author name, rendered by the [Metadata](../metadata/metadata.md) cluster as an `<a>` link to the channel page. 12px / Semibold / onSurface. No underline at rest; hover underlines the link alone; focus paints a hairline `sys.color.focus` outline at `sys.radius.xs`.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "timestamp": {
+      "required": true,
+      "description": "Relative time since the post. 12px / Regular / outline.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "followAction": {
+      "required": false,
+      "description": "Inline plain text affordance after the timestamp (separated by middot). 12 / Semibold / primary (inactive) → onSurfaceVariant ('Following'). No fill, no border.",
+      "accepts": [
+        "text",
+        "button"
+      ]
+    },
+    "meta": {
+      "required": false,
+      "description": "Middot-separated author metadata. Each item renders as its own `<a>` link inheriting the row's tone (12 / Semibold / onSurfaceVariant). Middot separator decorative (`aria-hidden`) and sits outside link hit areas. Single line; truncates.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "title": {
+      "required": false,
+      "description": "Post title. heading.sm (16 / Semibold) / onSurface. One line; truncates with ellipsis.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "body": {
+      "required": false,
+      "description": "Post excerpt. 14 / Regular / onSurfaceVariant. Two-line clamp with trailing ellipsis.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "thumbnail": {
+      "required": false,
+      "agentRequired": true,
+      "omittedBehavior": "collapse",
+      "fallbackOnMissingSrc": "sys.color.surfaceContainerHigh",
+      "description": "80×80 square image at the trailing edge of the title/body block. radius.sm. `omittedBehavior: collapse` is a runtime safety net — when the prop is undefined the slot drops out of the layout (no reserved whitespace). `agentRequired: true` overrides this for scaffold/generation time: agents MUST always pass a `thumbnail` prop, falling back to `src: \"/placeholder.png\"` when no real subject is implied. `fallbackOnMissingSrc` is the dim-tone fill the component paints when `thumbnail` is present but `src` fails to load (network error or empty string). When the post carries 2+ images, overlays a `SquareStackIcon` badge at the top-right corner (16px / white / 4 inset on top + right).",
+      "accepts": [
+        "thumbnail"
+      ]
+    },
+    "poll": {
+      "required": false,
+      "description": "Inline banner naming an attached poll. surfaceVariant fill, 48px min-height. Leading glyph `PollFillIcon` + label, both painted in `sys.color.brand`; label is constrained to the literal `Poll`."
+    },
+    "offer": {
+      "required": false,
+      "description": "Inline banner naming an attached offer-evaluation post. Identical chrome to `poll` — surfaceVariant fill, 48px min-height — with the leading glyph swapped to `CompensationFillIcon` and the glyph + label painted in `sys.color.success` (resolves to `ref.palette.green.500`). Label is constrained to the literal `Offer`."
+    },
+    "citation": {
+      "required": false,
+      "description": "Inline link-share card naming an external source."
+    },
+    "mention": {
+      "required": false,
+      "description": "Tap-anywhere line under the body naming the parent thread. Italic, primary, body-sm.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "engagement": {
+      "required": false,
+      "description": "Footer row of three counters laid out as an `xsmall` Text Button group. Likes + Comments are real Text Buttons (`text` / `xsmall` / `secondary`); Views renders as a non-interactive `<span>` matching the same 16-glyph / 12-label rhythm. Row gap follows the xsmall-rung group rule (`sys.layout.inline.sm` = 4px). Like is a toggle: active state retones the label to `sys.color.brand` (via `--button-text-label` override) and swaps `HeartIcon` → `HeartFillIcon`, with the count incrementing in lockstep. Never wraps."
+    }
+  },
+  "sizing": {
+    "containerFill": "sys.color.surface",
+    "containerPaddingBlock": "sys.layout.container.lg",
+    "containerPaddingInline": "sys.layout.container.md",
+    "interBlockGap": "sys.layout.stack.md",
+    "flagTypo": "sys.typo.label.sm",
+    "flagColor": "sys.color.brand",
+    "avatarSize": 32,
+    "channelTypo": "sys.typo.label.sm",
+    "channelColor": "sys.color.onSurface",
+    "timestampTypo": "sys.typo.label.sm",
+    "timestampColor": "sys.color.outline",
+    "followActionTypo": "sys.typo.label.sm",
+    "followActionColorInactive": "sys.color.primary",
+    "followActionColorActive": "sys.color.onSurfaceVariant",
+    "channelRowGap": "sys.layout.inline.md",
+    "metaTypo": "sys.typo.label.sm",
+    "metaColor": "sys.color.onSurfaceVariant",
+    "metaSeparatorGap": "sys.layout.inline.sm",
+    "titleBodyGap": "ref.space.100",
+    "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,
+    "thumbnailSize": "80 × 80",
+    "thumbnailRadius": "sys.radius.sm",
+    "thumbnailFallbackFill": "sys.color.surfaceContainerHigh",
+    "thumbnailMultipleBadge": {
+      "trigger": "thumbnail.stacked === true (2+ images attached to the post)",
+      "icon": "SquareStackIcon",
+      "size": "sys.icon.md",
+      "color": "ref.palette.white.1000",
+      "colorReason": "Fixed white so the badge stays legible against any user-supplied imagery in any theme; a surface-toned tint would invert in dark mode and disappear on bright photos.",
+      "anchor": "top-right of the thumbnail",
+      "insetTop": "sys.layout.container.2xs",
+      "insetRight": "sys.layout.container.2xs"
+    },
+    "engagementCounterShape": "xsmall Text Button (Likes / Comments) or matching static span (Views)",
+    "engagementLabelTypo": "sys.typo.label.sm",
+    "engagementLabelColor": "sys.color.onSurfaceVariant",
+    "engagementIconSize": "sys.icon.md",
+    "engagementSlotGap": "sys.layout.inline.sm",
+    "engagementRowGap": "sys.layout.inline.lg",
+    "likeActiveColor": "sys.color.brand",
+    "likeActiveIcon": "HeartFillIcon",
+    "likeRestIcon": "HeartIcon",
+    "likeLeadingOffset": "Inherited from Text Button's optical-alignment default — no per-call offset; the heart glyph sits at the card's content rail automatically."
+  },
+  "poll": {
+    "fill": "sys.color.surfaceVariant",
+    "radius": "sys.radius.md",
+    "paddingBlock": "ref.space.150",
+    "paddingInline": "ref.space.200",
+    "minHeight": "ref.space.600",
+    "bodyTypo": "14",
+    "glyph": "PollFillIcon",
+    "glyphColor": "sys.color.brand",
+    "labelColor": "sys.color.brand",
+    "labelLiteral": "Poll",
+    "anatomy": "Leading 'poll-title' sub-container groups glyph (brand tone) + label at 4px gap; 12px flex gap to vertical outlineVariant divider; 12px gap to participant count."
+  },
+  "offer": {
+    "fill": "sys.color.surfaceVariant",
+    "radius": "sys.radius.md",
+    "paddingBlock": "ref.space.150",
+    "paddingInline": "ref.space.200",
+    "minHeight": "ref.space.600",
+    "bodyTypo": "14",
+    "glyph": "CompensationFillIcon",
+    "glyphColor": "sys.color.success",
+    "glyphColorResolved": "ref.palette.green.500",
+    "labelColor": "sys.color.success",
+    "labelLiteral": "Offer",
+    "anatomy": "Identical to `poll` — same surfaceVariant slab, same 48 min-height, same leading sub-container + divider + participant count. Differs only in the glyph (CompensationFillIcon) and the editorial tone (success / green-500 instead of brand)."
+  },
+  "tagBanner": {
+    "shared": "`poll` and `offer` are siblings of the same banner family — same chrome, same anatomy. They differ only on the glyph + editorial tone.",
+    "labelEnum": "The leading-icon label is constrained to exactly two literals across both modules combined: `\"Poll\"` (for the poll banner) and `\"Offer\"` (for the offer-evaluation banner). Consumers (including Lovable) MUST pass one of these two values, or omit `label` to use the default for the chosen banner kind. No other label string is valid.",
+    "renderOrder": "When both modules are present on the same post, `poll` renders above `offer`. Either may stand alone."
+  },
+  "citation": {
+    "textColumnFill": "sys.color.surfaceVariant",
+    "outerRadius": "sys.radius.md",
+    "heroWidth": "120px",
+    "heroBleed": "Flush against the card's leading edge — no container padding, no inter-column gap.",
+    "textColumnPadding": "ref.space.150",
+    "titleSourceGap": "ref.space.100",
+    "allTextSize": "ref.space.150",
+    "titleStyle": "Semibold / onSurface",
+    "sourceStyle": "Regular / onSurfaceVariant",
+    "sourceMarkSize": "16 × 16",
+    "sourceMarkRadius": "ref.space.50",
+    "sourceMarkGap": "ref.space.50"
+  },
+  "mention": {
+    "typo": "sys.typo.body.sm",
+    "color": "sys.color.primary",
+    "fontStyle": "italic"
+  },
+  "states": {
+    "note": "Feed container is not itself an interactive primitive — interaction lives in the controls it carries (Follow toggle, engagement counters, citation link, mention link, thumbnail/poll affordances). Each follows its own spec's state contract. The card surface has no hover/pressed/focused treatment."
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Feed itself is not a focus target; each nested control (Like / Comments Text Buttons, channel / meta links, follow action) paints its own ring per its spec. This contract documents the composition any future row-level focus target would inherit.",
+    "composition": "inward",
+    "compositionReason": "Rows tile the column with a hairline divider; an outward ring would overlap divider and neighbour row.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the card edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the card edge (the counter-ring just inside the outer stroke)",
+      "implementation": "inset box-shadow constrained strictly inside the card's footprint."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "slotOmissionCollapses": "Runtime safety net — when these optional blocks (flag, followAction, thumbnail, poll, offer, citation, mention) are absent the layout reflows cleanly with no reserved whitespace. This is a graceful-degradation contract for downstream consumers, NOT a license for agents to omit slots at scaffold time. `thumbnail` in particular is `agentRequired` (see props.thumbnail) — agents must always pass it with `/placeholder.png` when no subject photo is implied.",
+    "containerBottomDivider": "Each Post card carries a hairline bottom divider (`sys.borderWidth.hairline` × `sys.color.outlineVariant`) so consecutive cards in a stream read with a deliberate inter-card seam. The divider is `border-bottom` on the card itself — layout-safe under `box-sizing: border-box`, no shadow tricks needed. Inside a `<FeedGroup>` (the 3-up bundle case), the inner posts keep their dividers and the group's last card carries the same outer-bottom divider as a standalone Post — the rhythm is identical, the wrapper is purely semantic.",
+    "groupCase": "Three (or more) Post cards bundled vertically inside a `<FeedGroup>` semantic wrapper. Used for thread-grouped or topic-bundled feeds where consecutive posts belong together. The group adds no extra surface chrome — each Post keeps its own `surface` fill, `container.lg/md` padding, and bottom divider; the wrapper only contributes a `role=\"region\"` + optional `aria-label` for the bundle's intent. There is no fixed item count contract; 3 is the canonical demo case.",
+    "tagBannerLabelConstrained": "The poll and offer banners share one closed enum for their leading label: `\"Poll\"` or `\"Offer\"`. Each module defaults to its own literal when `label` is omitted; passing any other string is a contract violation.",
+    "truncationNotWrap": "meta and title truncate; body clamps to two lines. The card never grows to fit a long title.",
+    "thumbnailFlexSibling": "Title and body share their inline space with the thumbnail when both are present; thumbnail is a flex sibling, not floated, so the body's two-line clamp computes against the reduced inline width.",
+    "engagementNoReflow": "Footer row stays single-line; tiny screens scroll the row rather than wrapping.",
+    "likeToggle": "Tapping Likes increments the count and swaps the rest-state HeartIcon / secondary appearance for the active-state HeartFillIcon with the label re-toned to `sys.color.brand` (via a `--button-text-label` override — not the Text Button `primary` appearance — because Feed's active-like colour is the editorial brand tone, not the interactive primary). Glyph re-colours via `currentColor`. Tapping again decrements and reverts. Controlled via `liked` + `onLikeChange`, or left uncontrolled for in-demo behaviour.",
+    "likeLeadingNudge": "The Like glyph aligns flush with the card's content rail via Text Button's optical-alignment default — the chrome bleeds outward by its own padding on every side, so the visible heart sits at the rail without any per-call offset. The 4px row gap to Comments stays unaffected.",
+    "viewsNonInteractive": "Views renders as a non-interactive `<span>` matching the xsmall Text Button visual rhythm — no hover / pressed / focus, no `cursor: pointer`. It is a metric display, not an action that has been turned off, so `aria-disabled` is the wrong shape.",
+    "channelAndMetaAreLinks": "Channel name and every `meta` item are independent links. The middot separator between meta items is decorative (`aria-hidden`) and sits outside each link's hit area, so the hover underline never spans the separator."
+  },
+  "forbidden": [
+    "thumbnail slot omitted at scaffold / agent time — every feed post MUST pass a `thumbnail` prop. Fill `src` with a real subject photo when implied, the bundled `/placeholder.png` otherwise. The runtime `slotOmissionCollapses` reflow is a safety net for downstream consumers, NOT permission for agents to skip the slot",
+    "author meta collapsed into a single line — the two meta rows (channel · time / workplace · role · username) are anatomy invariants",
+    "engagement footer rendered with raw <button> — like / comments / views are button/text + non-interactive span (views) per the spec",
+    "active-like color painted with sys.color.primary — active-like uses sys.color.brand via the --button-text-label plumbing var",
+    "raw <a> for hashtag / mention — inline link tone uses sys.color.primary via the body markup contract, not raw anchor styling",
+    "Feed wrapped in a padding-inline div / className=\"px-*\" / style={{ padding }} — Feed is layoutInset=\"full-bleed\" and pays its own page rail once; an outer padding wrapper double-pays the gutter and misaligns the card with NavigationBar / TabBar (the runtime useFullBleedGuard warns on this)",
+    "Feed wrapped in an external <Link>/<a> to make the card navigable — pass the `onClick` prop instead (the card surface becomes the target, interior affordances route independently). An outer anchor re-pays the page rail as a gutter AND nests the card's own anchors (channel link, citation, mention), which breaks DOM parsing"
+  ]
+}

package/agents/components/form-field/form-field.family.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "form-field",
+  "name": "FormField",
+  "description": "Text-entry family. `input` is the default labeled single-line text field with optional helper / count; `textarea` is the multi-line cousin with a `rows` floor and vertical-only resize; `search` is a bare pill-shaped variant with a leading search glyph; `select` is the Input-shaped picker that opens a sheet.",
+  "useCases": [
+    "single-line text input",
+    "multi-line text input (bio, comment, compose body)",
+    "labeled text field",
+    "search input",
+    "bare search pill",
+    "sheet-driven option picker",
+    "labelled select+input pairing (e.g. country code + number)"
+  ],
+  "visualReuse": "locked",
+  "layoutInset": "inline",
+  "usage": {
+    "note": "Each variant is also exposed as a convenience named export (Input / Textarea / SearchBar / Select), all backed by `FormField`.",
+    "subs": {
+      "input": { "import": "Input", "example": "<Input label=\"…\" value={v} onChange={setV} />" },
+      "textarea": { "import": "Textarea", "example": "<Textarea label=\"…\" value={v} onChange={setV} />" },
+      "search": { "import": "SearchBar", "example": "<SearchBar value={q} onChange={setQ} />" },
+      "select": { "import": "Select", "example": "<Select label=\"…\" value={v} onChange={setV} options={[…]} />" }
+    }
+  },
+  "spec": "form-field.md",
+  "subcomponents": [
+    {
+      "slug": "input",
+      "spec": "input.spec.json",
+      "md": "input.md",
+      "default": true
+    },
+    {
+      "slug": "textarea",
+      "spec": "textarea.spec.json",
+      "md": "textarea.md"
+    },
+    {
+      "slug": "search",
+      "spec": "search.spec.json",
+      "md": "search.md"
+    },
+    {
+      "slug": "select",
+      "spec": "select.spec.json",
+      "md": "select.md"
+    }
+  ]
+}