@teamblind-chorus/ui 1.0.0

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

@@ -0,0 +1,237 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "List",
+  "family": "list",
+  "subcomponent": "entry",
+  "description": "Directory-entry List variant — edge-to-edge rows that pair an *optional* leading [Thumbnail](../thumbnail/thumbnail.md) (selectable rung 32 / 40 / 48 / 56 via `size=\"small|medium|large|xlarge\"`) with an identity group (label + optional inline `count` Badge + optional stacked `secondary` line — e.g. follower count — that tile flush with line-height-only spacing) and an optional single-line `description` separated from the identity group by `ref.space.25` (2). Optional trailing affordance per row. Same click semantics as the text variant — no selection model. Replaces the legacy `row/entity` atom — every entity-row case (follow suggestion, member directory, subscription / channel / topic / playlist directory) now ships as a full-bleed list at this variant. The optional leading slot also lets the same sub host **label-only** nav rows (settings menu, category index) — drop `thumbnail` from the row descriptor to collapse the leading column and tile the label flush at the 16 inline rail.",
+  "element": "ul",
+  "props": {
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when the List is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `list.family.json`."
+    },
+    "size": {
+      "type": "literal",
+      "values": [
+        "small",
+        "medium",
+        "large",
+        "xlarge"
+      ],
+      "default": "medium",
+      "description": "Thumbnail rung shared by every row in the list — `small` = 32, `medium` = 40, `large` = 48, `xlarge` = 56. The row's inline padding (16), block padding (8), and the family-wide row min-height (48) stay constant across sizes; only the leading Thumbnail footprint changes. Pick `small` for compact directories where the avatar reads as a mark, `medium` for the canonical channel / source directory, `large` for member-directory rows where the avatar carries identity weight, `xlarge` for the canonical follow-suggestion rung used by [SuggestionList](../suggestion-list/suggestion-list.md)."
+    },
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of row descriptors. Each item passes `thumbnail` props forwarded verbatim to the Thumbnail component."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Outer scroll surface. Vertical stack with a transparent fill (inherits parent container tone); rows separated by a 1px outlineVariant divider, not a gap."
+    },
+    "row": {
+      "required": true,
+      "description": "Single list item. Whole row is the interactive target."
+    },
+    "leading": {
+      "required": false,
+      "omittedBehavior": "collapsed",
+      "fallbackOnMissingSrc": "sys.color.surfaceContainerHigh",
+      "description": "Optional Thumbnail at the leading edge at the list's `size` rung (32 / 40 / 48 / 56), vertically centred against the text column. Forwarded verbatim from item.thumbnail. When `thumbnail` is omitted on a row descriptor the leading column collapses, the `leading → text` (12) gap drops to 0, and the label sits flush at the 16 inline rail — reach for it on label-only nav rows (settings menu, category index) and mix-and-match identity rows. `fallbackOnMissingSrc` is the dim-tone fill the Thumbnail paints when `src` is present but empty / fails to load — at scaffold time, agents fill `src` with `/placeholder.png` rather than relying on the fallback. To intentionally render a label-only row, omit `thumbnail` entirely rather than passing an empty `src`.",
+      "accepts": [
+        "thumbnail"
+      ]
+    },
+    "label": {
+      "required": true,
+      "description": "Primary row text. `sys.typo.label.md` (14 / Semibold) / `sys.color.onSurface`. Single line; truncates with ellipsis. Pairs flush with the inline `count` slot — no gap between them, only `sys.layout.inline.sm` (4) horizontal separation on the primary row.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "count": {
+      "required": false,
+      "description": "Optional inline node painted to the right of the label on the same line (e.g. follower count, member count). Canonical fill is a numeric [Badge](../badge/badge.md). Separated from the label by `sys.layout.inline.sm` (4). Label shrinks first so a long name truncates against the count.",
+      "accepts": [
+        "badge",
+        "text"
+      ]
+    },
+    "secondary": {
+      "required": false,
+      "description": "Optional stacked meta line painted below the label inside the identity group (e.g. `'12.4K Followers'`, `'Brooklyn, NY · Home baker'`). `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.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "description": {
+      "required": false,
+      "description": "Optional secondary line under the identity group. `sys.typo.label.sm` (12 / Semibold) / `sys.color.onSurfaceVariant`. Single line; truncates with ellipsis. Separated from the identity group by `ref.space.25` (2) so the description reads as a tight supporting layer below the name rather than as a co-equal line.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "trailingIcon": {
+      "required": false,
+      "description": "Node at the trailing edge. Consumer-supplied. Accepts a decorative icon, a toggle button (favorite / mute / pin), a numeric badge, or a small text button (Follow / Invite). Taps on the trailing slot stop propagating before they reach the row's `onClick` — the slot is a separate hit target so the consumer can wire its own action without committing the row.",
+      "accepts": [
+        "icon",
+        "badge",
+        "button"
+      ]
+    }
+  },
+  "rowProps": {
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "label": {
+      "type": "string",
+      "required": true
+    },
+    "count": {
+      "type": "node",
+      "optional": true,
+      "description": "Inline count node painted flush with the label. Canonical fill: `<Badge count={n} />`."
+    },
+    "secondary": {
+      "type": "string",
+      "optional": true,
+      "description": "Stacked meta line painted below the label inside the identity group (e.g. follower count text, location). Caption-tone but `onSurface` color — reads as part of the identity block, not as a recessive description."
+    },
+    "description": {
+      "type": "string",
+      "optional": true,
+      "description": "Single-line caption-tone description under the identity group. Truncates with ellipsis; never wraps to a second line."
+    },
+    "thumbnail": {
+      "type": "object",
+      "optional": true,
+      "description": "Optional. Forwarded to Thumbnail verbatim (`src`, `alt`, optional `shape`, optional `updateDot`, optional `logoBadge`). Omit to render a label-only row — the leading column collapses, the `leading → text` (12) gap drops to 0, and the label sits flush at the 16 inline rail."
+    },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Trailing-edge node. Wrapped in a slot that stops click propagation so the slot is its own hit target separate from the row's `onClick`."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "divider": {
+      "type": "boolean",
+      "default": true,
+      "description": "Per-row bottom-divider opt-out. Pass `divider: false` to suppress the hairline `outlineVariant` rule beneath the row; the row's footprint and inline padding stay unchanged. Reach for it when a visual group ends mid-stack and the divider would visually fence off the next group from its label."
+    },
+    "strong": {
+      "type": "boolean",
+      "default": false,
+      "description": "Per-row label-emphasis opt-in (family-wide contract — see [list.md § Cross-sub contract](./list.md)). Already Semibold at rest in this variant; `strong` is the no-op marker reserved for parity with other subs and to support future weight shifts without breaking the prop surface."
+    },
+    "onClick": {
+      "type": "function",
+      "optional": true
+    },
+    "forcedState": {
+      "type": "literal",
+      "values": [
+        "hovered",
+        "pressed",
+        "focused"
+      ],
+      "optional": true,
+      "description": "Docs-only — pins the row to a single visual state via `data-force-state`. Not for production use."
+    }
+  },
+  "sizing": {
+    "rowPaddingBlock": "ref.space.100 (8) at small / medium / large; ref.space.150 (12) at xlarge — the 56 rung's identity stack reads denser so block padding bumps a step.",
+    "rowPaddingInline": "ref.space.200",
+    "rowMinHeight": "ref.space.600",
+    "leadingTextGap": "sys.layout.inline.lg (12) when the leading Thumbnail is present (the image-leading rung of the family's role-based spacing); 0 when `thumbnail` is omitted (the column collapses and the label sits flush at the 16 inline rail).",
+    "trailingActionGap": "sys.layout.inline.md",
+    "trailingActionGapNote": "Fixed 8px between the text group and a trailing action — the family-wide trailing gap.",
+    "dividerWidth": "sys.borderWidth.hairline",
+    "dividerColor": "sys.color.outlineVariant",
+    "dividerPerRowOptOut": "Pass `divider: false` on a row to suppress its bottom divider.",
+    "labelTypo": "sys.typo.label.md",
+    "labelColor": "sys.color.onSurface",
+    "labelToCountGap": "sys.layout.inline.sm",
+    "secondaryTypo": "sys.typo.label.sm",
+    "secondaryColor": "sys.color.onSurface",
+    "secondaryToLabelGap": "0",
+    "identityToDescriptionGap": "ref.space.25",
+    "descriptionTypo": "sys.typo.label.sm",
+    "descriptionColor": "sys.color.onSurfaceVariant",
+    "descriptionMaxLines": 1,
+    "leadingThumbnailSize": {
+      "small": 32,
+      "medium": 40,
+      "large": 48,
+      "xlarge": 56
+    },
+    "dividerInset": "left 16 + right 16 from the row's edges (overrides the family-wide `right: 0` rule). At `size=\"xlarge\"`, the divider's left edge anchors to the text column instead (16 + 56 + 12 = 84 from the row's leading edge) so the rule reads as separating the text columns of two suggestion rows. Label-only rows (no thumbnail) always fall back to the default 16 inset regardless of `size` — there is no avatar column to anchor against.",
+    "trailingIconSize": "16 × 16",
+    "trailingIconColor": "sys.color.onSurfaceVariant"
+  },
+  "states": {
+    "default": {
+      "overlay": null
+    },
+    "hovered": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.hover"
+      }
+    },
+    "pressed": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "disabled": {
+      "containerOpacity": "sys.state.disabled",
+      "containerOpacityScope": "Dims the row content only — the inter-row divider and the focus overlay keep full opacity, so a disabled row never fades the hairline rule between it and the next row.",
+      "pointerEvents": "none"
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the row is in.",
+    "composition": "inward",
+    "compositionReason": "Rows tile the column flush with only a hairline `outlineVariant` divider between them; an outward ring would overlap the divider and the neighbouring row.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the row edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the row edge (the counter-ring just inside the outer stroke)",
+      "implementation": "inset box-shadow on the row's `::before` overlay (the `::after` carries the inter-row divider). Constrained strictly inside the row's footprint and never exceeds it."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "keyboardNavigation": "Arrow up/down moves focus between rows. Home and End jump to first / last.",
+    "rowClickTarget": "Whole row is clickable when an `onClick` is bound to the item. The thumbnail is never a separate hit target.",
+    "identityGroupFlush": "Label and inline count tile flush on the primary line with `sys.layout.inline.sm` (4) horizontal separation and no vertical gap — they read as one tight identity block.",
+    "descriptionSingleLine": "Description always renders on a single line and truncates with ellipsis. The row never grows to fit longer description copy — overflow truncates against the trailing slot if present.",
+    "trailingSlotIndependent": "Clicks inside `trailingIcon` stop propagating before they reach the row's `onClick`. Wire a favorite / follow / overflow action there without it committing the row's primary action."
+  },
+  "forbidden": [
+    "thumbnail rendered as a raw <img> outside the chorus-thumbnail slot wrapper",
+    "thumbnail size different from the list's `size` rung (32 / 40 / 48 / 56) — the thumbnail is optional, but when present it MUST match the rung",
+    "passing `thumbnail: { src: '' }` to fake a label-only row — omit the `thumbnail` key entirely instead so the leading column actually collapses",
+    "description rendered as a multi-line block — the spec is single-line, truncated",
+    "extra gap between label and count — they tile flush on the primary line",
+    "wrapping the list in another `padding-inline` / `px-*` div — the list owns its 16px inline rail at the row level"
+  ]
+}

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

@@ -0,0 +1,75 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "list",
+  "name": "List",
+  "description": "Vertical list of rows. Four sub-components share one anatomy and diverge on the leading slot, the selection contract, and the expand contract: `standard` (default — display / navigation rows; a row opts into a leading 40px [Thumbnail](../thumbnail/thumbnail.md) image (the image type) by passing `thumbnail`, or a leading 24px icon (the icon type) by passing `icon`, with optional `supportingText` second line + optional inline `count` badge + optional trailing affordance per row), `radio` (single-select picker with leading 16px radio indicator), `entry` (directory-entry rows with selectable 32 / 40 / 48 / 56 leading Thumbnail via `size=\"small|medium|large|xlarge\"`, identity group of label + optional inline `count` Badge + optional stacked `secondary` line, and an optional single-line `description` below — the canonical home for every entity-row case: follow suggestion, member directory, subscription / channel / topic / playlist directory), `accordion` (expandable rows with auto-rendered trailing chevron that rotates on expand, hosting a content body and optional nested `<List embedded>` group below the trigger). Drill-in rows are not a separate sub-component: any `standard` / `radio` row opts into a trailing drill-in chevron with `nav: true` (on a `radio` row it marks a major category that opens a second screen).",
+  "useCases": [
+    "settings rows",
+    "menu rows",
+    "picker rows",
+    "single-select option group",
+    "drill-in navigation",
+    "avatar-anchored rows",
+    "directory rows",
+    "subscription / channel / topic directory entries",
+    "follow-suggestion stacks (full-bleed)",
+    "expandable rows",
+    "FAQ / policy sections",
+    "expandable filter groups",
+    "hierarchical menus (parent → child rows)"
+  ],
+  "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 }} \u2014 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 \u2014 see AGENTS.md \u00a7 Composition rules.",
+  "compositionModes": {
+    "standalone": {
+      "default": true,
+      "chrome": {
+        "background": "sys.color.surface",
+        "padding": "row-level inline + block via list-row anatomy"
+      },
+      "context": "Direct child of the page shell or any host that pays the page-rail gutter once."
+    },
+    "embedded": {
+      "trigger": "prop `embedded={true}` on <List /> OR direct child of `.chorus-carousel` / `.chorus-feed` (DOM-ancestry safety net).",
+      "chrome": {
+        "background": "transparent",
+        "padding": "0"
+      },
+      "context": "Composed inside another rail-responsible host. Rows take over from the host's content-box edge; leading thumbnails / radios align with the host header's left rail."
+    }
+  },
+  "usage": {
+    "note": "Rows are an `items` descriptor *array* on `<List>` — there is NO `<ListItem>` export. A styled `<button>` row or a hand-rolled flex row is a reinvention of `list / entry`. `accordion` is the one sub that takes `<Accordion>` children.",
+    "subs": {
+      "standard": { "variant": "standard", "example": "<List variant=\"standard\" items={[{ label, leadingIcon, trailing, onClick }]} />" },
+      "entry": { "variant": "entry", "example": "<List variant=\"entry\" items={[{ thumbnail, label, secondary, description, trailing, onClick }]} />" },
+      "radio": { "variant": "radio", "example": "<List variant=\"radio\" value={v} onChange={setV} items={[{ label, value }]} />" },
+      "accordion": { "import": "Accordion", "example": "<Accordion><Accordion.Item title=\"…\">…</Accordion.Item></Accordion>" }
+    }
+  },
+  "spec": "list.md",
+  "subcomponents": [
+    {
+      "slug": "standard",
+      "spec": "standard.spec.json",
+      "md": "standard.md",
+      "default": true
+    },
+    {
+      "slug": "radio",
+      "spec": "radio.spec.json",
+      "md": "radio.md"
+    },
+    {
+      "slug": "entry",
+      "spec": "entry.spec.json",
+      "md": "entry.md"
+    },
+    {
+      "slug": "accordion",
+      "spec": "accordion.spec.json",
+      "md": "accordion.md"
+    }
+  ]
+}

package/agents/components/list/list.md

@@ -0,0 +1,24 @@
+# List
+
+A vertically-stacked sequence of rows for menus, settings panels, picker sheets, inline option groups, directory entries, and expandable hierarchies. Four sub-components share one anatomy and diverge on the leading slot, the selection contract, and the expand contract.
+
+**Reach for this when** the rows are same-kind chrome — settings entries, menu options, single-select picker rows, drill-in navigation, directory rows, expandable section headers. **Skip when** the rows are authored content with author + body + footer (use [Feed](../feed/feed.md)) or a horizontal collection of curated cards (use [Carousel](../carousel/carousel.md)). Pick the sub by the trailing affordance and the leading slot: display / navigation rows → [Standard](./standard.md) (no `thumbnail` for text-only; pass `thumbnail` for the 40px avatar-leading image type, label + optional `supportingText`); single-select radio → [Radio](./radio.md); 32 / 40 / 48 avatar leading with identity-group (label + inline `count`) + optional single-line description → [Entry](./entry.md); drill-in chevron → any [Standard](./standard.md) / [Radio](./radio.md) row with `nav: true`; expand chevron that rotates on click → [Accordion](./accordion.md).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell. Each row pays its own `8px block / 16px inline` padding via `layout.container.xs` / `layout.container.md`; do **not** wrap the List in another `padding-inline` / `px-*` / `style={{ padding: … }}` div, or the row leading edge (radio glyph, thumbnail, label start) lands at a different inset than surrounding chrome. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Cross-sub contract
+
+- **Container.** Vertical stack, transparent fill (inherits the parent surface). Rows separated by a 1px `outlineVariant` divider inset 16px (`layout.container.md`) from **both** the leading and trailing edges so the rule reads as separating *content*, not the container. The Entry sub overrides the leading inset at `size="xlarge"` only — see [entry.md](./entry.md). No outer radius — corner shape belongs to the wrapping container.
+- **Row geometry.** 8px block / 16px inline padding (`layout.container.xs` / `layout.container.md`); min-height 48px. Row spacing is **role-based**, not a single flex gap: the **text group → trailing action** gap is a fixed `layout.inline.md` (8px) in every sub, while the **leading → text group** gap depends on the leading *type* — `layout.inline.md` (8px) for an icon leading (Radio's indicator), `layout.inline.lg` (12px) for an image leading (a Standard row's `thumbnail` image type / Entry Thumbnail). A label-only Entry row (no `thumbnail`) drops the leading gap to 0. Row grows when `supportingText` is present.
+- **Label column.** Label: 16px / Regular / `onSurface` (sub-list rows compressed inside an accordion render at 14px / Regular — see [accordion.md](./accordion.md) § Nested list; Entry rows promote the label to 14px / Semibold so the inline `count` reads as part of the identity group). SupportingText: 14px / Regular / `onSurfaceVariant`, sits directly under the label with no extra gap — the two lines stack on the label-column's intrinsic line-box rhythm. The Entry sub replaces the second line with a single-line `description` (12px / Regular / `onSurfaceVariant`, separated from the identity group by `ref.space.25` (2) — see [entry.md](./entry.md)). All secondary lines truncate with ellipsis.
+- **Strong-label opt-in.** Pass `strong={true}` on a row (`<Accordion.Item strong>` on the accordion sub) to promote the label's weight from Regular (`body.*-weight`, 400) to Semibold (`label.*-weight`, 600) at the same size and line-height — `body.md → label.lg` at the 16 rung, `body.sm → label.md` at the 14 rung. The row's geometry (height, dividers, slot positions) is unchanged; only the label glyphs gain stroke weight. Reach for it when one row needs to read as the primary entry within a denser scan — the active company in a directory, the canonical answer in an FAQ, the user's own row in a member list. Use sparingly — a stack where every row is strong reads as the default again, defeating the marker.
+- **States.** `selected` exists only on Radio. The whole row is the interactive surface.
+- **Focus indicator.** Composition: Inward (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)) — inset shadows entirely inside the row's box. Trigger: `:focus-visible`.
+- **Accessibility.** Every non-Radio sub (Standard / Entry / Accordion) exposes `role="list"`; Radio exposes `role="radiogroup"` with each row `role="radio"` + `aria-checked`. A `nav: true` row's trailing chevron is decorative (`aria-hidden`) — the whole row stays the single interactive target. Keyboard navigation (Arrow ↑/↓, Home/End) is handled by the container; Radio also commits on Space / Enter.
+
+## Sub-components
+
+- **[Standard](./standard.md)** — Display / navigation rows; the default sub for menu lists that route or fire without a selection model. Text-only by default (no leading slot, whole row is the click target); a row opts into a 40px leading [Thumbnail](../thumbnail/thumbnail.md) — the image type — by passing `thumbnail` (the former Image sub, now a per-row case), or a 24px (`sys.icon.lg`) leading glyph — the icon type — by passing `icon` (8px from the text group, mutually exclusive with `thumbnail`). A row opts into an inline `count` Badge to the right of the label (the unread / status-count case); for the avatar-anchored identity group with an inline count, reach for [Entry](./entry.md) instead. Set `nav: true` on a row for the drill-in chevron (the former Nav sub, now a per-row case).
+- **[Radio](./radio.md)** — Single-select picker with a leading 16px radio indicator; clicking a row commits its value via `onChange(value)`.
+- **[Entry](./entry.md)** — Directory-entry rows with a selectable 32 / 40 / 48 / 56 leading [Thumbnail](../thumbnail/thumbnail.md) (`size="small|medium|large|xlarge"`). Identity group of label + optional inline `count` Badge + optional stacked `secondary` line, plus an optional single-line `description` separated by `ref.space.25` (2). Same click semantics as Standard. The single home for every entity-row case (follow suggestion, member directory, subscription / channel / topic / playlist directory).
+- **[Accordion](./accordion.md)** — Expandable rows. Trailing edge auto-renders a `ChevronDownIcon` that rotates `0° → 180°` on expand; the open trigger hosts a content body (prose or another `<List embedded>`) indented one extra `layout.container.md` so the body reads as nested inside the trigger's label column. When the body holds a `<List embedded>`, a hairline `outlineVariant` divider paints at the top of the body so parent ↔ child hierarchy reads.

package/agents/components/list/radio.md

@@ -0,0 +1,144 @@
+# Radio
+
+Single-select picker List sub-component. Each row carries a leading 24px (`sys.icon.lg`) radio indicator; clicking commits that row's value via `onChange(value)`. Exactly one row is selected at a time. Row geometry, typography, divider, state overlays, and inward focus ring all delegate to the [family-wide rules](./list.md); this sub documents the Radio-specific leading indicator and selection contract.
+
+**Reach for this when** the user picks exactly one value from a short, fully-visible set — sort order, range filter, equity tier. **Skip when** multiple values may be selected (use [`Chip variant="filter"`](../chip/filter.md) or [`Button variant="check"`](../button/check.md)), the set is long enough to demand a sheet-driven picker ([Select](../form-field/select.md)), or the row *only* navigates without selecting (use a [Standard](./standard.md) row with `nav: true`). When a value both selects *and* opens a deeper screen — a major category — keep Radio and add `nav: true` (see [Major category with a second screen](#major-category-with-a-second-screen)).
+
+**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.*`; do **not** wrap the list in another `padding-inline` / `px-*` / `style={{ padding: … }}` div, or the radio indicator lands at a different inset than the section headings around it. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+A radio-selectable list — single-select picker over the shared anatomy.
+
+```preview
+list/radio
+---
+import { useState } from 'react';
+import { List } from '@teamblind-chorus/ui';
+
+const [value, setValue] = useState('week');
+
+<List
+  variant="radio"
+  value={value}
+  onChange={setValue}
+  items={[
+    { value: 'day',     label: 'Day' },
+    { value: 'week',    label: 'Week' },
+    { value: 'month',   label: 'Month' },
+    { value: 'quarter', label: 'Quarter' },
+    { value: 'year',    label: 'Year' },
+  ]}
+/>
+```
+
+## Use cases
+
+### With supporting text
+
+Pairs each label with a secondary line — for when the label alone doesn't carry enough context (*sort orders explained in copy*, *equity types with one-line definitions*).
+
+```preview
+list/radio-with-supporting
+---
+import { useState } from 'react';
+import { List } from '@teamblind-chorus/ui';
+
+const [value, setValue] = useState('trending');
+
+<List
+  variant="radio"
+  value={value}
+  onChange={setValue}
+  aria-label="Sort posts by"
+  items={[
+    { value: 'newest',     label: 'Newest first',  supportingText: 'Most recent posts at the top' },
+    { value: 'trending',   label: 'Trending',      supportingText: 'Active threads from the last 24h' },
+    { value: 'most-liked', label: 'Most liked',    supportingText: 'Highest like count this week' },
+    { value: 'oldest',     label: 'Oldest first',  supportingText: 'Earliest posts at the top' },
+  ]}
+/>
+```
+
+### Disabled item
+
+A row pinned to `disabled: true` — pointer-events suppressed, indicator dims with the row at `sys.state.disabled` opacity. For options contextually unavailable but still belonging in the set (*paywalled tier*, *region-locked option*).
+
+```preview
+list/radio-disabled-item
+---
+import { useState } from 'react';
+import { List } from '@teamblind-chorus/ui';
+
+const [value, setValue] = useState('week');
+
+<List
+  variant="radio"
+  value={value}
+  onChange={setValue}
+  items={[
+    { value: 'day',     label: 'Day' },
+    { value: 'week',    label: 'Week' },
+    { value: 'month',   label: 'Month' },
+    { value: 'quarter', label: 'Quarter', disabled: true },
+    { value: 'year',    label: 'Year' },
+  ]}
+/>
+```
+
+### Major category with a second screen
+
+A `nav: true` row adds a trailing right-pointing chevron alongside the radio indicator — for a major category that both commits a value *and* opens a deeper screen of sub-options. Selecting the row fires `onChange`; the row's `onClick` routes to the second screen. The chevron is decorative; the whole row is the single click target.
+
+```preview
+list/radio-nav
+---
+import { useState } from 'react';
+import { List } from '@teamblind-chorus/ui';
+
+const [value, setValue] = useState('apparel');
+
+<List
+  variant="radio"
+  value={value}
+  onChange={setValue}
+  aria-label="Choose a category"
+  items={[
+    { value: 'all',      label: 'All categories' },
+    { value: 'apparel',  label: 'Apparel',     supportingText: 'Tops, outerwear, footwear', nav: true, onClick: () => {} },
+    { value: 'home',     label: 'Home & living', supportingText: 'Furniture, decor, kitchen', nav: true, onClick: () => {} },
+    { value: 'beauty',   label: 'Beauty' },
+  ]}
+/>
+```
+
+## Slots
+
+- **container** — outer vertical stack (delegates to family).
+- **row** — single list item; whole row is the click target.
+- **leading** — required. 24×24 (`sys.icon.lg`) radio indicator: `RadioIcon` (outline) at rest, `RadioFillIcon` (primary) when selected. Decorative.
+- **label** — primary row text. 16px / Regular / `onSurface`.
+- **supportingText** *(optional)* — secondary line under label.
+- **navChevron** *(optional, per-row)* — auto-rendered 16px right-pointing chevron, painted when the row sets `nav: true` — a major category that opens a second screen. `onSurfaceVariant`, decorative; never a separate hit target.
+
+## States
+
+`selected` is unique to this sub — the leading indicator switches to `RadioFillIcon` in `primary`; row foreground stays at `onSurface` (no fill change on the row itself).
+
+| State      | Overlay opacity      | Additional |
+|------------|----------------------|------------|
+| `default`  | —                    | Outline indicator. |
+| `hovered`  | `sys.state.hover`    | `:hover`. |
+| `pressed`  | `sys.state.pressed`  | `:active`. |
+| `selected` | —                    | Indicator → `RadioFillIcon` in `primary`. |
+| `disabled` | overlay suppressed   | Row at `sys.state.disabled` opacity; indicator dims with the row. |
+
+## Focus indicator
+
+Inward 3-layer ring inside the row's bounds — see [Focus indicator](./list.md#cross-sub-contract). The row is the keyboard target, not the indicator.
+
+## Behavior
+
+- **Keyboard navigation.** Arrow ↑ / ↓ moves focus; **Space** and **Enter** commit; Home / End jump to first / last.
+- **Selection model.** Single-select; selecting a row deselects the previous. Controlled via `value` + `onChange`.
+- **Row click target.** Whole row is clickable; the indicator is never a separate hit target.