@teamblind-chorus/ui 1.0.0

package/agents/components/list/standard.spec.json

@@ -0,0 +1,221 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "List",
+  "family": "list",
+  "subcomponent": "standard",
+  "description": "The default List variant — display or navigation rows over the shared List anatomy. The whole row is the click target; no selection model. A row is text-only by default (no leading slot); it opts into a **leading image** (the image type) by passing a `thumbnail`, which renders a 40px [Thumbnail](../thumbnail/thumbnail.md) at the leading edge with a 12px (`sys.layout.inline.lg`) gap to the text group, or into a **leading icon** (the icon type) by passing an `icon`, which renders a 24px (`sys.icon.lg`) glyph with an 8px (`sys.layout.inline.md`) gap. A row opts into a trailing drill-in chevron with `nav: true` (the drill-in case — the row routes the user to another surface); a per-item `trailingIcon` overrides the auto chevron. A row opts into an inline **count badge** to the right of the label via `count` — separated from the label by `sys.layout.inline.sm` (4), the unread / status-count case — and it composes with the chevron / trailing slot on the same row. For the richer directory shape (selectable 32/48/56 avatar + stacked `secondary` identity line) reach for [list/entry](./entry.md); Standard's leading image is single-density at the 40 rung.",
+  "element": "ul",
+  "props": {
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when the List is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `list.family.json`."
+    },
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of row descriptors. A row carrying `thumbnail` props forwards them verbatim to the leading Thumbnail (the image type)."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Outer scroll surface. Vertical stack with a transparent fill (inherits parent container tone); rows separated by a 1px outlineVariant divider, not a gap."
+    },
+    "row": {
+      "required": true,
+      "description": "Single list item. Whole row is the interactive target."
+    },
+    "leading": {
+      "required": false,
+      "fallbackOnMissingSrc": "sys.color.surfaceContainerHigh",
+      "description": "The leading slot — omitted by default (no reserved leading whitespace), hosting one of two mutually exclusive types. **Image type** (`thumbnail`): a [Thumbnail](../thumbnail/thumbnail.md) at the 40 rung, vertically centred against the label column, with a 12px (`sys.layout.inline.lg`) gap to the text group; `thumbnail` props (`src`, `alt`, `updateDot`, `logoBadge`) forward verbatim, and `fallbackOnMissingSrc` is the dim-tone fill it paints when `src` is empty / fails to load (at scaffold time, agents fill `src` with `/placeholder.png` rather than relying on the fallback). **Icon type** (`icon`): a 24px (`sys.icon.lg`) decorative glyph in `onSurfaceVariant`, vertically centred, with an 8px (`sys.layout.inline.md`) gap to the text group — the category-mark shape for settings / menu rows. The slot enforces the 24 rung regardless of the glyph's own `size`. A row passes `thumbnail` or `icon`, never both.",
+      "accepts": [
+        "thumbnail",
+        "icon"
+      ]
+    },
+    "label": {
+      "required": true,
+      "description": "Primary row text. 16px / Regular / onSurface. Single line; truncates with ellipsis. Pairs flush with the inline `count` slot — `sys.layout.inline.sm` (4) horizontal separation, baseline-aligned, on the primary line; the label shrinks first so a long label truncates against the count.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "count": {
+      "required": false,
+      "description": "Optional inline node painted to the right of the label on the same line — the unread / status-count case. Canonical fill is a numeric [Badge](../badge/badge.md). Separated from the label by `sys.layout.inline.sm` (4); the label shrinks first so a long label truncates against the count, which stays pinned at its intrinsic width. Distinct from `trailingIcon`: `count` tiles tight to the label inside the text group, while `trailingIcon` / `navChevron` sit at the row's trailing edge — so the two compose (a drill-in row can carry a count next to the label and keep its trailing chevron). For the avatar-anchored directory shape with an inline count, reach for [list/entry](./entry.md) instead.",
+      "accepts": [
+        "badge"
+      ]
+    },
+    "supportingText": {
+      "required": false,
+      "description": "Secondary line under label. 14px / Regular / onSurfaceVariant, sits directly under the label with no extra gap.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "trailingIcon": {
+      "required": false,
+      "description": "Consumer-supplied node at the trailing edge. A 16px icon (e.g. an external-link mark replacing the drill-in chevron), or — on a leading-image row — a small text button (Follow / Invite). A status **badge** does not belong here — it tiles next to the label via the `count` slot so every badge in the list reads at the same position; the trailing edge stays for icons / buttons. Taps on the trailing slot stop propagating before they reach the row's `onClick`, so it is a separate hit target. Overrides the auto-rendered nav chevron on the same row.",
+      "accepts": [
+        "icon",
+        "button"
+      ]
+    },
+    "navChevron": {
+      "required": false,
+      "description": "Auto-rendered 16px right-pointing chevron at the trailing edge, painted when the row sets `nav: true` — the drill-in affordance signalling the row routes to another surface. `onSurfaceVariant` tone, decorative (`aria-hidden`); never a separate hit target — the whole row is the click target. A per-item `trailingIcon` replaces it."
+    }
+  },
+  "rowProps": {
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "label": {
+      "type": "string",
+      "required": true
+    },
+    "supportingText": {
+      "type": "string",
+      "optional": true
+    },
+    "count": {
+      "type": "node",
+      "optional": true,
+      "description": "Inline count node painted to the right of the label on the same line. Canonical fill: `<Badge>{n}</Badge>`. Composes with `nav` / `trailingIcon` — the count sits by the label, the chevron / trailing node stays at the row's trailing edge."
+    },
+    "thumbnail": {
+      "type": "object",
+      "optional": true,
+      "description": "The image type — when present, renders a leading 40px Thumbnail (props `src`, `alt`, optional `updateDot`, optional `logoBadge` forwarded verbatim). Omit for a text-only row. Mutually exclusive with `icon`."
+    },
+    "icon": {
+      "type": "node",
+      "optional": true,
+      "description": "The icon type — when present, renders a leading 24px (`sys.icon.lg`) decorative glyph in `onSurfaceVariant`, 8px (`sys.layout.inline.md`) from the text group. Canonical fill: a category icon (`<BellIcon />`, `<BookmarkIcon />`). The slot forces the 24 rung, so `size` on the passed glyph is ignored. Mutually exclusive with `thumbnail`."
+    },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Trailing-edge node. Wrapped in a slot that stops click propagation so the slot is its own hit target separate from the row's `onClick`."
+    },
+    "divider": {
+      "type": "boolean",
+      "default": true,
+      "description": "Per-row bottom-divider opt-out. Pass `divider: false` to suppress the hairline `outlineVariant` rule beneath the row; the row's footprint and inline padding stay unchanged. Reach for it when a visual group ends mid-stack and the divider would visually fence off the next group from its label. The last row already omits its divider via `:not(:last-child)`."
+    },
+    "nav": {
+      "type": "boolean",
+      "default": false,
+      "description": "Drill-in case — when `true`, the row auto-renders a trailing right-pointing chevron marking that it routes to another surface. Overridden by a per-item `trailingIcon`."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "strong": {
+      "type": "boolean",
+      "default": false,
+      "description": "Per-row label-emphasis opt-in (family-wide contract — see [list.md § Cross-sub contract](./list.md)). When `true`, the row's label weight promotes from `body.md` Regular (400) to `label.lg` Semibold (600) at the same 16px size and 1.5 line-height — geometry stays identical, only the glyph stroke thickens. Use sparingly to mark one primary row inside a denser scan; a stack where every row is `strong` defeats the marker."
+    },
+    "onClick": {
+      "type": "function",
+      "optional": true
+    },
+    "forcedState": {
+      "type": "literal",
+      "values": [
+        "hovered",
+        "pressed",
+        "focused"
+      ],
+      "optional": true,
+      "description": "Docs-only — pins the row to a single visual state via `data-force-state` so the contract can be inspected in a static preview. Not for production use."
+    }
+  },
+  "sizing": {
+    "rowPaddingBlock": "ref.space.100",
+    "rowPaddingInline": "ref.space.200",
+    "rowMinHeight": "ref.space.600",
+    "leadingTextGap": "sys.layout.inline.lg",
+    "leadingTextGapNote": "12px (`sys.layout.inline.lg`) between a leading 40-rung Thumbnail (the image type, an image leading) and the text group — the image-leading rung of the family's role-based row spacing, wider than the 8px icon rung so the avatar and the label column read as two distinct blocks. Applies only to rows that carry a `thumbnail`; text-only rows have no leading slot.",
+    "leadingIconSize": "sys.icon.lg",
+    "leadingIconGap": "sys.layout.inline.md",
+    "leadingIconGapNote": "8px (`sys.layout.inline.md`) between a leading 24px (`sys.icon.lg`) icon (the icon type) and the text group — the icon-leading rung of the family's role-based row spacing (the base leading gap), narrower than the 12px image rung. Applies only to rows that carry an `icon`.",
+    "trailingActionGap": "sys.layout.inline.md",
+    "trailingActionGapNote": "Fixed 8px (`sys.layout.inline.md`) between the text group and a trailing icon / nav chevron — the family-wide trailing gap, identical across every List variant.",
+    "labelToCountGap": "sys.layout.inline.sm",
+    "labelToCountGapNote": "4px (`sys.layout.inline.sm`) between the label and an inline `count` badge — they tile flush on the primary line as one label+count block, narrower than the 8px trailing gap. Mirrors list/entry's identity-group spacing.",
+    "dividerWidth": "sys.borderWidth.hairline",
+    "dividerColor": "sys.color.outlineVariant",
+    "dividerPerRowOptOut": "Pass `divider: false` on a row to suppress its bottom divider.",
+    "leadingThumbnailSize": 40,
+    "labelTypo": "sys.typo.body.md",
+    "labelColor": "sys.color.onSurface",
+    "supportingTypo": "sys.typo.body.sm",
+    "supportingColor": "sys.color.onSurfaceVariant",
+    "supportingOffset": "0",
+    "trailingIconSize": "16 × 16",
+    "trailingIconColor": "sys.color.onSurfaceVariant",
+    "navChevronSize": "16 × 16",
+    "navChevronColor": "sys.color.onSurfaceVariant"
+  },
+  "states": {
+    "default": {
+      "overlay": null
+    },
+    "hovered": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.hover"
+      }
+    },
+    "pressed": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "disabled": {
+      "containerOpacity": "sys.state.disabled",
+      "containerOpacityScope": "Dims the row content only — the inter-row divider and the focus overlay keep full opacity, so a disabled row never fades the hairline rule between it and the next row.",
+      "pointerEvents": "none"
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the row is in.",
+    "composition": "inward",
+    "compositionReason": "Rows tile the column flush with only a hairline `outlineVariant` divider between them; an outward ring would overlap the divider and the neighbouring row.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the row edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the row edge (the counter-ring just inside the outer stroke)",
+      "implementation": "inset box-shadow on the row's `::before` overlay (the `::after` carries the inter-row divider). Constrained strictly inside the row's footprint and never exceeds it."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "keyboardNavigation": "Arrow up/down moves focus between rows. Home and End jump to first / last.",
+    "rowClickTarget": "Whole row is clickable when an `onClick` is bound to the item. A leading thumbnail is never a separate hit target.",
+    "navDrillIn": "A row with `nav: true` renders the trailing chevron and routes the user to another surface on click (consumer wires `onClick`). The chevron is decorative — the whole row is the single click target, never the chevron alone.",
+    "trailingHitTarget": "Clicks inside `trailingIcon` stop propagating before they reach the row — wire a favorite / mute / pin toggle or a Follow button there without it committing the row's primary action.",
+    "truncationNotWrap": "Both label and supportingText truncate; the row never grows to fit long text."
+  },
+  "forbidden": [
+    "row leading content (thumbnail) as a separate hit area — the entire row is the click target",
+    "nav chevron as a separate hit target — the drill-in chevron is decorative; the whole row is the click target",
+    "leading thumbnail at a size other than the row's intrinsic 40 rung",
+    "compact directory rows (selectable 32/48/56 avatar + stacked secondary line + optional toggle) built as a leading-image Standard row — that directory anatomy is [list/entry](./entry.md); Standard's image type is single-density at the 40 rung. (Standard does carry an inline `count` badge next to the label for unread / status counts, but not the avatar-rung directory shape.)",
+    "raw `border:` on the row — list seam is the family's bottom divider via outlineVariant"
+  ]
+}

package/agents/components/metadata/compact.md

@@ -0,0 +1,69 @@
+# Compact
+
+One-line author attribution for comment and reply rows. The [Standard](./standard.md) head with its primary line (avatar + entity name + timestamp + follow) omitted — only the secondary meta-link row renders, with the posting time relocated to the line's trailing edge: company name · nickname (optional role badge) · timestamp.
+
+**Reach for this when** attributing a comment or reply where the vertical budget is a single text line and the author identity is company + nickname. **Skip when** composing the head of a Feed Post or Feed Ad — the avatar + two-line cluster (use [Standard](./standard.md)) — or when the row is a generic entity directory entry with a trailing commit (use [list/entry](../list/entry.md)).
+
+**Layout inset.** `inline` — Compact ships no padding of its own. Sits inside whichever comment / reply row composes it; the host pays surrounding rhythm, divider, and tap target.
+
+## Default
+
+The canonical fill — company name and nickname as independent links, plain timestamp last. Each middot keeps the family's `line-height: 1` rule so the dot never inflates the text line.
+
+```preview
+metadata/compact/default
+---
+import { Metadata } from '@teamblind-chorus/ui';
+
+<Metadata
+  variant="compact"
+  meta={['Maple Mill Bakery', 'ryestarter']}
+  timestamp="35m"
+/>
+```
+
+## Use cases
+
+### With role badge
+
+An object identity item carries `badge` — a single presentational mark rendered after the nickname's link, outside the `<a>`, at the middots' 4px gap. At most one badge rides the nickname, never a stack.
+
+```preview
+metadata/compact/badge
+---
+import { Metadata, Badge } from '@teamblind-chorus/ui';
+
+<Metadata
+  variant="compact"
+  meta={[
+    'Maple Mill Bakery',
+    { label: 'ryestarter', href: '#', badge: <Badge variant="role">Verified</Badge> },
+  ]}
+  timestamp="35m"
+/>
+```
+
+## Slots
+
+- **container** — outer row hosting the single text line. `min-width: 0` so the line truncates inside a flexed comment row.
+- **meta** — identity link row: company name then nickname, each its own `<a>`; siblings separate by middot; never wraps. An object item may carry `badge` — one presentational mark after the link, outside the `<a>`.
+- **timestamp** — trailing plain-text posting time after the last middot. Never a link.
+
+## Anatomy
+
+| Slot          | Token bindings |
+|---------------|----------------|
+| meta          | `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, links inherit; underline on hover |
+| timestamp     | `sys.typo.label.sm` / `sys.color.outline` |
+| dot separator | `·` glyph, `color: sys.color.outline`, **`line-height: 1`** so its line-box equals its font-size — never inflates the text line |
+
+## States
+
+Compact Metadata itself has no lifecycle state. Each identity link carries its own state contract; the timestamp is inert.
+
+## Behavior
+
+- **Dot height constrained.** Every middot separator (between identity items and before the timestamp) uses `line-height: 1` so its line-box matches its font-size — same family-wide rule as the standard head.
+- **Independent affordances.** Identity items are independent `<a>` links — taps land on the link, not the host row. The timestamp is plain text and never intercepts the row's own tap target.
+- **Single line.** The cluster never wraps. When the host row is narrower than the cluster, the identity links truncate; the timestamp keeps its full width.
+- **Time last.** The canonical order is company · nickname · timestamp — the posting time always closes the line.

package/agents/components/metadata/compact.spec.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Metadata",
+  "family": "metadata",
+  "subcomponent": "compact",
+  "description": "One-line author attribution for comment / reply rows — the [Standard](standard.md) head with its primary line (avatar + entity name + timestamp + follow) omitted. Only the secondary meta-link row renders, with the posting time relocated to the line's trailing edge: company name · nickname (bare, no @ prefix, optional single role badge) · timestamp. The identity items keep the standard meta-row grammar (independent `<a>` links, middot separators, badge outside the link); the timestamp is plain text in `sys.color.outline` so the line reads identity-first, time-last. `layoutInset: inline` — atom-shaped, pays no padding of its own; the host comment row owns the gutter / divider / click target.",
+  "element": "div",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "compact"
+    },
+    "meta": {
+      "type": "node",
+      "required": true,
+      "description": "Array of independently-linked identity items — canonical fill is `[company name, nickname]`, the nickname canonically last, displayed bare (no @ prefix). Each entry is either a string (renders as a stub-href link) or a `{ label, href, badge }` object — `badge` is an optional SINGLE presentational mark node rendered AFTER the item's link, outside the <a> (canonical fill: Badge variant=\"role\" on the trailing nickname item). Items separate by middot. Same grammar as the standard sub's `meta`; here it is the whole cluster, so it is required."
+    },
+    "timestamp": {
+      "type": "string",
+      "required": true,
+      "description": "Posting time at the line's trailing edge — plain text (never a link), preceded by a middot, in `label.sm` / `sys.color.outline` so it recedes behind the identity links. Required: the timestamp is what distinguishes a compact attribution from a bare identity row."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Outer row — hosts the single text line. `min-width: 0` so the line can truncate inside a flexed comment row.",
+      "intrinsic": true
+    },
+    "meta": {
+      "required": true,
+      "description": "Identity meta-link row — company name then nickname, each its own `<a>`; siblings separate by middot; `flex-wrap: nowrap` so the cluster stays a single text line. Hover paints the underline on the link alone — the middot stays unstyled.",
+      "intrinsic": true
+    },
+    "timestamp": {
+      "required": true,
+      "description": "Trailing plain-text posting time after the last middot. `sys.typo.label.sm` / `sys.color.outline` — one tonal step further than the identity links.",
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "sizing": {
+    "metaTypo": "sys.typo.label.sm",
+    "metaColor": "sys.color.onSurfaceVariant",
+    "timestampTypo": "sys.typo.label.sm",
+    "timestampColor": "sys.color.outline",
+    "dotColor": "sys.color.outline",
+    "dotLineHeight": "1",
+    "dotLineHeightNote": "Same family-wide rule as the standard sub: the middot separator inherits the surrounding text's font-size but uses `line-height: 1` so its line-box never exceeds the glyph's font-size — the dot never inflates the single text line.",
+    "metaSeparatorInset": "sys.layout.inline.sm"
+  },
+  "states": {
+    "note": "Compact Metadata itself has no lifecycle states — each identity link carries its own state contract; the timestamp is inert."
+  },
+  "behavior": {
+    "dotHeight": "Every middot separator (between identity items and before the timestamp) uses `line-height: 1` so its line-box matches its font-size — same family-wide rule as the standard sub.",
+    "linkAffordances": "Identity items render as independent `<a>` elements — taps land on the link, not the host row. The timestamp is plain text and never intercepts the row's own tap target.",
+    "singleLine": "The cluster is one text line — the meta row never wraps. When the host row is narrower than the cluster, the identity links truncate; the timestamp keeps its full width.",
+    "metaBadge": "An object identity item's `badge` node renders after the item's `<a>` at the middots' 4px (`inline.sm`) gap — the mark annotates the nickname without becoming link content."
+  },
+  "forbidden": [
+    "avatar, entity-name primary line, follow toggle, subtitle, or trailing slot painted on the compact form — those belong to the [Standard](standard.md) head; compact is the one-line text-only shape",
+    "timestamp omitted or rendered as a link — the plain trailing timestamp anchors the line and is what makes it an attribution",
+    "timestamp placed before the identity items — the canonical order is company · nickname · timestamp, time last",
+    "nickname displayed with an @ prefix — nicknames render bare, family-wide",
+    "more than one badge riding the nickname — at most one role mark, never a stack"
+  ]
+}

package/agents/components/metadata/metadata.family.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "metadata",
+  "name": "Metadata",
+  "description": "Author / brand attribution cluster shared by [Feed Post](../feed/post.md) and [Feed Ad](../feed/ad.md). A leading 32-rung [Thumbnail](../thumbnail/thumbnail.md), a primary line (entity name + optional inline timestamp + optional follow toggle), and an optional secondary line (a plain `subtitle` text — canonical 'Sponsored' for ads — or an array of independently-linked `meta` items: location, job function, and — canonically last — the user's nickname, displayed bare with no @ prefix). Optional trailing slot hosts a row-level affordance like the dismiss × button on ads. The one-line [Compact](compact.md) sub drops the primary line for comment / reply attribution: company name · nickname (optional role badge) · trailing timestamp. The middot separator's line-box is constrained to its font-size so the dot never inflates the surrounding text line.",
+  "useCases": [
+    "feed post author attribution",
+    "feed ad brand attribution",
+    "sponsored placement attribution",
+    "comment / reply author attribution (compact)"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "wrapperGuidance": "Atom — pays no inline padding of its own. Sits inside whichever Feed sub-component composes it (Post / Ad card head); the host pays surrounding rhythm. Do NOT wrap Metadata in a per-row padding-inline div.",
+  "usage": {
+    "note": "Both shapes are the single `Metadata` export — the one-line comment shape is `variant=\"compact\"`, NOT a separate `<MetadataCompact>`. Leading thumbnail is the `avatar` prop (NOT `thumbnail`); the secondary line is either a `subtitle` string or a `meta` string array — not children.",
+    "subs": {
+      "standard": {
+        "import": "Metadata",
+        "example": "<Metadata avatar={{ src, alt }} name=\"…\" nameHref=\"#\" timestamp=\"2h\" meta={[\"…\"]} />"
+      },
+      "compact": {
+        "variant": "compact",
+        "example": "<Metadata variant=\"compact\" meta={[\"Maple Mill Bakery\", \"ryestarter\"]} timestamp=\"35m\" />"
+      }
+    }
+  },
+  "spec": "metadata.md",
+  "subcomponents": [
+    {
+      "slug": "standard",
+      "spec": "standard.spec.json",
+      "md": "standard.md",
+      "default": true
+    },
+    {
+      "slug": "compact",
+      "spec": "compact.spec.json",
+      "md": "compact.md"
+    }
+  ]
+}

package/agents/components/metadata/metadata.md

@@ -0,0 +1,26 @@
+# Metadata
+
+Author / brand attribution cluster. The family covers two shapes riding the same `label.sm` text grammar: **[Standard](./standard.md)** — the avatar + two-line head shared by [Feed Post](../feed/post.md) and [Feed Ad](../feed/ad.md) (entity name + optional timestamp / follow on top, subtitle or meta-link row below); **[Compact](./compact.md)** — the one-line comment / reply attribution (company name · nickname · timestamp, no avatar). Per-sub intent lives on each sub's page.
+
+**Layout inset.** `inline` — Metadata ships no padding of its own. Sits inside whichever host composes it (Feed Post / Ad card head, comment row); the host pays surrounding rhythm, divider, and tap target.
+
+## Cross-sub contract
+
+Three rules hold across every family member.
+
+### Dot height
+
+Every middot separator inherits the surrounding text's font-size but uses `line-height: 1`, so its line-box never exceeds the glyph's font-size — the U+00B7 glyph's natural vertical extent never inflates the host text line. The dot paints in `sys.color.outline` and is always inline, never a block element.
+
+### Bare nickname, single badge
+
+The user's nickname is canonically the last identity item and displays bare — no @ prefix. An identity item may carry at most ONE presentational mark node (canonical fill: [badge/role](../badge/badge.md)), rendered after the item's link and outside the `<a>` so the mark never becomes link content.
+
+### Independent link affordances
+
+Every identity item (entity name, meta items) is its own `<a>` — taps land on the link, not the host row. Plain-text parts (timestamp, subtitle) never intercept the row's tap target.
+
+## Sub-components
+
+- **[Standard](./standard.md)** *(default)* — Avatar + two-line attribution head for Feed Post / Feed Ad. Primary line (name + timestamp + follow) over an optional secondary line (subtitle or meta-link row); optional trailing affordance.
+- **[Compact](./compact.md)** — One-line comment / reply attribution: company name · nickname (optional role badge) · trailing plain timestamp. Reached as `variant="compact"` on the same `Metadata` export.

package/agents/components/metadata/standard.md

@@ -0,0 +1,104 @@
+# Standard
+
+The default attribution head of the [Metadata](./metadata.md) family, shared by [Feed Post](../feed/post.md) and [Feed Ad](../feed/ad.md). A leading 32-rung [Thumbnail](../thumbnail/thumbnail.md), a primary line (entity name + optional inline timestamp + optional follow toggle), and an optional secondary line (a plain `subtitle` text — canonical 'Sponsored' for ads — or an array of independently-linked `meta` items: location, job function, and — canonically last — the user's nickname, displayed bare with no @ prefix). Optional trailing slot hosts a row-level affordance like the dismiss × button on ads.
+
+**Reach for this when** composing the head of a Feed Post or Feed Ad — the cluster owns the avatar + identity + meta. **Skip when** you need a one-line comment / reply attribution — company name · nickname · timestamp, no avatar (use [Compact](./compact.md)) — a generic entity directory row with up to three text lines and a single trailing commit (use [list/entry](../list/entry.md)), a labelled-region heading (use [Header](../header/header.md)), or a profile / channel page hero (use [Profile header](../profile-header/profile-header.md)).
+
+**Layout inset.** `inline` — Metadata ships no padding of its own. Sits inside whichever Feed sub-component composes it; the host pays surrounding rhythm.
+
+## Default
+
+The Feed Post shape — avatar + channel name with timestamp + meta link row (location, job, nickname — bare, no @ prefix).
+
+```preview
+metadata/standard/default
+---
+import { Metadata } from '@teamblind-chorus/ui';
+
+<Metadata
+  avatar={{ src: '/placeholder.png', alt: 'Sourdough Bakers' }}
+  name="Sourdough Bakers"
+  nameHref="#"
+  timestamp="2h"
+  meta={['Brooklyn, NY', 'Home baker', 'crustcrumb']}
+/>
+```
+
+## Use cases
+
+### With follow action
+
+The inline follow toggle. A middot separates it from the timestamp; the toggle paints in `sys.color.primary` at rest and `sys.color.onSurfaceVariant` when active. The dot's line-box stays inside its font-size so the row's text-line stays tight.
+
+```preview
+metadata/standard/follow
+---
+import { Metadata } from '@teamblind-chorus/ui';
+
+<Metadata
+  avatar={{ src: '/placeholder.png', alt: 'Indie Game Devs' }}
+  name="Indie Game Devs"
+  nameHref="#"
+  timestamp="4h"
+  followAction
+  meta={['Solo dev', 'First release', 'sidequest']}
+/>
+```
+
+### Sponsored (ad)
+
+Feed Ad shape — `subtitle="Sponsored"` paints a plain caption-tone line under the brand name (no link affordance, no meta row). Pair with `trailing` to host the dismiss × button.
+
+```preview
+metadata/standard/sponsored
+---
+import { Metadata } from '@teamblind-chorus/ui';
+import { XIcon } from '@teamblind-chorus/ui/icons';
+
+<Metadata
+  avatar={{ src: '/placeholder.png', alt: 'Acme Coffee' }}
+  name="Acme Coffee"
+  subtitle="Sponsored"
+  trailing={
+    <button type="button" aria-label="Dismiss ad" onClick={() => {}}>
+      <XIcon size={16} />
+    </button>
+  }
+/>
+```
+
+## Slots
+
+- **container** — outer flex row. `align-items: center`, `sys.layout.inline.md` (8px) gap between avatar, text column, and trailing slot.
+- **avatar** *(optional)* — leading [Thumbnail](../thumbnail/thumbnail.md) at `size={32}`. Forwards every Thumbnail prop verbatim.
+- **text** — two-line text column. Primary line on top, optional secondary line below. `flex: 1 1 auto`, `min-width: 0` so both lines truncate.
+- **name** — entity name. `<a>` when `nameHref` is set, `<span>` otherwise. `sys.typo.label.sm` / `sys.color.onSurface`. Single line; truncates.
+- **timestamp** *(optional)* — inline timestamp after the name. `sys.typo.label.sm` / `sys.color.outline`.
+- **followAction** *(optional)* — bare-text follow toggle at the primary line's trailing edge. Preceded by a middot.
+- **subtitle** *(optional, ad)* — plain caption-tone secondary line. Mutually exclusive with `meta`.
+- **meta** *(optional, post)* — secondary line meta-link row. Each item is its own `<a>`; siblings separate by middot. The last item is canonically the user's nickname, displayed bare (no @ prefix). An object item may carry `badge` — a single presentational mark node rendered after the link, outside the `<a>` (canonical fill: [badge/role](../badge/badge.md) on the nickname — at most one badge rides the nickname, never a stack).
+- **trailing** *(optional)* — trailing-edge slot. Canonical fill is the Feed Ad dismiss × button.
+
+## Anatomy
+
+| Slot          | Token bindings |
+|---------------|----------------|
+| container     | Flex row, `sys.layout.inline.md` (8) gap, `align-items: center` |
+| avatar        | [Thumbnail](../thumbnail/thumbnail.md) `size={32}` |
+| name          | `sys.typo.label.sm` / Semibold / `sys.color.onSurface`, single-line ellipsis |
+| timestamp     | `sys.typo.label.sm` / `sys.color.outline` |
+| dot separator | `·` glyph, `color: sys.color.outline`, **`line-height: 1`** so its line-box equals its font-size — never inflates the text line |
+| follow        | `sys.typo.label.sm` / Semibold / `sys.color.primary` (active → `sys.color.onSurfaceVariant`) |
+| subtitle      | `sys.typo.label.sm` / `sys.color.onSurfaceVariant` |
+| meta          | `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, links inherit; underline on hover |
+
+## States
+
+Metadata itself has no lifecycle state. Each interactive child (name link, follow toggle, meta links, trailing button) carries its own state contract.
+
+## Behavior
+
+- **Dot height constrained.** Every middot separator (between primary-line items and between meta items) uses `line-height: 1` so its line-box matches its font-size. The U+00B7 glyph's natural vertical extent never inflates the parent's text-line.
+- **Independent affordances.** Name and meta items are independent `<a>` links — taps land on the link, not the row. Trailing slot's clicks stop propagating so the dismiss button never commits the surrounding row.
+- **Meta badge outside the link.** An object meta item's `badge` node renders after the item's `<a>` at the middots' 4px (`inline.sm`) gap — the mark annotates the nickname without becoming link content, so the link's hover / focus target stays text-only.
+- **Secondary line mutex.** `subtitle` and `meta` are mutually exclusive — pass one, not both. When both are passed, `meta` wins.