@teamblind-chorus/ui 1.0.1 → 1.2.0

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

@@ -3,7 +3,7 @@
   "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.",
+  "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. A row opts into an embedded **`banner`** — a [Banner](../banner/banner.md) painted below the row's text group at the row's full content width, `sys.layout.stack.xs` (8) below it — for an in-row call-out tied to that row's subject.",
   "element": "ul",
   "props": {
     "embedded": {
@@ -67,6 +67,13 @@
     "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."
+    },
+    "banner": {
+      "required": false,
+      "description": "Optional embedded [Banner](../banner/banner.md) painted **below** the row's text group, separated by `sys.layout.stack.xs` (8). The row flips from a single horizontal line to a vertical stack — the normal leading + label + trailing line on top, the Banner spanning the row's **full content width** (aligned to the same 16px inline inset as the label above it) underneath. Reach for it when a list row needs an in-row call-out tied to that row's subject — a follow-up prompt, a capability nudge, a single-line CTA — rather than a separate full-width Banner detached from the row. The Banner keeps its own fill / radius / padding and its full prop surface (use `appearance=\"accent\"` + `neutralBody` for the quiet-tint call-out shape, a leading `icon`, a `trailingAction` Text Button). It is a **nested-action region**: clicks inside it stop propagating before they reach the row's `onClick`, and the row's hover / pressed overlay is suppressed while the pointer sits on it — same contract as `trailingIcon`.",
+      "accepts": [
+        "banner"
+      ]
     }
   },
   "rowProps": {
@@ -102,6 +109,11 @@
       "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`."
     },
+    "banner": {
+      "type": "node",
+      "optional": true,
+      "description": "Embedded `<Banner>` rendered below the row's text group at the row's full content width, `sys.layout.stack.xs` (8) below it. A nested-action region: its own controls (e.g. a `trailingAction` Text Button) never commit the row, and the row's hover / pressed overlay is suppressed over it. Canonical fill: `<Banner appearance=\"accent\" neutralBody icon={…} trailingAction={…}>…</Banner>`."
+    },
     "divider": {
       "type": "boolean",
       "default": true,
@@ -147,6 +159,8 @@
     "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.",
+    "bannerGap": "sys.layout.stack.xs",
+    "bannerGapNote": "8px (`sys.layout.stack.xs`) vertical gap between the row's text group and an embedded `banner` below it. The Banner spans the row's full content width (the 16px inline inset is the row's own padding, not paid again by the Banner — see banner.md § Layout inset).",
     "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",
@@ -179,6 +193,26 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "inward",
+        "layer": "::after/::before overlay — position:absolute, inset:0, inset box-shadow, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the row is in; never via plain mouse click."
+    },
+    "nestedActionScope": "The hover / pressed overlay is suppressed while the pointer sits on an independent trailing action (a `trailingIcon` button — favorite / mute / Follow). The small control owns the state; the large row does NOT also read as hovered / pressed. The decorative nav chevron is exempt — it is the row's own drill-in affordance, so hovering it still lights the whole row. The visual-state boundary matches the event boundary (the trailing action already stops propagation).",
     "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.",
@@ -208,7 +242,7 @@
     "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.",
+    "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. The slot is a separate hit target visually too: while the pointer hovers / presses it, the row's own hover / pressed overlay is suppressed so the large row never reads as active alongside the small control (the decorative nav chevron is exempt — it lights the row).",
     "truncationNotWrap": "Both label and supportingText truncate; the row never grows to fit long text."
   },
   "forbidden": [
@@ -216,6 +250,8 @@
     "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"
+    "raw `border:` on the row — list seam is the family's bottom divider via outlineVariant",
+    "embedded `banner` painted with a per-child `margin-block` / `padding-block` wrapper to fake the 8px gap — the text-group↔Banner gap is the row stack's `gap: sys.layout.stack.xs`, and the Banner's horizontal inset is the row's own 16px padding; Banner ships no outer margin",
+    "embedded `banner` as a separate `<List>` row beneath the header — the call-out belongs to its row's subject, so it nests inside that row via `item.banner`, not as a sibling row that the divider would fence off"
   ]
 }

package/agents/components/metadata/compact.md

@@ -1,14 +1,16 @@
 # 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.
+> 🇰🇷 한국어: [`i18n/ko/schema/components/metadata/compact.md`](../../../i18n/ko/schema/components/metadata/compact.md)
 
-**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)).
+One-line channel-detail attribution. The slimmed [Standard](./standard.md) head — it keeps the leading 32-rung avatar but drops the primary name line, follow toggle, and subtitle (the info that is unnecessary once the channel context is established). A leading avatar plus the meta-link row, with the posting time relocated to the line's trailing edge: avatar, then company name · nickname (optional role badge), then the timestamp — the timestamp carries no leading middot, separated from the identity cluster by an 8px gap so it reads as a distinct trailing element.
 
-**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.
+**Reach for this when** a single text line is the budget and the channel context is already on screen — channel-detail attribution, comment / reply rows. **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 host 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.
+The canonical fill — a leading 32-rung avatar, 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
@@ -17,6 +19,7 @@ import { Metadata } from '@teamblind-chorus/ui';
 
 <Metadata
   variant="compact"
+  avatar={{ src: '/bread-avatar.png', alt: 'Maple Mill Bakery' }}
   meta={['Maple Mill Bakery', 'ryestarter']}
   timestamp="35m"
 />
@@ -35,6 +38,7 @@ import { Metadata, Badge } from '@teamblind-chorus/ui';
 
 <Metadata
   variant="compact"
+  avatar={{ src: '/bread-avatar.png', alt: 'Maple Mill Bakery' }}
   meta={[
     'Maple Mill Bakery',
     { label: 'ryestarter', href: '#', badge: <Badge variant="role">Verified</Badge> },
@@ -45,7 +49,8 @@ import { Metadata, Badge } from '@teamblind-chorus/ui';
 
 ## Slots
 
-- **container** — outer row hosting the single text line. `min-width: 0` so the line truncates inside a flexed comment row.
+- **avatar** *(optional)* — leading [Thumbnail](../thumbnail/thumbnail.md) at `size={32}`, identical to the Standard head. Vertically centered against the one-line meta cluster.
+- **container** — outer flex row (`align-items: center`) hosting the avatar and the single text line. `min-width: 0` so the line truncates inside a flexed host 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.
 
@@ -53,6 +58,7 @@ import { Metadata, Badge } from '@teamblind-chorus/ui';
 
 | Slot          | Token bindings |
 |---------------|----------------|
+| avatar        | [Thumbnail](../thumbnail/thumbnail.md) `size={32}` |
 | 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 |
@@ -63,7 +69,7 @@ Compact Metadata itself has no lifecycle state. Each identity link carries its o
 
 ## 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.
+- **Dot height constrained.** Every middot separator (between identity items) uses `line-height: 1` so its line-box matches its font-size — same family-wide rule as the standard head. The timestamp carries no leading middot — it is separated from the identity cluster by an 8px (`inline.md`) gap.
 - **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.
+- **Time last.** The canonical order is company · nickname, then the timestamp (no leading middot) — the posting time always closes the line.

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

@@ -3,13 +3,18 @@
   "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.",
+  "description": "One-line channel-detail attribution — the slimmed [Standard](standard.md) head that keeps the leading 32-rung [Thumbnail](../thumbnail/thumbnail.md) but drops the primary name line, follow toggle, and subtitle (the info that is unnecessary once the channel context is already established). A leading avatar plus the identity meta-link row, with the posting time relocated to the line's trailing edge: avatar · 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 row owns the gutter / divider / click target.",
   "element": "div",
   "props": {
     "variant": {
       "type": "literal",
       "value": "compact"
     },
+    "avatar": {
+      "type": "object",
+      "optional": true,
+      "description": "Leading [Thumbnail](../thumbnail/thumbnail.md) at `size={32}` — same prop and rung as the [Standard](standard.md) head. Forwards every Thumbnail prop verbatim (`{ src, alt }`). When omitted, the Thumbnail renders its image-area fallback over `surfaceContainerHigh`."
+    },
     "meta": {
       "type": "node",
       "required": true,
@@ -18,15 +23,23 @@
     "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."
+      "description": "Posting time at the line's trailing edge — plain text (never a link), in `label.sm` / `sys.color.outline` so it recedes behind the identity links. NOT preceded by a middot: the time is separated from the identity cluster by an `inline.md` (8) gap so it reads as a distinct trailing element rather than another identity item (mirrors the Standard head's name↔time treatment). 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.",
+      "description": "Outer row — flex row, `align-items: center`, hosting the leading avatar and the single text line. `min-width: 0` so the line can truncate inside a flexed host row.",
       "intrinsic": true
     },
+    "avatar": {
+      "required": false,
+      "description": "Leading [Thumbnail](../thumbnail/thumbnail.md) at `size={32}` — identical to the Standard head. Vertically centered against the one-line meta cluster.",
+      "accepts": [
+        "thumbnail"
+      ],
+      "rendersAs": "thumbnail:32"
+    },
     "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.",
@@ -34,7 +47,7 @@
     },
     "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.",
+      "description": "Trailing plain-text posting time after the identity cluster — no leading middot, separated by an `inline.md` (8) gap. `sys.typo.label.sm` / `sys.color.outline` — one tonal step further than the identity links.",
       "accepts": [
         "text"
       ]
@@ -54,13 +67,13 @@
     "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.",
+    "dotHeight": "Every middot separator (between identity items) uses `line-height: 1` so its line-box matches its font-size — same family-wide rule as the standard sub. The timestamp carries no leading middot — it is separated from the identity cluster by an `inline.md` gap.",
     "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",
+    "entity-name primary line, follow toggle, subtitle, or trailing slot painted on the compact form — those belong to the [Standard](standard.md) head; compact keeps only the leading avatar plus the one-line identity / timestamp",
     "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",

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

@@ -2,7 +2,7 @@
   "$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.",
+  "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 keeps the leading 32-rung avatar but drops the primary name line, follow toggle, and subtitle — channel-detail attribution: avatar · 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",
@@ -13,7 +13,7 @@
   "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.",
+    "note": "Both shapes are the single `Metadata` export — the one-line channel-detail shape is `variant=\"compact\"`, NOT a separate `<MetadataCompact>`. Leading thumbnail is the `avatar` prop (NOT `thumbnail`) on both shapes; the secondary line is either a `subtitle` string or a `meta` string array — not children.",
     "subs": {
       "standard": {
         "import": "Metadata",
@@ -21,7 +21,7 @@
       },
       "compact": {
         "variant": "compact",
-        "example": "<Metadata variant=\"compact\" meta={[\"Maple Mill Bakery\", \"ryestarter\"]} timestamp=\"35m\" />"
+        "example": "<Metadata variant=\"compact\" avatar={{ src, alt }} meta={[\"Maple Mill Bakery\", \"ryestarter\"]} timestamp=\"35m\" />"
       }
     }
   },

package/agents/components/metadata/metadata.md

@@ -1,6 +1,8 @@
 # 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.
+> 🇰🇷 한국어: [`i18n/ko/schema/components/metadata/metadata.md`](../../../i18n/ko/schema/components/metadata/metadata.md)
+
+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 channel-detail attribution (leading 32-rung avatar · company name · nickname · timestamp), the slimmed head with the name line, follow, and subtitle dropped. 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.
 
@@ -23,4 +25,4 @@ Every identity item (entity name, meta items) is its own `<a>` — taps land on
 ## 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.
+- **[Compact](./compact.md)** — One-line channel-detail attribution: leading 32-rung avatar · company name · nickname (optional role badge) · trailing plain timestamp. The slimmed Standard head with the primary name line, follow, and subtitle dropped. Reached as `variant="compact"` on the same `Metadata` export.

package/agents/components/metadata/standard.md

@@ -1,5 +1,7 @@
 # Standard
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/metadata/standard.md`](../../../i18n/ko/schema/components/metadata/standard.md)
+
 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)).
@@ -67,6 +69,28 @@ import { XIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
+### With role badge
+
+A meta item in object form carries `badge` — a single presentational mark rendered after the item's link, outside the `<a>`, at the middots' 4px gap. Canonical fill: a role [Badge](../badge/badge.md) on the trailing nickname. At most one badge rides the nickname, never a stack.
+
+```preview
+metadata/standard/badge
+---
+import { Metadata, Badge } from '@teamblind-chorus/ui';
+
+<Metadata
+  avatar={{ src: '/placeholder.png', alt: 'Sourdough Bakers' }}
+  name="Sourdough Bakers"
+  nameHref="#"
+  timestamp="2h"
+  meta={[
+    'Brooklyn, NY',
+    'Home baker',
+    { label: 'crustcrumb', href: '#', badge: <Badge variant="role">Verified</Badge> },
+  ]}
+/>
+```
+
 ## Slots
 
 - **container** — outer flex row. `align-items: center`, `sys.layout.inline.md` (8px) gap between avatar, text column, and trailing slot.

package/agents/components/nav-card/nav-card.md

@@ -1,5 +1,7 @@
 # Nav card
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/nav-card/nav-card.md`](../../../i18n/ko/schema/components/nav-card/nav-card.md)
+
 A bounded single-row card — outlined rounded surface with a label, optional supporting line, and optional trailing affordance. Two variants pick the trailing shape: `default` ships no trailing icon (bare labelled tile), `nav` auto-renders the right-pointing chevron (explicit drill-in). The whole card is the tap target.
 
 **Reach for this when** one row needs to read as its own discrete affordance — a labelled scope tile (`default`), a standalone settings drill-in (`nav`), a picker trigger, or a channel / sub-brand entry card. **Skip when** rows stack into a vertical column (use a [List](../list/list.md) drill-in row — `nav: true`), the action is a commit (use [Button](../button/button.md)), or the surface is purely informational (use [Banner](../banner/banner.md)).

package/agents/components/nav-card/nav-card.spec.json

@@ -126,6 +126,15 @@
     "pressed": {
       "overlay": { "color": "label", "opacity": "sys.state.pressed" }
     },
+    "focused": {
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": { "width": "sys.borderWidth.hairline", "color": "sys.color.focusInset" },
+        "outerRing": { "width": "sys.borderWidth.thin", "color": "sys.color.focus" }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual — a three-layer outward ring on the card's outer edge, with no state-overlay tint (the ring alone carries focus here). Mirrors the `focusIndicator` block for spec-only renderers. Composes over the lifecycle state the card is in."
+    },
     "disabled": {
       "containerOpacity": "sys.state.disabled",
       "pointerEvents": "none"

package/agents/components/nav-list/nav-list.md

@@ -1,5 +1,7 @@
 # Nav list
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/nav-list/nav-list.md`](../../../i18n/ko/schema/components/nav-list/nav-list.md)
+
 A vertical label-only nav list — labelled block where each row carries a label (and an optional supporting line) plus a trailing chevron Icon Button, and routes via `href` / `onClick`. Bundles a [Header](../header/header.md) over a label-only [List](../list/entry.md) `variant="entry"` so the section title and the route group come as one composition. Anatomy is intentionally label-only — `thumbnail` is omitted on every row, the leading column collapses, and the trailing rail carries a default [Icon Button](../button/icon.md) with a right-pointing chevron.
 
 **Reach for this when** the screen shows a category index, settings menu, or any "pick a sub-page" set where each row is purely a route target. **Skip when** the rows need a leading thumbnail (use [DirectoryList](../directory-list/directory-list.md)) or the rows commit in place rather than route (use [List](../list/standard.md) `variant="standard"`).

package/agents/components/navigation-bar/main.md

@@ -1,5 +1,7 @@
 # Main
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/navigation-bar/main.md`](../../../i18n/ko/schema/components/navigation-bar/main.md)
+
 The landing-screen top bar — anchored to a tab root (feed, inbox, profile). A leading menu glyph plus left-aligned page name sit at the start; **up to four** trailing icon actions (conventionally search, chat, profile) sit at the end. Title carries the system's largest page-level rung (`typo.heading.lg`, 24/Semibold). The same row also serves a **drill-in (content-detail) screen** — pass `onBack` instead of `onMenuClick` and the leading glyph swaps to a back chevron, with the trailing cluster carrying up to four actions (see [Use cases](#use-cases)).
 
 **Reach for this when** the screen is a tab root and needs the menu drawer plus a small set of global affordances, **or** when it's a content-detail drill-in (a post / article reached from a feed) needing back navigation plus a share-and-save cluster. **Skip when** you need a centred title with a single action (use [Sub](./sub.md)) or are on a dedicated search page (use [Search](./search.md)).

package/agents/components/navigation-bar/navigation-bar.md

@@ -1,5 +1,7 @@
 # Navigation bar
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/navigation-bar/navigation-bar.md`](../../../i18n/ko/schema/components/navigation-bar/navigation-bar.md)
+
 The top app bar — a horizontal strip pinned to the top of a screen that names the screen and exposes its highest-priority actions. Three sub-flavors share this contract: **Main** (landing-screen bar), **Sub** (drill-in bar with centred title), and **Search** (search-page bar with a bare-text input). All three sit at 16px inline / 8px block padding and delegate icon slots to [Icon Button](../button/icon.md).
 
 **Layout inset.** `full-bleed` — sits flush at the top of the page shell. The bar owns its own `16px inline / 8px block` padding via `layout.container.*`; do **not** wrap it in another `padding-inline` / `px-*` / `style={{ padding: … }}` div. The bar is pinned chrome, not a `<main>` child — sits *outside* the `<main>` that pays `sys.layout.page.*`. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).

package/agents/components/navigation-bar/search.md

@@ -1,5 +1,7 @@
 # Search
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/navigation-bar/search.md`](../../../i18n/ko/schema/components/navigation-bar/search.md)
+
 The search top bar — anchored to a dedicated search page reached from a [Main](./main.md) or [Sub](./sub.md) bar's search trigger. Owns the entire search affordance: leading back-arrow Icon Button, single bare-text input filling the row, conditional trailing clear (*×*). Drops the centred title — the input *is* the focus.
 
 **Reach for this when** the entire screen exists to capture a query and show results. **Skip when** search is one affordance among several on a tab root (use [Main](./main.md) with a search trailing action) or when the field lives in-line with content (use the [search](../form-field/search.md) form-field).

package/agents/components/navigation-bar/sub.md

@@ -1,5 +1,7 @@
 # Sub
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/navigation-bar/sub.md`](../../../i18n/ko/schema/components/navigation-bar/sub.md)
+
 The drill-in top bar — anchored to every screen one step inside a flow. Centred page name, flanked by two independent side slots — each optionally a [Text Button](../button/text.md), an [Icon Button](../button/icon.md), or a [Toolbar Button](../button/toolbar.md) / text link, chosen per side. The title itself is optional too: omit it when the side actions say everything (composer bars). Title drops from Main's `typo.heading.lg` to `typo.heading.sm` (16/Semibold).
 
 **Reach for this when** the screen is one step inside a flow and needs a back affordance plus a single primary action. **Skip when** you're on a tab root (use [Main](./main.md)) or a dedicated search page (use [Search](./search.md)).

package/agents/components/page-shell/page-shell.family.json

@@ -17,6 +17,6 @@
   },
   "spec": "page-shell.md",
   "subcomponents": [
-    { "slug": "page-shell", "md": "page-shell.md", "default": true, "specMissing": true }
+    { "slug": "page-shell", "spec": "page-shell.spec.json", "md": "page-shell.md", "default": true }
   ]
 }

package/agents/components/page-shell/page-shell.md

@@ -1,5 +1,7 @@
 # PageShell
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/page-shell/page-shell.md`](../../../i18n/ko/schema/components/page-shell/page-shell.md)
+
 The app scaffold that **pins** `NavigationBar` (top) and `TabBar` (bottom) while only the body scrolls.
 
 ## Why it exists
@@ -31,6 +33,39 @@ renders:
 </div>
 ```
 
+## Default
+
+`NavigationBar` pins to the top, `TabBar` pins to the bottom, and only the `<main>` body scrolls. Scroll the list inside the window — the bars stay put while the content moves.
+
+```preview
+page-shell/default
+---
+import { PageShell, NavigationBar, TabBar, List } from '@teamblind-chorus/ui';
+
+<PageShell
+  nav={<NavigationBar variant="main" title={…} />}
+  tabBar={<TabBar value={tab} onChange={setTab} items={items} />}
+>
+  <List items={settings} />
+</PageShell>
+```
+
+### Inline body
+
+When the screen carries inline (non-full-bleed) content, pass `bodyProps` to add the page gutter to `<main>` so the body sits inset from the screen edge while the bars stay pinned.
+
+```preview
+page-shell/inline-body
+---
+<PageShell
+  bodyProps={{ style: { paddingInline: 'var(--sys-layout-page-md)' } }}
+  nav={<NavigationBar variant="sub" title="About" />}
+  tabBar={<TabBar value={tab} onChange={setTab} items={items} />}
+>
+  {/* inline content — honors the page gutter */}
+</PageShell>
+```
+
 ## Props
 
 | prop | type | notes |

package/agents/components/page-shell/page-shell.spec.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "PageShell",
+  "family": "page-shell",
+  "description": "The app scaffold that PINS `NavigationBar` (top) and `TabBar` (bottom) while only the body scrolls. Chorus bars render in flow and do NOT self-pin; PageShell is the pinning mechanism — a full-height (100dvh) flex column whose middle `<main>` is the sole scroll region (`flex: 1 1 auto; min-height: 0; overflow-y: auto; overscroll-behavior: contain`). The `nav` and `tabBar` slots render as flow children at their natural height; without this skeleton the whole page scrolls as one piece and both bars drift off-screen on long content. The shell owns ONLY the pin/scroll mechanics — not a content gutter — so the body honors the normal full-bleed / inline padding contract; pass `bodyProps` to add the page gutter to `<main>` when the screen carries inline (non-full-bleed) content. Never give the bars `position: sticky` / `fixed`: that double-applies their own `env(safe-area-inset-*)`. Single-spec family.",
+  "element": "div",
+  "props": {
+    "nav": {
+      "type": "node",
+      "optional": true,
+      "description": "Rendered in flow at the top — a `NavigationBar`. Pays its own `safe-area-inset-top`; the shell does NOT re-pay it. Pinned by the flex column, never by `position: sticky` / `fixed`."
+    },
+    "tabBar": {
+      "type": "node",
+      "optional": true,
+      "description": "Rendered in flow at the bottom — a `TabBar`. Pays its own `safe-area-inset-bottom`; the shell does NOT re-pay it. Pinned by the flex column, never by `position: sticky` / `fixed`."
+    },
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "The scrolling body content — the sole scroll region. Rendered inside `<main class=\"chorus-page-shell__body\">`."
+    },
+    "bodyProps": {
+      "type": "object",
+      "optional": true,
+      "description": "Spread onto `<main>` — use to add a page gutter (`style={{ paddingInline: 'var(--sys-layout-page-md)' }}`) when the screen carries inline (non-full-bleed) content. `className` composes with `chorus-page-shell__body`; the rest spread as-is. Do NOT use it to re-pay a bar's safe-area inset."
+    },
+    "className": {
+      "type": "string",
+      "optional": true,
+      "description": "Composes with the shell root's own `chorus-page-shell` class. Use for placement only; never to override the pin/scroll mechanics."
+    }
+  },
+  "slots": {
+    "nav": {
+      "required": false,
+      "description": "Flow child at the top of the column, rendered at its natural height (typically a `NavigationBar`). Stays pinned because only the body scrolls beneath it. Pays its own viewport-top safe-area inset.",
+      "omittedBehavior": "collapse",
+      "accepts": [
+        "navigation-bar"
+      ]
+    },
+    "body": {
+      "required": true,
+      "intrinsic": true,
+      "description": "The `<main>` element — the ONLY scroll region. `flex: 1 1 auto; min-height: 0; overflow-y: auto; overscroll-behavior: contain`. Takes the remaining column height between the bars and scrolls its children; the `min-height: 0` line is load-bearing (without it the flex body refuses to shrink and the page scrolls as one piece). The shell renders this element itself and fills it with `children`.",
+      "omittedBehavior": "error"
+    },
+    "tabBar": {
+      "required": false,
+      "description": "Flow child at the bottom of the column, rendered at its natural height (typically a `TabBar`). Stays pinned because only the body scrolls above it. Pays its own viewport-bottom safe-area inset.",
+      "omittedBehavior": "collapse",
+      "accepts": [
+        "tab-bar"
+      ]
+    }
+  },
+  "sizing": {
+    "shellDisplay": "flex",
+    "shellDirection": "column",
+    "shellHeight": "100dvh",
+    "bodyFlex": "1 1 auto",
+    "bodyMinHeight": "0",
+    "bodyOverflowY": "auto",
+    "bodyOverscrollBehavior": "contain",
+    "bodyGutter": "sys.layout.page.md",
+    "note": "The shell paints no fill of its own — it is a transparent flex column; `nav`, `body`, and `tabBar` each carry their own surface. The dvh / flex / min-height values are fixed layout mechanics, not a size axis. `bodyGutter` (`sys.layout.page.md`) is NOT applied by default — it is the canonical page-rail value the consumer opts into via `bodyProps` when the body carries inline (non-full-bleed) content; full-bleed screens leave the body gutter at 0."
+  },
+  "behavior": {
+    "pinMechanism": "A full-height flex column (`display: flex; flex-direction: column; height: 100dvh`) where `nav` and `tabBar` are flow children at their natural height and `<main>` takes the remaining space as the sole scroll region. The bars stay put on long lists because the body — not the shell or the page — is what scrolls.",
+    "soleScrollRegion": "Only `<main class=\"chorus-page-shell__body\">` scrolls (`overflow-y: auto`). `min-height: 0` lets the body shrink below its content height so it (not the shell) becomes the scroll container; `overscroll-behavior: contain` keeps scroll chaining from leaking to the document.",
+    "barsDoNotSelfPin": "Chorus bars render in flow and pay only their own `env(safe-area-inset-*)`; pinning is the shell's job. Never give `NavigationBar` / `TabBar` `position: sticky` / `fixed` — that double-applies their safe-area insets. A dev-only `usePinnedBarGuard` warns in the console when a bar is rendered inside a scrolling region instead of a shell.",
+    "noContentGutter": "PageShell owns only the pin/scroll mechanics, not a content gutter — the body honors the normal full-bleed / inline padding contract. Pass `bodyProps={{ style: { paddingInline: 'var(--sys-layout-page-md)' } }}` to add the page gutter when the screen carries inline content.",
+    "overlayNavExempt": "The overlay `NavigationBar` (floating over a `ProfileHeader` cover) is the exception — it scrolls with the hero by design and is NOT pinned by the shell; place it inside the body, not the `nav` slot."
+  },
+  "forbidden": [
+    "NavigationBar / TabBar given position: sticky / fixed inside the shell — the flex column is the pin; sticky/fixed double-applies the bar's safe-area inset",
+    "a bar rendered inside the scrolling body (nav/tabBar passed as children) instead of the nav / tabBar slot — it scrolls away with the content on long lists",
+    "hand-rolling the flex-column recipe instead of using PageShell — the min-height:0 / overflow-y:auto / overscroll-behavior:contain mechanics ship in the component, not a copy-paste CSS recipe",
+    "omitting min-height:0 on the body (or overriding it) — without it the flex body refuses to shrink and the whole page scrolls as one piece, drifting the bars off-screen",
+    "wrapping the shell in another scroll container or giving the shell root overflow:auto — the body is the sole scroll region; a second scroller breaks the pin",
+    "re-paying a bar's safe-area inset via bodyProps padding-top / padding-bottom — each bar owns its own viewport inset; the shell and body never re-pay it",
+    "adding a default content gutter to the shell — PageShell owns no gutter; inline padding is opted into per-screen via bodyProps, never baked into the shell"
+  ]
+}

package/agents/components/pagination/pagination.family.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "pagination",
+  "name": "Pagination",
+  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span` / inline-flex) sized to its dots — one 6px dot per page; the active dot paints `sys.color.onSurface`, the rest paint `sys.color.outlineVariant`. Presentational only (`aria-hidden`) — the host pager owns horizontal placement (the carousels center it), scroll position, active-index tracking, and keyboard reach; tapping a dot does not navigate. Renders nothing below two pages. Single appearance, single rung. Single-spec family.",
+  "useCases": [
+    "carousel page position (PostCarousel / ProfileCarousel)",
+    "swipeable media gallery position",
+    "onboarding pager position"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "pagination.md",
+  "usage": {
+    "note": "Decorative only — the root is `aria-hidden` and dots are not buttons. An inline element with intrinsic width: the host owns horizontal placement (e.g. centering under its pager) as well as the active index (e.g. via IntersectionObserver on its snap targets), and MUST keep later pages keyboard-reachable on its own. Renders nothing when `count` < 2.",
+    "example": "<Pagination count={5} activeIndex={2} />"
+  },
+  "subcomponents": [
+    {
+      "slug": "pagination",
+      "spec": "pagination.spec.json",
+      "md": "pagination.md",
+      "default": true
+    }
+  ]
+}