@teamblind-chorus/ui 1.0.0

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

@@ -0,0 +1,201 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "List",
+  "family": "list",
+  "subcomponent": "accordion",
+  "description": "Expandable-row List sub-component. Each `Accordion.Item` renders a List-row trigger (label + auto-rendered 16px chevron that rotates `0°` → `180°` on expand) over a content body that paints below when open. Row geometry, typography, divider, state overlays, and inward focus ring all delegate to the [family-wide rules](./list.md); this sub adds the expand/collapse contract and the top group-divider that separates the open trigger from its child rows. The family stays **edge-to-edge** (`layoutInset: full-bleed`): rows pay their own `16px inline / 8px block` padding via `layout.container.*`. Expanded content is indented an additional 16px on the leading edge so the body reads as nested INSIDE the trigger's label column, and carries a 40px min-height to keep short bodies on a touch-target rhythm. The chevron is decorative — the entire trigger header is the click target.",
+  "element": "div",
+  "props": {
+    "type": {
+      "type": "enum",
+      "values": ["single", "multiple"],
+      "default": "single",
+      "description": "`single` allows one open item at a time; `multiple` allows any number. Affects how `value` and `defaultValue` are typed."
+    },
+    "value": {
+      "type": "union",
+      "members": ["string", "string[]"],
+      "optional": true,
+      "description": "Controlled open-state. `string` for `type='single'`, `string[]` for `type='multiple'`. Pair with `onValueChange`."
+    },
+    "defaultValue": {
+      "type": "union",
+      "members": ["string", "string[]"],
+      "optional": true,
+      "description": "Uncontrolled initial open-state. Ignored when `value` is also passed."
+    },
+    "onValueChange": {
+      "type": "function",
+      "optional": true,
+      "description": "Called with the next open-state (`string | null` for single, `string[]` for multiple) when the user toggles an item."
+    },
+    "collapsible": {
+      "type": "boolean",
+      "default": true,
+      "description": "Single-mode only. When `false`, an open item cannot be collapsed by clicking its own trigger — one item is always open. Ignored when `type='multiple'`."
+    },
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag inherited from the List family. When `true` (or when the Accordion is a direct child of `.chorus-carousel` / `.chorus-feed`), enters embedded mode — chrome defers to the host. See `compositionModes` in `list.family.json`."
+    },
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "One or more `Accordion.Item` children."
+    }
+  },
+  "itemProps": {
+    "value": {
+      "type": "string",
+      "required": true,
+      "description": "Unique identifier used to track the item's open-state in the Accordion."
+    },
+    "label": {
+      "type": "string",
+      "required": true,
+      "description": "Trigger header text. Single line; wraps to a second line when long, no truncation."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "strong": {
+      "type": "boolean",
+      "default": false,
+      "description": "Per-item trigger-label-emphasis opt-in (family-wide contract — see [list.md § Cross-sub contract](./list.md)). When `true`, the trigger'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 (e.g., the active section in a directory accordion)."
+    },
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "Content body rendered when the item is open."
+    },
+    "forcedState": {
+      "type": "literal",
+      "values": ["hovered", "pressed", "focused"],
+      "optional": true,
+      "description": "Docs-only — pins the trigger to a single visual state via `data-force-state`. Not for production use."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Outer stack. Transparent fill so the host surface tone reads through. `role='region'` carries the accordion's accessible name (`aria-label`).",
+      "intrinsic": true
+    },
+    "item": {
+      "required": true,
+      "description": "Single expandable row. Hairline `outlineVariant` divider inset 16px (`layout.container.md`) on BOTH the leading and trailing edges, painted as an absolutely-positioned `::after` overlay on every row except the last — matching the family-wide List row divider rule. `data-state='open' | 'closed'` reflects the current open-state.",
+      "intrinsic": true
+    },
+    "trigger": {
+      "required": true,
+      "description": "Header button. Holds the label and the auto-rendered trailing chevron. `role='button'`, `aria-expanded` reflects open-state, `aria-controls` references the content region. Same geometry as a List row (48px min-height, 8px block / 16px inline padding).",
+      "intrinsic": true
+    },
+    "label": {
+      "required": true,
+      "description": "Trigger label. `16px / Regular / onSurface` — matches the List family `label` spec. Wraps to a second line; no truncation.",
+      "accepts": ["text"]
+    },
+    "chevron": {
+      "required": true,
+      "description": "Auto-rendered 16px `ChevronDownIcon` at `onSurfaceVariant`. Rotates from `0°` to `180°` over 120ms `ease-out` on expand. Decorative.",
+      "intrinsic": true
+    },
+    "content": {
+      "required": true,
+      "description": "Body region. Paints below the trigger when open; uses `hidden` attribute when closed.\n\nTwo padding modes by content kind:\n\n- **Prose body** (text, icon, button, form-field): inline padding is `32px leading / 16px trailing` — one extra `layout.container.md` of indent on the leading edge so the prose reads as nested INSIDE the trigger's label column. `min-height: 40px` keeps short single-line bodies on a touch-target rhythm.\n- **Embedded row group** (`<List embedded>` or another `<Accordion embedded>`): inline padding is `16px leading / 0 trailing` — the leading indent is paid once by the body (sub-list rows align one container.md inside the trigger's label column) and the trailing rail is paid by the row's own inline padding, so the sub-list stretches flush to the accordion's right edge without a double-paid gutter. The body also paints a hairline `outlineVariant` divider at its TOP via a `::before` overlay (inset 16px on both inline edges, matching the inter-item divider rule) so the parent trigger and the child rows read as a parent ↔ child hierarchy.\n\nThe two modes are selected automatically via `:has([data-embedded='true'])` — call sites do not pass a mode prop; dropping a `<List embedded>` (or nested `<Accordion embedded>`) into the content body switches the body to compact-host geometry.",
+      "accepts": ["text", "icon", "button", "list", "form-field"]
+    },
+    "groupDivider": {
+      "required": false,
+      "description": "Hairline `outlineVariant` rule painted at the TOP edge of the open content body via a `::before` overlay when the body hosts a `<List embedded>` (or any same-kind row group). Inset 16px (`layout.container.md`) on both inline edges, matching the inter-item divider. Distinguishes the parent trigger from the child group so the hierarchy reads visually. Omitted for prose bodies.",
+      "intrinsic": true
+    }
+  },
+  "sizing": {
+    "triggerMinHeight": "ref.space.600",
+    "triggerPaddingBlock": "sys.layout.container.xs",
+    "triggerPaddingInline": "sys.layout.container.md",
+    "triggerLabelTypo": "sys.typo.body.md",
+    "triggerLabelColor": "sys.color.onSurface",
+    "chevronSize": "sys.icon.md",
+    "chevronColor": "sys.color.onSurfaceVariant",
+    "chevronGap": "sys.layout.inline.md",
+    "chevronRotationDuration": "120ms",
+    "chevronRotationTiming": "ease-out",
+    "contentPaddingBlock": "sys.layout.container.xs",
+    "contentProsePaddingInlineStart": "calc(sys.layout.container.md * 2)",
+    "contentProsePaddingInlineEnd": "sys.layout.container.md",
+    "contentEmbeddedPaddingInlineStart": "sys.layout.container.md",
+    "contentEmbeddedPaddingInlineEnd": "0",
+    "contentIndent": "sys.layout.container.md",
+    "contentMinHeight": "ref.space.500",
+    "contentBodyTypo": "sys.typo.body.sm",
+    "contentBodyColor": "sys.color.onSurfaceVariant",
+    "embeddedRowLabelTypo": "sys.typo.body.sm",
+    "embeddedRowMinHeight": "ref.space.500",
+    "embeddedRowDivider": "none",
+    "dividerWidth": "sys.borderWidth.hairline",
+    "dividerColor": "sys.color.outlineVariant",
+    "dividerInsetInline": "sys.layout.container.md",
+    "groupDividerWidth": "sys.borderWidth.hairline",
+    "groupDividerColor": "sys.color.outlineVariant",
+    "groupDividerInsetInline": "sys.layout.container.md"
+  },
+  "appearances": {
+    "default": {
+      "background": "transparent",
+      "note": "The only appearance — Accordion paints no fill of its own. The host surface tone reads through every row. Reach for a wrapping [Carousel](../carousel/carousel.md) when the accordion needs its own labelled region."
+    }
+  },
+  "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 an inward 3-layer ring inside the trigger's footprint. Composes over whichever lifecycle state the trigger is in.",
+    "composition": "inward",
+    "compositionReason": "Items tile flush with only a hairline `outlineVariant` divider between them; an outward ring would overlap the divider and the neighbouring row.",
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "implementation": "inset box-shadow on the trigger's `::before` overlay."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "clickTarget": "Whole trigger header is the click target. The chevron is decorative — never a separate hit target.",
+    "keyboardActivation": "Space and Enter both toggle the item when the trigger holds focus. Arrow up/down moves focus between triggers.",
+    "single": "In `type='single'` mode, opening an item closes the previously open one. With `collapsible={true}` (default), clicking the open item closes it too — leaving zero open items.",
+    "multiple": "In `type='multiple'` mode, each trigger toggles its own item independently. `value` is a string array.",
+    "wrapNotTruncate": "Trigger label wraps onto a second line when long; the row grows. Truncation would hide the affordance from being scannable.",
+    "chevronRotation": "120ms `ease-out` transform on the chevron's rotation. Under `prefers-reduced-motion: reduce` the rotation snaps instantly."
+  },
+  "forbidden": [
+    "item rendered as its own outlined rounded surface — Accordion tiles items flush with a hairline divider; outlined-card stacks are NavCardGroup, not an accordion",
+    "Accordion wrapped in a parent `padding-inline` / `px-*` / `style={{ paddingInline: … }}` container outside a documented bounded surface — the family is full-bleed and double-pays the page gutter when an outer rail is also applied",
+    "prose content body painted flush to the trigger's leading edge — text / icon / button / form-field bodies MUST sit at `32px` inline-start (trigger inline padding + a further `layout.container.md` indent) so the prose reads as nested inside the row. Embedded row-group bodies are a separate contract (16 leading / 0 trailing) — see `contentEmbeddedPaddingInline*`.",
+    "expanded content body collapsed below `40px` min-height — short single-line bodies still need to land on a touch-target rhythm so the row's open-state reads as distinct from its closed-state",
+    "divider painted full-bleed (no inline inset) — the rule must be inset 16px on BOTH edges; a full-bleed rule reads as separating the container, not the rows",
+    "chevron replaced with a plus / minus glyph — the family uses the rotating chevron contract; alt glyphs read as a different affordance (an add action, a remove action)",
+    "content body painted with a chromatic fill (primaryContainer, etc.) — the body inherits the host surface tone; chromatic emphasis on an accordion body reads as a Banner aside, not a content section",
+    "destructive commit fired inline inside the content body without a Button wrapper — destructive commits open a Dialog / BottomSheet, never fire from a raw content link",
+    "child `<List>` dropped into the content body WITHOUT `embedded={true}` — the list keeps its own surface chrome + inline padding and double-pays the body's 32px leading indent, leaving child rows at a deeper inset than the trigger's label column. Use `embedded` so the list inherits the body's edges.",
+    "child list group rendered WITHOUT the top `outlineVariant` divider — the parent trigger and the first child row tile flush, collapsing the parent ↔ child hierarchy into one stack. The top divider is the visual contract that the group is nested, not co-equal.",
+    "top group divider replaced with a `border-top:` on the list container — `border` reflows the box and breaks the inward focus ring on the first list row. Paint via the body's `::before` overlay (no-layout stroke), never a layout border.",
+    "trigger label sized below 16px or set to Semibold — Accordion is a List sub and inherits the family `label` spec (`16 / Regular / onSurface`); a 14/Semibold trigger reads as a different family from the rows it nests"
+  ]
+}

package/agents/components/list/entry.md

@@ -0,0 +1,280 @@
+# Entry
+
+Directory-entry [List](./list.md) sub — an entity row pairing an optional leading [Thumbnail](../thumbnail/thumbnail.md) avatar with an identity group (label, optional inline `count` Badge, optional `secondary` line and `description`). Same click semantics as the [Standard sub](./standard.md); geometry, state overlays, and inward focus ring delegate to the [family-wide rules](./list.md). Slots and Anatomy below carry the rung and slot detail.
+
+**Reach for this when** rendering an entity-row directory — follow suggestion, member directory, subscription / channel / topic / playlist directory, mention / recipient picker, entity search result — or, with `thumbnail` omitted, label-only nav rows (settings menu, category index). **Skip when** you need a Feed-specific attribution cluster (use [Metadata](../metadata/metadata.md) for Post / Ad card heads).
+
+**Layout inset.** full-bleed — sits as a direct child of the page shell. Each row pays its own `16px inline / 8px block` padding via `layout.container.md` / `layout.container.xs`; do **not** wrap the list in another `padding-inline` / `px-*` / `style={{ padding: … }}` div. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Directory entry rows — pick the Thumbnail rung via the **Size** dropdown (`xlarge` 56 → `small` 32). Row payload (label + stacked secondary + single-line description + trailing follow toggle) stays constant; only the leading avatar footprint changes. At `xlarge` the inter-row divider anchors to the text column (16 + 56 + 12 = 84) so the rule reads as separating identity columns under the wider avatar.
+
+```preview
+list/entry
+---
+import { Button, List } from '@teamblind-chorus/ui';
+
+<List
+  variant="entry"
+  size="medium"
+  items={[
+    {
+      value: 'sourdough-bakers',
+      label: 'Sourdough Bakers',
+      secondary: '12.4K Followers',
+      description: 'Open-crumb obsession, cold-proof timelines, weekend bakes.',
+      thumbnail: { src: '/placeholder.png', alt: 'Sourdough Bakers' },
+      trailingIcon: (
+        <Button variant="toggle" onClick={() => {}}>Follow</Button>
+      ),
+    },
+    {
+      value: 'indie-game-devs',
+      label: 'Indie Game Devs',
+      secondary: '8,210 Followers',
+      description: 'Solo dev diaries, first-release postmortems, jam recaps.',
+      thumbnail: { src: '/placeholder.png', alt: 'Indie Game Devs' },
+      trailingIcon: (
+        <Button variant="toggle" onClick={() => {}}>Follow</Button>
+      ),
+    },
+  ]}
+/>
+```
+
+## Use cases
+
+### With trailing Text Button (compact attribution row)
+
+Pairs a leading Thumbnail + label with a trailing [Text Button](../button/text.md) (`size="xsmall"`) and nothing else — the most compact *image + label + trailing-text-button* identity-plus-commit row. The button carries the **link-affordance follow / invite** shape: `appearance="accent"` while inactive (`Follow`) so the commit reads as the loudest call, flipping to `appearance="default"` once active (`Following`) so the followed state recedes. Distinct from the [Default](#default)'s `variant="toggle"` Follow chip — reach for the text button when the row reads as an attribution line (channel / author + follow) rather than a directory entry with a pill control. This is the exact combo the [Post carousel](../carousel/post.md) card pins to the top of each post as its attached attribution element.
+
+```preview
+list/entry-with-text-button
+---
+import { Button, List } from '@teamblind-chorus/ui';
+
+<List
+  variant="entry"
+  size="medium"
+  items={[
+    {
+      value: 'beauty-talk',
+      label: 'Beauty Talk',
+      thumbnail: { src: '/placeholder.png', alt: 'Beauty Talk' },
+      trailingIcon: (
+        <Button variant="text" size="xsmall" appearance="accent" onClick={() => {}}>Follow</Button>
+      ),
+    },
+    {
+      value: 'plant-people',
+      label: 'Plant People',
+      thumbnail: { src: '/placeholder.png', alt: 'Plant People' },
+      trailingIcon: (
+        <Button variant="text" size="xsmall" onClick={() => {}}>Following</Button>
+      ),
+    },
+  ]}
+/>
+```
+
+### With trailing star toggle
+
+Uses the **single-shape fill-only contract**: always `<StarFillIcon>`, color flips by state (active = `var(--sys-color-icon-yellow)`, inactive = `var(--sys-color-icon-muted)`). Shape stays constant so the trailing rail keeps a stable hit-target footprint — never swap between outline (`StarIcon`) and fill (`StarFillIcon`) for the same affordance. Rows with a trailing affordance default to `size="small"` (32) — the smaller leading footprint keeps the trailing rail visually balanced.
+
+```preview
+list/entry-with-star
+---
+import { Badge, Button, List } from '@teamblind-chorus/ui';
+import { StarFillIcon } from '@teamblind-chorus/ui/icons';
+
+<List
+  variant="entry"
+  size="small"
+  items={[
+    {
+      value: 'sourdough',
+      label: 'Sourdough Bakers',
+      count: <Badge count={12} />,
+      thumbnail: { src: '/placeholder.png', alt: 'Sourdough Bakers' },
+      trailingIcon: (
+        <Button
+          variant="icon"
+          size="medium"
+          aria-label="Favorited"
+          aria-pressed="true"
+          icon={<StarFillIcon />}
+          style={{ color: 'var(--sys-color-icon-yellow)' }}
+          onClick={() => {}}
+        />
+      ),
+    },
+    {
+      value: 'stocks',
+      label: 'Stocks & Investing',
+      count: <Badge count={142} />,
+      thumbnail: { src: '/placeholder.png', alt: 'Stocks & Investing' },
+    },
+    {
+      value: 'movie-talk',
+      label: 'Movie Talk',
+      count: <Badge count={24} />,
+      thumbnail: { src: '/placeholder.png', alt: 'Movie Talk' },
+      trailingIcon: (
+        <Button
+          variant="icon"
+          size="medium"
+          aria-label="Favorite"
+          aria-pressed="false"
+          icon={<StarFillIcon />}
+          style={{ color: 'var(--sys-color-icon-muted)' }}
+          onClick={() => {}}
+        />
+      ),
+    },
+  ]}
+/>
+```
+
+### As nav option (trailing chevron Icon Button)
+
+The trailing slot carries a default [Icon Button](../button/icon.md) (`variant="icon"`, `size="medium"`) filled with a right-pointing chevron — the canonical nav-option drill-in affordance. Reach for it when the row routes to a sub-page and you still want to expose an identity-bearing thumbnail (workspace switch, channel directory drill-in). For pure label-only nav stacks, omit `thumbnail` instead — see [the label-only case below](#label-only-no-thumbnail).
+
+```preview
+list/entry-as-nav-option
+---
+import { Button, List } from '@teamblind-chorus/ui';
+import { ChevronRightIcon } from '@teamblind-chorus/ui/icons';
+
+<List
+  variant="entry"
+  size="medium"
+  items={[
+    {
+      value: 'sourdough',
+      label: 'Sourdough Bakers',
+      secondary: '12.4K Followers',
+      thumbnail: { src: '/placeholder.png', alt: 'Sourdough Bakers' },
+      trailingIcon: (
+        <Button
+          variant="icon"
+          size="medium"
+          aria-label="Open Sourdough Bakers"
+          icon={<ChevronRightIcon />}
+          onClick={() => {}}
+        />
+      ),
+    },
+    {
+      value: 'indie-game-devs',
+      label: 'Indie Game Devs',
+      secondary: '8,210 Followers',
+      thumbnail: { src: '/placeholder.png', alt: 'Indie Game Devs' },
+      trailingIcon: (
+        <Button
+          variant="icon"
+          size="medium"
+          aria-label="Open Indie Game Devs"
+          icon={<ChevronRightIcon />}
+          onClick={() => {}}
+        />
+      ),
+    },
+  ]}
+/>
+```
+
+### Label only (no thumbnail)
+
+Omit `thumbnail` on a row to collapse the leading column — the label sits flush at the 16 inline rail and the row reads as a label-only entry. Reach for it on settings menus, category indexes, and *pick a sub-page* stacks. Pair with a trailing chevron Icon Button to assemble the canonical nav-option row; this is the shape [NavList](../nav-list/nav-list.md) bundles under its header.
+
+```preview
+list/entry-label-only
+---
+import { Button, List } from '@teamblind-chorus/ui';
+import { ChevronRightIcon } from '@teamblind-chorus/ui/icons';
+
+<List
+  variant="entry"
+  items={[
+    {
+      value: 'location',
+      label: 'Location',
+      trailingIcon: (
+        <Button variant="icon" size="medium" aria-label="Open Location" icon={<ChevronRightIcon />} onClick={() => {}} />
+      ),
+    },
+    {
+      value: 'job',
+      label: 'Job Function',
+      trailingIcon: (
+        <Button variant="icon" size="medium" aria-label="Open Job Function" icon={<ChevronRightIcon />} onClick={() => {}} />
+      ),
+    },
+    {
+      value: 'learning',
+      label: 'Learning & Advising',
+      trailingIcon: (
+        <Button variant="icon" size="medium" aria-label="Open Learning & Advising" icon={<ChevronRightIcon />} onClick={() => {}} />
+      ),
+    },
+    {
+      value: 'money',
+      label: 'Money',
+      trailingIcon: (
+        <Button variant="icon" size="medium" aria-label="Open Money" icon={<ChevronRightIcon />} onClick={() => {}} />
+      ),
+    },
+  ]}
+/>
+```
+
+## Slots
+
+- **container** — outer vertical stack (delegates to family).
+- **row** — single list item; whole row is the click target.
+- **leading** *(optional)* — [Thumbnail](../thumbnail/thumbnail.md) at the list's `size` rung (32 / 40 / 48 / 56). `thumbnail` props forward verbatim. Omit per row to collapse the leading column entirely — the leading→text gap (12) also drops, and the label sits flush at the 16 inline rail. Mix-and-match per row is supported.
+- **label** — primary row text. `sys.typo.label.md` (14 / Semibold) / `sys.color.onSurface`. Pairs flush with `count` on the primary line.
+- **count** *(optional)* — inline node painted to the right of the label on the same line (canonical: `<Badge count={n} />`). Separated by `sys.layout.inline.sm` (4); label shrinks first so a long name truncates against the count.
+- **secondary** *(optional)* — stacked meta line below the label inside the identity group (follower count, location). `sys.typo.label.sm` (12 / Semibold) / `sys.color.onSurface`. Tiles flush with the label — line-height-only spacing, no margin — so the two lines read as one tight identity block.
+- **description** *(optional)* — single-line caption-tone supporting line below the identity group. `sys.typo.label.sm` (12 / Semibold) / `sys.color.onSurfaceVariant`. Separated from the identity group by `ref.space.25` (2). Truncates with ellipsis; never wraps.
+- **trailingIcon** *(optional, per-row)* — consumer-supplied node at the trailing edge. Canonical fills: `<Button variant="toggle">` (Follow chip), `<Button variant="text" size="xsmall" appearance="accent">` (Follow / Invite link-affordance — the [attribution-row case](#with-trailing-text-button-compact-attribution-row)), `<Button variant="icon">` (favorite / overflow), `<Badge>`. Its own hit target — clicks stop propagating before reaching the row.
+- **divider** *(optional, per-row)* — pass `divider: false` to suppress the row's bottom hairline. Use when a visual group ends mid-stack and the divider would visually fence off the next group from its label.
+
+## Anatomy
+
+| Slot                       | Token bindings |
+|----------------------------|----------------|
+| row container              | Block / inline padding (`layout.container.md` inline rail across every rung). Block: `8px` (`layout.container.xs`) at `small` / `medium` / `large`, `12px` (`layout.container.sm`) at `xlarge` — the 56 rung's identity stack reads denser. `min-height: 48` (`ref.space.600`). |
+| leading thumbnail *(optional)* | 32 (`size="small"`) / 40 (`size="medium"`) / 48 (`size="large"`) / 56 (`size="xlarge"`). Omit per row to collapse the leading column. |
+| leading → text column      | `sys.layout.inline.lg` (12) when leading is present — Entry-specific override of the family-wide `inline.md` (8) row gap. Drops to `0` when `thumbnail` is omitted. |
+| label                      | `sys.typo.label.md` (14 / Semibold) / `onSurface`, single-line ellipsis |
+| label → count              | `sys.layout.inline.sm` (4) |
+| count                      | inline node — canonical `<Badge>` |
+| label → secondary          | `0` — line-height only |
+| secondary                  | `sys.typo.label.sm` (12 / Semibold) / `onSurface`, single-line ellipsis |
+| identity group → description | `ref.space.25` (2) |
+| description                | `sys.typo.label.sm` (12 / Semibold) / `onSurfaceVariant`, single-line ellipsis |
+| text column → trailing     | `sys.layout.inline.sm` (4) |
+| trailingIcon               | `<Button variant="icon">`, `<Button variant="toggle">`, `<Button variant="text" appearance="accent">`, or `<Badge>` |
+| inter-row divider          | `1px` `outlineVariant`. Default (`small` / `medium` / `large`): `16` inset from both edges. `xlarge`: leading inset anchors to the text column (`16 + 56 + 12 = 84`) so the rule reads as separating identity columns; trailing inset stays at `16`. **Label-only rows** (no thumbnail): leading inset falls back to the default `16` regardless of `size`. |
+
+## States
+
+No `selected` state. State overlays (hover / pressed / disabled) delegate to the [family-wide rules](./list.md#cross-sub-contract).
+
+## Focus indicator
+
+Inward 3-layer ring inside the row's bounds — see the family-wide [Focus indicator](./list.md#cross-sub-contract). The whole row is the keyboard target; a trailing toggle / icon button carries its own focus ring per its component spec.
+
+## Behavior
+
+- **Thumbnail is optional, per row.** Drop `thumbnail` from a row to collapse the leading column and the `leading → text` (12) gap; the label sits flush at the 16 inline rail. For pure label-only nav stacks, [NavList](../nav-list/nav-list.md) bundles this shape under a header.
+- **Identity group is tight.** Label + (inline count) on the primary line, optional `secondary` stacked flush below — line-height-only spacing — so the entire identity group reads as one block.
+- **Divider inset switches at `xlarge`.** Default rungs: hairline inset `16` from both edges so the rule reads as separating *content*. At `xlarge` the leading inset anchors to the text column (`16 + 56 + 12 = 84`) — the 56 avatar is large enough that a row-edge divider reads as a hard line under the avatar.
+- **Block padding bumps at `xlarge`.** Default rungs use `container.xs` (8); `xlarge` bumps to `container.sm` (12) — the 56 rung's identity stack needs an extra step of breathing room.
+- **Description is the supporting layer.** Sits below the identity group with `ref.space.25` (2) of separation. Always single-line; truncates. The row never grows to fit longer copy.
+- **Truncates, never wraps.** Label and description both truncate; trailing slot is never pushed off-row by long text.
+- **Trailing slot is its own hit target.** Clicks inside `trailingIcon` stop propagating before reaching the row — wire favorite / follow / overflow there without committing the row's primary action.
+- **Keyboard navigation.** Arrow ↑ / ↓ moves focus between rows; Home / End jump to first / last.
+- **Row content is the shared `EntryRow` atom.** Each row's inner cluster — leading Thumbnail + identity column (label + optional inline `count` + optional `secondary`) + optional `description` + trailing slot — is rendered by the shared `EntryRow` component (class `chorus-entry-row`). The List row wrapper owns only the row geometry (16 / 8 padding, 48 min-height, divider, hover / focus / keyboard). The [Post carousel](../carousel/post.md) card header renders the **same** `EntryRow` (passing `verified` for the inline trust mark), so the directory-entry *image + label + trailing action* combo has a single definition.