@teamblind-chorus/ui 1.0.0

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

@@ -0,0 +1,152 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Metadata",
+  "family": "metadata",
+  "subcomponent": "standard",
+  "description": "Author / brand attribution cluster shared by [Feed Post](../feed/post.md) and [Feed Ad](../feed/ad.md). Composes a leading 32-rung [Thumbnail](../thumbnail/thumbnail.md), a primary line (entity name + optional inline timestamp + optional follow toggle), and a secondary line (either 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). An optional trailing slot hosts a row-level affordance (dismiss × for ads). The dot separator is constrained so its line-box never exceeds its font-size — middle-dot glyphs that would otherwise inflate the row's line-height stay flush with the surrounding text. `layoutInset: inline` — atom-shaped, pays no padding of its own; the host (Feed Post / Feed Ad card head) owns the row gutter / divider / click target.",
+  "element": "div",
+  "props": {
+    "avatar": {
+      "type": "object",
+      "optional": true,
+      "description": "Forwarded to [Thumbnail](../thumbnail/thumbnail.md) verbatim at `size={32}`. When omitted, the Thumbnail renders its image-area fallback over `surfaceContainerHigh`."
+    },
+    "name": {
+      "type": "string",
+      "required": true,
+      "description": "Primary line entity name — channel topic (Post) or brand (Ad). Single line; truncates with ellipsis."
+    },
+    "nameHref": {
+      "type": "string",
+      "optional": true,
+      "description": "Destination URL for the entity name. When present, the name renders as an `<a>`; otherwise as a `<span>`."
+    },
+    "timestamp": {
+      "type": "string",
+      "optional": true,
+      "description": "Inline timestamp painted after the name on the primary line, in `label.sm` / `sys.color.outline` — one tonal step further than the name. Reach for it on Feed Post; omit on Feed Ad."
+    },
+    "followAction": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether to paint the inline follow toggle after the timestamp. When `true`, a dot separator + Follow/Following text toggle render at the primary line's trailing edge. State is controlled via `followed` + `onFollowChange`."
+    },
+    "followed": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether the viewer follows this entity. Drives the inline follow toggle's label and `aria-pressed`."
+    },
+    "onFollowChange": {
+      "type": "function",
+      "optional": true,
+      "description": "Fires with the next `followed` value when the inline follow toggle is tapped."
+    },
+    "subtitle": {
+      "type": "string",
+      "optional": true,
+      "description": "Secondary line plain text — canonical use is 'Sponsored' on Feed Ad. Mutually exclusive with `meta` (when both are passed, `meta` wins)."
+    },
+    "meta": {
+      "type": "node",
+      "optional": true,
+      "description": "Array of independently-linked metadata items rendered on the secondary line. 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; at most one badge rides the nickname). The last item is canonically the user's nickname, displayed bare (no @ prefix). Items separate by middot. Reach for it on Feed Post; omit on Feed Ad."
+    },
+    "trailing": {
+      "type": "node",
+      "optional": true,
+      "description": "Trailing-edge slot. Canonical fill: the Feed Ad dismiss × button. The slot's hit target is its own — taps on it never propagate to the entity-name link."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Outer flex row — `align-items: center`, `sys.layout.inline.md` (8px) gap between avatar, text block, and trailing slot.",
+      "intrinsic": true
+    },
+    "avatar": {
+      "required": false,
+      "description": "Leading [Thumbnail](../thumbnail/thumbnail.md) at `size={32}`. Every Thumbnail prop forwarded verbatim.",
+      "accepts": [
+        "thumbnail"
+      ],
+      "rendersAs": "thumbnail:32"
+    },
+    "text": {
+      "required": true,
+      "description": "Two-line text column. Primary line (name + optional timestamp + optional follow) on top; optional secondary line (subtitle text OR meta-link row) below. `flex: 1 1 auto`, `min-width: 0` so both lines truncate.",
+      "intrinsic": true
+    },
+    "name": {
+      "required": true,
+      "description": "Entity name. `sys.typo.label.sm` (12 / Semibold) / `sys.color.onSurface`. Renders as `<a>` when `nameHref` is set, `<span>` otherwise. Single line; truncates with ellipsis.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "timestamp": {
+      "required": false,
+      "description": "Inline timestamp after the name. `sys.typo.label.sm` (12 / Semibold) / `sys.color.outline` — one tonal step further than the name so the timestamp recedes.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "followAction": {
+      "required": false,
+      "description": "Inline follow toggle at the primary line's trailing edge. Bare text affordance (no chrome) — `sys.color.primary` at rest, `sys.color.onSurfaceVariant` when active. A `·` separator precedes it.",
+      "intrinsic": true
+    },
+    "subtitle": {
+      "required": false,
+      "description": "Secondary line plain text. `sys.typo.label.sm` / `sys.color.onSurfaceVariant`. Mutually exclusive with `meta`.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "meta": {
+      "required": false,
+      "description": "Secondary line meta-link row. Each item is its own `<a>` link; sibling items separate by middot. Hover paints the underline on the link alone — the middot stays unstyled.",
+      "intrinsic": true
+    },
+    "trailing": {
+      "required": false,
+      "description": "Trailing-edge slot — typically a dismiss × button on Feed Ad. Its own hit target; clicks don't propagate to the surrounding row.",
+      "accepts": [
+        "button",
+        "icon"
+      ]
+    }
+  },
+  "sizing": {
+    "containerGap": "sys.layout.inline.md",
+    "containerAlign": "center",
+    "avatarSize": 32,
+    "nameTypo": "sys.typo.label.sm",
+    "nameColor": "sys.color.onSurface",
+    "timestampTypo": "sys.typo.label.sm",
+    "timestampColor": "sys.color.outline",
+    "subtitleTypo": "sys.typo.label.sm",
+    "subtitleColor": "sys.color.onSurfaceVariant",
+    "metaTypo": "sys.typo.label.sm",
+    "metaColor": "sys.color.onSurfaceVariant",
+    "dotColor": "sys.color.outline",
+    "dotLineHeight": "1",
+    "dotLineHeightNote": "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 — keeps the row's text-line tight even when the inherited line-height would otherwise allow extra vertical space around the middot.",
+    "primaryRowGap": "sys.layout.inline.md",
+    "metaRowGap": "0",
+    "metaSeparatorInset": "sys.layout.inline.sm"
+  },
+  "states": {
+    "note": "Metadata itself has no lifecycle states — each interactive child (name link, follow toggle, meta links, trailing button) carries its own state contract."
+  },
+  "behavior": {
+    "dotHeight": "Every middot separator inside Metadata (between name/timestamp/follow on the primary line, and between meta items on the secondary line) uses `line-height: 1` so its line-box matches its font-size. This prevents the U+00B7 glyph's natural vertical extent from inflating the parent's line-box.",
+    "linkAffordances": "Name and meta items render as `<a>` elements when an `href` is supplied — each is an independent affordance. Taps on the trailing slot stop propagating.",
+    "compositionInsideFeed": "Both [Feed Post](../feed/post.md) and [Feed Ad](../feed/ad.md) compose Metadata at the head of the card. Post passes `timestamp` + `meta`; Ad passes `subtitle` + `trailing` (dismiss button)."
+  },
+  "forbidden": [
+    "Metadata rendered outside a Feed Post / Feed Ad host — the cluster is the author / brand attribution primitive that pairs with Feed; for generic 'who / what this is + commit' rows, use [list/entry](../list/entry.md)",
+    "subtitle paired with meta — the secondary line is mutually exclusive; pick one (meta for Post, subtitle for Ad)",
+    "middot separators painted as block elements — the dot is always inline so it inherits the surrounding text's baseline",
+    "name rendered as a button — the name is a link to the entity page, never a commit"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "nav-card",
+  "name": "NavCard",
+  "description": "Bounded single-row card \u2014 an outlined rounded surface with a label, an optional supporting line, and an optional trailing affordance. Two variants select the trailing shape: `default` ships no trailing icon (bare labelled tile), `nav` auto-renders the right-pointing chevron (the drill-in form). The whole card is the tap target. Reach for it when a [List](../list/list.md) drill-in row (`text` with `nav: true`) needs to read as its own discrete affordance rather than as one entry in a stack \u2014 a labelled scope tile (default), a standalone settings drill-in (nav), a picker trigger, or an entity entry card. Single-spec family.",
+  "useCases": [
+    "standalone labelled tile (default)",
+    "single settings drill-in (nav)",
+    "picker trigger",
+    "channel / scope selector card",
+    "bounded-surface drill-in"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "wrapperGuidance": "Inline card. NavCard has its own internal padding + border-radius + outline + 48 min-height, and `width: 100%` so it fills the host column. It ships no outer margin and does NOT claim the page rail. The host owns the surrounding inset: when placed at the page-shell level, the shell's `layout.page.md` gutter provides the 16px horizontal safe zone; when wrapped inside another host (Section body, BottomSheet content slot, SideSheet column, NavCardGroup stack), that host's container padding governs the inset. Vertical spacing between NavCards is paid by `NavCardGroup`'s `gap: var(--sys-layout-stack-xs)` (8px) \u2014 never paint per-child `margin-block` on NavCard.",
+  "usage": {
+    "note": "The trailing drill-in chevron comes from `variant=\"nav\"`, not a trailing child; `leading` takes a node (Icon / Thumbnail).",
+    "example": "<NavCard variant=\"nav\" label=\"…\" supportingText=\"…\" leading={<Icon />} href=\"#\" />"
+  },
+  "spec": "nav-card.md",
+  "subcomponents": [
+    {
+      "slug": "nav-card",
+      "spec": "nav-card.spec.json",
+      "md": "nav-card.md",
+      "default": true
+    }
+  ]
+}

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

@@ -0,0 +1,179 @@
+# Nav card
+
+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)).
+
+**Layout inset.** `inline` — carries its own internal `16px inline / 8px block` padding (`layout.container.md` / `layout.container.xs`), `radius.md` corners, hairline outline, 48px min-height, and `width: 100%` so it fills the host column. Ships no outer margin and does not claim the page rail. The host owns the surrounding inset — page shell gutter at the route level, container padding inside a `<Section>` / `<BottomSheet>` / `<SideSheet>` / `<NavCardGroup>`. Vertical spacing between cards comes from `NavCardGroup`'s `gap: var(--sys-layout-stack-xs)` (8) — never paint per-child `margin-block` on NavCard.
+
+## Default
+
+The bare form — label only, no trailing icon. Reach for it when the card is a labelled tile (scope label, status card, informational entry) and the drill-in chevron would over-promise navigation.
+
+```preview
+nav-card/default
+---
+import { NavCard } from '@teamblind-chorus/ui';
+
+<NavCard label="Cell label here" href="#" />
+```
+
+## Use cases
+
+### Nav (with trailing chevron)
+
+`variant="nav"` auto-renders the right-pointing chevron — the explicit drill-in form. Reach for it when the card routes into another surface (settings detail, picker, sub-flow).
+
+```preview
+nav-card/nav
+---
+import { NavCard } from '@teamblind-chorus/ui';
+
+<NavCard variant="nav" label="Cell label here" href="#" />
+```
+
+### With supporting text
+
+Two-line variant — primary label on top, supporting metadata below at `onSurfaceVariant`. Works with either variant; pair with `nav` when the drill-in is metadata-bearing.
+
+```preview
+nav-card/supporting
+---
+import { NavCard } from '@teamblind-chorus/ui';
+
+<NavCard
+  variant="nav"
+  label="Saved posts"
+  supportingText="47 posts across 9 channels"
+  href="#"
+/>
+```
+
+### With leading icon
+
+A leading 16 × 16 glyph at the inline padding edge. The icon vertically centres on the row's parent block — same `align-items: center` axis as the label column and trailing slot, so the glyph sits on the same midline as the label (one-line) or label + supportingText block (two-line).
+
+```preview
+nav-card/leading-icon
+---
+import { NavCard } from '@teamblind-chorus/ui';
+import { BellIcon } from '@teamblind-chorus/ui/icons';
+
+<NavCard
+  label="Notifications"
+  leading={<BellIcon size={16} />}
+  supportingText="3 unread mentions"
+  href="#"
+/>
+```
+
+### With leading thumbnail
+
+A leading 32-rung [Thumbnail](../thumbnail/thumbnail.md) — used when the drill target is an entity (channel, person, brand) rather than a chrome action. The thumbnail block-centres on the row's vertical midline, same as an icon leading.
+
+```preview
+nav-card/leading-thumbnail
+---
+import { NavCard, Thumbnail } from '@teamblind-chorus/ui';
+
+<NavCard
+  variant="nav"
+  label="Hyundai Motor"
+  supportingText="Private · My company"
+  leading={<Thumbnail size={32} alt="Hyundai" />}
+  href="#"
+/>
+```
+
+### Group
+
+Multiple NavCards stacked vertically as a `NavCardGroup` — each card stays its own outlined affordance, separated by `sys.layout.stack.xs` (8px) gap. Use when several drill-in cards share a section but should read as discrete cards (vs a List drill-in rail — `text` rows with `nav: true` — where rows tile flush with hairline dividers).
+
+```preview
+nav-card/group
+---
+import { NavCard, NavCardGroup } from '@teamblind-chorus/ui';
+import { BellIcon, BookmarkIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+
+<NavCardGroup aria-label="Account">
+  <NavCard variant="nav" label="Profile" supportingText="Display name, avatar, bio" leading={<ProfileIcon size={16} />} href="#" />
+  <NavCard variant="nav" label="Saved posts" supportingText="47 posts across 9 channels" leading={<BookmarkIcon size={16} />} href="#" />
+  <NavCard variant="nav" label="Notifications" leading={<BellIcon size={16} />} href="#" />
+</NavCardGroup>
+```
+
+### Surface (opaque tier on a non-`surface` host)
+
+`appearance="surface"` paints the card with its own `sys.color.surface` fill so it reads as an opaque tier. Reach for it when the card sits on a transparent / non-`surface` host (coloured hero, tonal band, BottomSheet content slot) and the default transparent fill would let the card blend in.
+
+```preview
+nav-card/surface
+---
+import { NavCard, NavCardGroup } from '@teamblind-chorus/ui';
+import { BellIcon, BookmarkIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+
+<div
+  style={{
+    background: 'var(--sys-color-surfaceContainerLow)',
+    padding: 'var(--sys-layout-container-md)',
+    borderRadius: 'var(--sys-radius-lg)',
+  }}
+>
+  <NavCardGroup aria-label="Account">
+    <NavCard variant="nav" appearance="surface" label="Profile" supportingText="Display name, avatar, bio" leading={<ProfileIcon size={16} />} href="#" />
+    <NavCard variant="nav" appearance="surface" label="Saved posts" supportingText="47 posts across 9 channels" leading={<BookmarkIcon size={16} />} href="#" />
+    <NavCard variant="nav" appearance="surface" label="Notifications" leading={<BellIcon size={16} />} href="#" />
+  </NavCardGroup>
+</div>
+```
+
+## Slots
+
+- **container** — outlined rounded box. `surface` fill, `radius.md` corners, hairline `outlineVariant` stroke painted as inset box-shadow (never `border:`).
+- **leading** *(optional)* — 16px icon (`currentColor`) or 32-rung [Thumbnail](../thumbnail/thumbnail.md). Block-centred on the row's vertical midline — same contract for icon and thumbnail. Omitted by default; label flushes to the inline padding edge.
+- **labelCol** — vertical column holding label and (optional) supportingText. `min-width: 0` so both lines truncate.
+- **label** — primary card text. 14px / Regular / `onSurface`. Single line; truncates.
+- **supportingText** *(optional)* — secondary line under label. 12px / Regular / `onSurfaceVariant`. Sits flush under the label with no extra top margin — line-height alone separates the two rows.
+- **trailingIcon** *(optional)* — on `variant="nav"`, an auto-rendered right-pointing chevron at 16px, `onSurfaceVariant`. On `variant="default"` no trailing renders. A `trailingIcon` prop overrides either case. Slot stays block-centred regardless of one-line / two-line body.
+
+## Anatomy
+
+| Slot           | Token bindings |
+|----------------|----------------|
+| container      | `surface` fill, `radius.md` corners, hairline `outlineVariant` inset box-shadow, `48px` min-height, `8px` block / `16px` inline padding |
+| leading        | 16 × 16 (`sys.icon.md`) glyph in `currentColor` or 32 × 32 [Thumbnail](../thumbnail/thumbnail.md). Block-centred on the row's vertical midline (same contract for icon and thumbnail). `sys.layout.inline.md` (8px) gap to label column |
+| labelCol       | Flex column, `min-width: 0`, no inter-line margin (line-height carries the rhythm) |
+| label          | `sys.typo.body.sm` (14 / Regular) / `onSurface` |
+| supportingText | `sys.typo.label.sm` (12 / Semibold) / `onSurfaceVariant`, no top margin |
+| trailingIcon   | 16 × 16, `onSurfaceVariant`, `sys.layout.inline.md` (8px) gap to label column. Auto-rendered chevron on `variant="nav"`; omitted on `variant="default"` unless `trailingIcon` is supplied. Always block-centred. |
+| group          | `NavCardGroup` flex column, `sys.layout.stack.xs` (8px) gap between cards |
+
+## Appearance
+
+| Appearance | Container fill                  | When to reach |
+|------------|---------------------------------|----------------|
+| `default`  | `transparent`                   | The canonical form. NavCard's identity is the outlined chrome (hairline + radius + label + chevron); host surface tone reads through. State overlays mix on the transparent base. |
+| `surface`  | `sys.color.surface` (opaque)    | NavCard on a transparent / non-`surface` host (coloured hero, tonal band, BottomSheet content). Outline, label, chevron, and state overlays unchanged. |
+
+## Sizes
+
+A single rung. Min-height 48 (touch-target floor); consumers cannot shrink or grow the card.
+
+## States
+
+| State      | Overlay                       | Additional |
+|------------|-------------------------------|------------|
+| `default`  | —                             | Outlined surface at rest. |
+| `hovered`  | label tone at `sys.state.hover`   | Overlay paints across the container. |
+| `pressed`  | label tone at `sys.state.pressed` | Overlay deepens; no other shift. |
+| `disabled` | overlay suppressed            | Container at `sys.state.disabled` opacity; `pointer-events: none`. |
+
+## Focus indicator
+
+Outward 3-layer ring painted on the container's outer edge via an `::after` overlay (rest stroke sits on `::before`). Trigger: `:focus-visible`. NavCard sits as its own bounded surface with margin to siblings, so an outward ring reads cleanly — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+## Behavior
+
+- **Whole card is the click target.** The trailing chevron is never a separate hit target.
+- **Element swap.** Renders `<button>` by default; `<a href>` when `href` is set.
+- **Truncation, not wrap.** Both label and supportingText truncate with ellipsis; the card never grows to fit long text.

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

@@ -0,0 +1,161 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "NavCard",
+  "family": "nav-card",
+  "description": "Outlined, rounded single-row card. Single label (optional supporting line) over a `surface`-toned box with a hairline `outlineVariant` inset-shadow stroke and `radius.md` corners. Two variants select the trailing affordance: `default` ships no trailing icon (bare labelled card — settings entry, scope tile, informational drill-target), `nav` auto-renders the right-pointing chevron for explicit drill-in semantics. Whole card is the click target — keyboard focus, hover overlay, and tap commit all sit on the card. Reach for it when one row needs to read as its own discrete affordance rather than as one entry in a [List](../list/list.md) drill-in stack (`text` rows with `nav: true`).",
+  "element": "button",
+  "props": {
+    "variant": {
+      "type": "enum",
+      "values": ["default", "nav"],
+      "default": "default",
+      "description": "Trailing affordance. `default` ships NO trailing icon — the card reads as a labelled tile (settings entry, scope card, informational drill-target). `nav` auto-renders the right-pointing chevron — the explicit drill-in form. A consumer-supplied `trailingIcon` prop still overrides on either variant (e.g. an external-link arrow, an expand-down chevron)."
+    },
+    "label": {
+      "type": "string",
+      "required": true,
+      "description": "Primary card text. Single line; truncates with ellipsis."
+    },
+    "supportingText": {
+      "type": "string",
+      "optional": true,
+      "description": "Secondary line under the label. Single line; truncates with ellipsis."
+    },
+    "leading": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional leading slot — a 16px icon glyph (renders in `currentColor`) or a 32-rung [Thumbnail](../thumbnail/thumbnail.md). Block-centred on the row's vertical midline — both icon and thumbnail share the same contract regardless of one-line / two-line body. When omitted the label sits flush at the inline padding edge."
+    },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Overrides the variant's trailing affordance. Pass a custom 16px glyph when the action isn't a navigation drill-in (inline expand-down arrow, external-link arrow). On `variant=\"default\"` no trailing renders unless `trailingIcon` is supplied; on `variant=\"nav\"` the auto-chevron is replaced."
+    },
+    "appearance": {
+      "type": "enum",
+      "values": ["default", "surface"],
+      "default": "default",
+      "description": "Container fill. `default` is transparent — the card's identity is the outlined chrome (hairline + radius + label + chevron) and the host surface tone reads through. `surface` paints `sys.color.surface` so the card reads as its own opaque tier; reach for it when the card sits on a transparent / non-`surface` host (between bare-surface sections, on a tonal band the card needs to break out of)."
+    },
+    "href": {
+      "type": "string",
+      "optional": true,
+      "description": "When provided, renders as `<a href>` instead of `<button>`. Mutually exclusive with `onClick` as the primary commit, though either may be combined for analytics."
+    },
+    "onClick": {
+      "type": "function",
+      "optional": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "forcedState": {
+      "type": "literal",
+      "values": ["hovered", "pressed", "focused"],
+      "optional": true,
+      "description": "Docs-only — pins the card to a single visual state via `data-force-state`. Not for production use."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Outlined rounded box. Transparent fill by default (host tone reads through) — `surface` fill via `appearance=\"surface\"`. `radius.md` corners, hairline `outlineVariant` stroke painted as inset box-shadow (never `border:`). Whole container is the interactive target.",
+      "intrinsic": true
+    },
+    "leading": {
+      "required": false,
+      "description": "Optional leading slot at 16 × 16 (icon) or 32 × 32 (Thumbnail). Icon glyphs render in `currentColor`. Block-centred on the row's vertical midline — both icon and thumbnail share the same contract regardless of one-line / two-line body.",
+      "accepts": ["icon", "thumbnail"]
+    },
+    "labelCol": {
+      "required": true,
+      "description": "Vertical column holding label and (optional) supportingText. `min-width: 0` so both lines truncate.",
+      "intrinsic": true
+    },
+    "label": {
+      "required": true,
+      "description": "Primary card text. 16px / Regular / `onSurface`. Single line; truncates with ellipsis.",
+      "accepts": ["text"]
+    },
+    "supportingText": {
+      "required": false,
+      "description": "Secondary line under the label. 14px / Regular / `onSurfaceVariant`, 2px below the label. Single line; truncates.",
+      "accepts": ["text"]
+    },
+    "trailingIcon": {
+      "required": false,
+      "description": "Trailing affordance. On `variant=\"nav\"` an auto-rendered right-pointing chevron at 16px, `onSurfaceVariant`. On `variant=\"default\"` no trailing renders. A `trailingIcon` prop overrides either case. Slot stays block-centred regardless of one-line / two-line body so the chevron reads as the row's commit affordance.",
+      "accepts": ["icon"]
+    }
+  },
+  "sizing": {
+    "radius": "sys.radius.md",
+    "minHeight": "ref.space.600",
+    "paddingBlock": "sys.layout.container.xs",
+    "paddingInline": "sys.layout.container.md",
+    "outlineWidth": "sys.borderWidth.hairline",
+    "outlineColor": "sys.color.outlineVariant",
+    "leadingGap": "sys.layout.inline.md",
+    "trailingGap": "sys.layout.inline.md",
+    "leadingIconSize": "sys.icon.md",
+    "labelTypo": "sys.typo.body.sm",
+    "labelColor": "sys.color.onSurface",
+    "supportingTypo": "sys.typo.label.sm",
+    "supportingColor": "sys.color.onSurfaceVariant",
+    "supportingOffset": "0",
+    "trailingIconSize": "sys.icon.md",
+    "trailingIconColor": "sys.color.onSurfaceVariant",
+    "groupGap": "sys.layout.stack.xs"
+  },
+  "appearances": {
+    "default": {
+      "background": "transparent",
+      "note": "No fill — the host surface tone reads through. The canonical NavCard: its identity is the outlined chrome (hairline + radius + label + chevron), not a fill. Hover / pressed paint as label-tone overlays mixed on the transparent base so the host tone keeps reading through underneath the state paint."
+    },
+    "surface": {
+      "background": "sys.color.surface",
+      "note": "Opaque `surface` fill. Reach for it when the card sits on a transparent / non-`surface` host (a `surfaceContainerLow` tonal band, a coloured hero, a BottomSheet's content slot) and should read as its own opaque tier rather than blending into the host. Outline, label, chevron, and state overlays are unchanged."
+    }
+  },
+  "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",
+      "pointerEvents": "none"
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual painted as a three-layer ring on the card's outer edge. Composes over whichever lifecycle state the card is in.",
+    "composition": "outward",
+    "compositionReason": "NavCard sits as its own bounded surface with margin to siblings; an outward ring reads cleanly without colliding with a neighbouring row's stroke.",
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "implementation": "outset box-shadow on the container's `::after` overlay; the rest stroke stays painted on `::before` so the two layers don't fight."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "clickTarget": "Whole card is clickable. The trailing chevron is never a separate hit target.",
+    "truncationNotWrap": "Both label and supportingText truncate; the card never grows to fit long text.",
+    "elementSwap": "Renders `<button>` by default; `<a href>` when `href` is set."
+  },
+  "forbidden": [
+    "border: painted as the rest stroke — must be inset box-shadow (no-layout strokes rule, DESIGN.md)",
+    "rest outline removed — the outlined chrome IS the defining shape of NavCard; without it the component is a List drill-in row in disguise",
+    "stacked vertically with raw <div> gaps — group via the NavCardGroup wrapper so the 8px gap stays consistent across compositions",
+    "tightly stacked into a hairline-divider rail — for that anatomy use a List drill-in stack (`text` rows with `nav: true`); NavCards in a NavCardGroup must each remain a discrete outlined card",
+    "text-decoration underline on label or any descendant on hover — the whole card is the hit target with its own hover overlay; an underline doubles the affordance",
+    "trailing chevron replaced with a non-navigational glyph when the action is not a drill-in — use button/icon or a different component instead",
+    "destructive commit fired on card tap — destructive commits open a Dialog / BottomSheet, never fire inline"
+  ]
+}

package/agents/components/nav-list/nav-list.family.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "nav-list",
+  "name": "NavList",
+  "description": "Vertical label-only nav list — labelled block where each row carries a label (and optional secondary line) plus a trailing chevron Icon Button, and routes via `href` / `onClick`. **Preset wrapper** over `<Header /> + <List variant=\"entry\">` rendered label-only (no thumbnail) with a default chevron Icon Button in the trailing slot — no new tokens, no new selection model. If you need any divergence (mixing label-only and thumbnail-bearing rows, swapping the trailing affordance, omitting the header), drop down to `<Header /> + <List variant=\"entry\" />` and compose freely. Reach for `<NavList />` on category indexes, settings menus, and 'pick a sub-page' surfaces where the preset matches verbatim.",
+  "useCases": [
+    "category index",
+    "settings menu",
+    "directory of route targets",
+    "drill-down navigation list"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "Owns its inline padding internally. Place as a direct child of the page-shell <main> (or any host that pays the gutter once). Do NOT wrap in a padding-inline div, className=\"px-*\", or style={{ padding }} — the page rail is paid once at the shell, never on the full-bleed child. Inside a bounded surface (Dialog / BottomSheet / SideSheet), apply the negative-margin opt-out — see AGENTS.md § Composition rules.",
+  "compositionModes": {
+    "standalone": {
+      "default": true,
+      "chrome": {
+        "background": "sys.color.surface",
+        "padding": "sys.layout.container.lg block / sys.layout.container.md inline"
+      },
+      "context": "Direct child of the page shell or any host that pays the page-rail gutter once."
+    },
+    "embedded": {
+      "trigger": "prop `embedded={true}` on <NavList /> OR direct child of `.chorus-carousel` / `.chorus-feed` (DOM-ancestry safety net).",
+      "chrome": {
+        "background": "transparent",
+        "padding": "0"
+      },
+      "context": "Composed inside another rail-responsible host. Row content takes over from the host's content-box edge."
+    }
+  },
+  "usage": {
+    "note": "Rows are a label-only `items` array (value/label + href or onClick) — no thumbnail key, and no List or row children; the trailing chevron is automatic.",
+    "example": "<NavList label=\"…\" items={[{ value, label, href }]} />"
+  },
+  "spec": "nav-list.md",
+  "subcomponents": [
+    {
+      "slug": "nav-list",
+      "spec": "nav-list.spec.json",
+      "md": "nav-list.md",
+      "default": true
+    }
+  ]
+}