@teamblind-chorus/ui 1.1.0 → 2.0.0

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

@@ -31,7 +31,7 @@
   "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."
+      "description": "Outer scroll surface. Vertical stack with a transparent fill (inherits parent container tone); rows separated by a 1px border.default divider, not a gap."
     },
     "row": {
       "required": true,
@@ -40,7 +40,7 @@
     "leading": {
       "required": false,
       "omittedBehavior": "collapsed",
-      "fallbackOnMissingSrc": "sys.color.surfaceContainerHigh",
+      "fallbackOnMissingSrc": "sys.color.surface.sunken",
       "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"
@@ -48,7 +48,7 @@
     },
     "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.",
+      "description": "Primary row text. `sys.typo.label.md` (14 / Semibold) / `sys.color.text.default`. 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"
       ]
@@ -63,14 +63,14 @@
     },
     "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.",
+      "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.text.default`. 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.",
+      "description": "Optional secondary line under the identity group. `sys.typo.label.sm` (12 / Semibold) / `sys.color.text.subtle`. 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"
       ]
@@ -126,7 +126,7 @@
     "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."
+      "description": "Per-row bottom-divider opt-out. Pass `divider: false` to suppress the hairline `border.default` 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",
@@ -156,17 +156,17 @@
     "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",
+    "dividerColor": "sys.color.border.default",
     "dividerPerRowOptOut": "Pass `divider: false` on a row to suppress its bottom divider.",
     "labelTypo": "sys.typo.label.md",
-    "labelColor": "sys.color.onSurface",
+    "labelColor": "sys.color.text.default",
     "labelToCountGap": "sys.layout.inline.sm",
     "secondaryTypo": "sys.typo.label.sm",
-    "secondaryColor": "sys.color.onSurface",
+    "secondaryColor": "sys.color.text.default",
     "secondaryToLabelGap": "0",
     "identityToDescriptionGap": "ref.space.25",
     "descriptionTypo": "sys.typo.label.sm",
-    "descriptionColor": "sys.color.onSurfaceVariant",
+    "descriptionColor": "sys.color.text.subtle",
     "descriptionMaxLines": 1,
     "leadingThumbnailSize": {
       "small": 32,
@@ -176,7 +176,7 @@
     },
     "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"
+    "trailingIconColor": "sys.color.text.subtle"
   },
   "states": {
     "default": {
@@ -194,28 +194,44 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "inward",
+        "layer": "::after/::before overlay — position:absolute, inset:0, inset box-shadow, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.border.focused"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.border.focused"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the row is in; never via plain mouse click."
+    },
     "nestedActionScope": "The hover / pressed overlay is suppressed while the pointer sits on the independent trailing action (a favorite / follow / overflow control). The small control owns the state; the large row does NOT also read as hovered / pressed. The visual-state boundary matches the event boundary (the trailing action already stops propagation).",
     "disabled": {
-      "containerOpacity": "sys.state.disabled",
-      "containerOpacityScope": "Dims the row content only — the inter-row divider and the focus overlay keep full opacity, so a disabled row never fades the hairline rule between it and the next row.",
-      "pointerEvents": "none"
+      "text": "sys.color.text.disabled",
+      "icon": "sys.color.icon.disabled",
+      "pointerEvents": "none",
+      "note": "Explicit disabled (no opacity): row text to text.disabled, icons to icon.disabled. Divider/focus overlay unaffected."
     }
   },
   "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.",
+    "compositionReason": "Rows tile the column flush with only a hairline `border.default` 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)",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "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)"

package/agents/components/list/list.md

@@ -10,7 +10,7 @@ A vertically-stacked sequence of rows for menus, settings panels, picker sheets,
 
 ## 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.
+- **Container.** Vertical stack, transparent fill (inherits the parent surface). Rows separated by a 1px `border.default` 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.
@@ -23,4 +23,4 @@ A vertically-stacked sequence of rows for menus, settings panels, picker sheets,
 - **[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.
+- **[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 `border.default` divider paints at the top of the body so parent ↔ child hierarchy reads.

package/agents/components/list/radio.md

@@ -4,7 +4,7 @@
 
 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)).
+**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](#major-category)).
 
 **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).
 
@@ -18,25 +18,22 @@ list/radio
 import { useState } from 'react';
 import { List } from '@teamblind-chorus/ui';
 
-const [value, setValue] = useState('week');
+const [value, setValue] = useState('trending');
 
 <List
   variant="radio"
   value={value}
   onChange={setValue}
+  aria-label="Sort posts by"
   items={[
-    { value: 'day',     label: 'Day' },
-    { value: 'week',    label: 'Week' },
-    { value: 'month',   label: 'Month' },
-    { value: 'quarter', label: 'Quarter' },
-    { value: 'year',    label: 'Year' },
+    { value: 'newest',     label: 'Newest first' },
+    { value: 'trending',   label: 'Trending' },
+    { value: 'most-liked', label: 'Most liked' },
   ]}
 />
 ```
 
-## Use cases
-
-### With supporting text
+## 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*).
 
@@ -57,12 +54,11 @@ const [value, setValue] = useState('trending');
     { 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
+## 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*).
 
@@ -79,16 +75,14 @@ const [value, setValue] = useState('week');
   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' },
+    { value: 'day',   label: 'Day' },
+    { value: 'week',  label: 'Week' },
+    { value: 'month', label: 'Month', disabled: true },
   ]}
 />
 ```
 
-### Major category with a second screen
+## Major category
 
 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.
 
@@ -109,7 +103,6 @@ const [value, setValue] = useState('apparel');
     { 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' },
   ]}
 />
 ```
@@ -137,7 +130,7 @@ const [value, setValue] = useState('apparel');
 
 ## 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.
+Inward single ring inside the row's bounds — see [Focus indicator](./list.md#cross-sub-contract). The row is the keyboard target, not the indicator.
 
 ## Behavior
 

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

@@ -30,7 +30,7 @@
   "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."
+      "description": "Outer scroll surface. Vertical stack with a transparent fill (inherits parent container tone); rows separated by a 1px border.default divider, not a gap."
     },
     "row": {
       "required": true,
@@ -114,17 +114,17 @@
     "trailingActionGap": "sys.layout.inline.md",
     "trailingActionGapNote": "Fixed 8px between the text group and a trailing nav chevron (the major-category `nav: true` case) — the family-wide trailing gap.",
     "dividerWidth": "sys.borderWidth.hairline",
-    "dividerColor": "sys.color.outlineVariant",
+    "dividerColor": "sys.color.border.default",
     "labelTypo": "sys.typo.body.md",
-    "labelColor": "sys.color.onSurface",
+    "labelColor": "sys.color.text.default",
     "supportingTypo": "sys.typo.body.sm",
-    "supportingColor": "sys.color.onSurfaceVariant",
+    "supportingColor": "sys.color.text.subtle",
     "supportingOffset": "0",
     "leadingRadioSize": "24 × 24",
-    "leadingRadioColorRest": "sys.color.outline",
-    "leadingRadioColorSelected": "sys.color.primary",
+    "leadingRadioColorRest": "sys.color.border.boldest",
+    "leadingRadioColorSelected": "sys.color.background.primary",
     "navChevronSize": "16 × 16",
-    "navChevronColor": "sys.color.onSurfaceVariant"
+    "navChevronColor": "sys.color.text.subtle"
   },
   "states": {
     "default": {
@@ -142,31 +142,46 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "inward",
+        "layer": "::after/::before overlay — position:absolute, inset:0, inset box-shadow, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.border.focused"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.border.focused"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the row is in; never via plain mouse click."
+    },
     "selected": {
       "leading": "Filled primary indicator; row foreground stays at onSurface. No fill change on the row itself."
     },
     "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.",
+      "text": "sys.color.text.disabled",
+      "icon": "sys.color.icon.disabled",
       "pointerEvents": "none",
-      "note": "Radio indicator dims with the row."
+      "note": "Explicit disabled (no opacity): row text to text.disabled, radio indicator + icons to icon.disabled. Divider/focus overlay unaffected."
     }
   },
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. The ring sits on the row, not on the leading indicator — the row is the keyboard target.",
     "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.",
+    "compositionReason": "Rows tile the column flush with only a hairline `border.default` 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)",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "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)"
@@ -181,6 +196,6 @@
   "forbidden": [
     "radio glyph as a separate hit area — the entire row is the click target",
     "multi-select painted as radio — radio variant is single-select; use checkbox or chip/filter for multi-select",
-    "selected state painted with sys.color.primaryContainer fill — radio selected paints the inner dot, not the row fill"
+    "selected state painted with sys.color.background.selected fill — radio selected paints the inner dot, not the row fill"
   ]
 }

package/agents/components/list/standard.md

@@ -10,7 +10,7 @@ A row opts into an inline `count` Badge to the right of the label (4px / `sys.la
 
 ## Default
 
-A plain text list — five menu rows with optional supporting text.
+A single text row — the atomic List component. A row is a `value` + `label`, with an optional `supportingText` second line. The whole row is the click target.
 
 ```preview
 list/standard
@@ -19,18 +19,12 @@ import { List } from '@teamblind-chorus/ui';
 
 <List
   items={[
-    { value: 'profile',  label: 'Profile',         supportingText: 'Name, photo, bio' },
-    { value: 'notif',    label: 'Notifications',   supportingText: 'Email, push, in-app' },
-    { value: 'privacy',  label: 'Privacy',         supportingText: 'Who can see your activity' },
-    { value: 'language', label: 'Language' },
-    { value: 'about',    label: 'About' },
+    { value: 'profile', label: 'Profile', supportingText: 'Display name, avatar, bio' },
   ]}
 />
 ```
 
-## Use cases
-
-### With trailing action
+## Trailing action
 
 A Text Button in the row's `trailingIcon` slot turns a display row into row + action — the row label stays informational (no `onClick` on the row), the trailing button is the only commit target. Reach for it on settings rows that pair a value with a small "change / edit / view" action.
 
@@ -52,21 +46,11 @@ import { Button, List } from '@teamblind-chorus/ui';
         </Button>
       ),
     },
-    {
-      value: 'sms',
-      label: 'SMS',
-      supportingText: '+1 (415) ***-2487',
-      trailingIcon: (
-        <Button variant="text" size="small" appearance="accent" onClick={() => {}}>
-          Edit
-        </Button>
-      ),
-    },
   ]}
 />
 ```
 
-### With an inline count
+## Inline count
 
 Pass a `count` on a row and a Badge renders to the right of the label on the same line, separated by `4px` (`sys.layout.inline.sm`) — the unread / status-count case. The label shrinks first so a long label truncates against the count, which stays pinned at its intrinsic width. Unlike `trailingIcon`, the count tiles tight to the label inside the text group, so it **composes with the drill-in chevron**: a `nav: true` row carries the count by the label *and* keeps its trailing chevron — one row with both an icon and a badge.
 
@@ -77,16 +61,12 @@ import { List, Badge } from '@teamblind-chorus/ui';
 
 <List
   items={[
-    { value: 'profile',  label: 'Profile',       supportingText: 'Display name, avatar, bio', nav: true },
-    { value: 'channels', label: 'My channels',   supportingText: '12 joined · 3 muted', nav: true },
-    { value: 'notif',    label: 'Notifications', count: <Badge>3</Badge>, nav: true },
-    { value: 'privacy',  label: 'Privacy', nav: true },
-    { value: 'account',  label: 'Account', nav: true },
+    { value: 'notif', label: 'Notifications', count: <Badge>3</Badge>, nav: true },
   ]}
 />
 ```
 
-### Drill-in rows
+## Drill-in
 
 Set `nav: true` on a row to auto-render a trailing right-pointing chevron — the drill-in affordance signalling the row routes to another surface. The whole row is the click target; the chevron is decorative. This is the canonical settings / menu navigation shape (it replaces the former `nav` variant). A per-item `trailingIcon` overrides the chevron for that row.
 
@@ -97,16 +77,12 @@ import { List } from '@teamblind-chorus/ui';
 
 <List
   items={[
-    { value: 'profile',  label: 'Profile',         supportingText: 'Display name, avatar, bio', nav: true },
-    { value: 'channels', label: 'My channels',     supportingText: '12 joined · 3 muted',        nav: true },
-    { value: 'notif',    label: 'Notifications', nav: true },
-    { value: 'privacy',  label: 'Privacy',       nav: true },
-    { value: 'account',  label: 'Account',       nav: true },
+    { value: 'profile', label: 'Profile', supportingText: 'Display name, avatar, bio', nav: true },
   ]}
 />
 ```
 
-### With a leading icon
+## Leading icon
 
 Pass an `icon` on a row and a 24px (`sys.icon.lg`) glyph renders at the leading edge in `onSurfaceVariant`, `8px` (`sys.layout.inline.md`) from the text group — the category-mark shape for settings / menu rows, lighter than a 40px leading image (and mutually exclusive with `thumbnail`). The glyph is decorative (the label carries the meaning) and the slot enforces the 24 rung regardless of the glyph's own `size`. Every other slot stays optional, so the icon composes with `supportingText`, an inline `count`, and the drill-in chevron.
 
@@ -114,19 +90,16 @@ Pass an `icon` on a row and a 24px (`sys.icon.lg`) glyph renders at the leading
 list/standard-icon-leading
 ---
 import { List, Badge } from '@teamblind-chorus/ui';
-import { ProfileIcon, BellIcon, BookmarkIcon, PulseIcon } from '@teamblind-chorus/ui/icons';
+import { BellIcon } from '@teamblind-chorus/ui/icons';
 
 <List
   items={[
-    { value: 'profile',  label: 'Profile',       supportingText: 'Display name, avatar, bio', icon: <ProfileIcon />, nav: true },
-    { value: 'notif',    label: 'Notifications', icon: <BellIcon />, count: <Badge>3</Badge>, nav: true },
-    { value: 'saved',    label: 'Saved',         icon: <BookmarkIcon />, nav: true },
-    { value: 'activity', label: 'Activity',      icon: <PulseIcon />, nav: true },
+    { value: 'notif', label: 'Notifications', icon: <BellIcon />, count: <Badge>3</Badge>, nav: true },
   ]}
 />
 ```
 
-### Leading image
+## Leading image
 
 Pass a `thumbnail` on a row and a 40px [Thumbnail](../thumbnail/thumbnail.md) renders at the leading edge, vertically centred against the label column. `thumbnail` props (`src`, `alt`, `updateDot`, `logoBadge`) forward verbatim. The gap to the text group steps up to `12px` (`sys.layout.inline.lg`) so the avatar and the label column read as two distinct blocks. This is the channel / source / author row shape — same click semantics as a text row, no selection model.
 
@@ -137,14 +110,12 @@ import { List } from '@teamblind-chorus/ui';
 
 <List
   items={[
-    { value: 'design-weekly', label: 'Design Weekly', supportingText: 'Updated 2h ago', thumbnail: { alt: 'Design Weekly' } },
-    { value: 'frontend',      label: 'Frontend Friday', supportingText: 'Updated 1d ago', thumbnail: { alt: 'Frontend Friday' } },
-    { value: 'changelog',     label: 'Changelog',       supportingText: 'Updated 3d ago', thumbnail: { alt: 'Changelog' } },
+    { value: 'sourdough', label: 'Sourdough Bakers', supportingText: '3 new posts today', thumbnail: { alt: 'Sourdough Bakers' } },
   ]}
 />
 ```
 
-### Leading image — with trailing action
+## Leading image + trailing action
 
 A Text Button in the row's `trailingIcon` slot — the canonical "directory row + small commit" composition. Reach for it on follow / join / invite rows where the leading Thumbnail anchors the entity and the trailing button is the only commit. Row body stays informational.
 
@@ -167,22 +138,11 @@ import { Button, List } from '@teamblind-chorus/ui';
         </Button>
       ),
     },
-    {
-      value: 'frontend',
-      label: 'Frontend',
-      supportingText: '892 colleagues following',
-      thumbnail: { alt: 'Frontend' },
-      trailingIcon: (
-        <Button variant="text" size="small" appearance="accent" onClick={() => {}}>
-          Follow
-        </Button>
-      ),
-    },
   ]}
 />
 ```
 
-### Leading image — drill-in rows
+## Leading image + drill-in
 
 Set `nav: true` on a leading-image row for an avatar-anchored row that routes to another surface (channel → channel detail, person → profile). The whole row is the click target; the chevron is decorative. A per-item `trailingIcon` overrides the chevron.
 
@@ -193,14 +153,12 @@ import { List } from '@teamblind-chorus/ui';
 
 <List
   items={[
-    { value: 'design-weekly', label: 'Design Weekly',   supportingText: '2.3k members', thumbnail: { alt: 'Design Weekly' }, nav: true },
-    { value: 'frontend',      label: 'Frontend Friday', supportingText: '1.1k members', thumbnail: { alt: 'Frontend Friday' }, nav: true },
-    { value: 'changelog',     label: 'Changelog',       supportingText: '840 members',  thumbnail: { alt: 'Changelog' }, nav: true },
+    { value: 'design-weekly', label: 'Design Weekly', supportingText: '2.3k members', thumbnail: { alt: 'Design Weekly' }, nav: true },
   ]}
 />
 ```
 
-### Leading image — without divider
+## Leading image, no divider
 
 `divider: false` on a row suppresses its bottom hairline rule — useful when a visual group ends mid-stack and the divider would visually fence off the next group from its label. The row's footprint and inline padding stay unchanged.
 
@@ -218,6 +176,75 @@ import { List } from '@teamblind-chorus/ui';
 />
 ```
 
+## Embedded Banner
+
+Pass a `banner` on a row and a [Banner](../banner/banner.md) renders **below** the row's text group, `8px` (`sys.layout.stack.xs`) down, spanning the row's full content width (aligned to the same 16px inline inset as the label above it). The row flips from a single line to a vertical stack — text group on top, Banner underneath. Reach for it when a row needs an in-row call-out tied to *that row's* subject (a follow-up prompt, a capability nudge, a single-line CTA), rather than a separate full-width Banner detached from the row.
+
+The Banner keeps its full prop surface — here `appearance="accent"` + `neutralBody` for the quiet-tint shape, a blue `CheckCircleFillIcon` leading the single-line body, and a `trailingAction` Text Button with a trailing chevron. The Banner is a nested-action region: its button never commits the row, and the row's hover / pressed overlay is suppressed over it. The row leads with a fill-type category glyph (`BriefcaseFillIcon`) that the leading slot tones to `onSurfaceVariant`.
+
+```preview
+list/standard-embedded-banner
+---
+import { Banner, Button, List } from '@teamblind-chorus/ui';
+import { BriefcaseFillIcon, CheckCircleFillIcon, ChevronRightIcon } from '@teamblind-chorus/ui/icons';
+
+<List
+  aria-label="Career"
+  items={[
+    {
+      value: 'major',
+      label: 'My major: Computer Science',
+      strong: true,
+      icon: <BriefcaseFillIcon />,
+      banner: (
+        <Banner
+          appearance="accent"
+          neutralBody
+          icon={<CheckCircleFillIcon size={16} style={{ color: 'var(--sys-color-background-primary)' }} />}
+          trailingAction={(
+            <Button variant="text" appearance="accent" size="small" trailingIcon={<ChevronRightIcon />}>
+              Expert Q&A
+            </Button>
+          )}
+        >
+          Ask a professional in this field
+        </Banner>
+      ),
+    },
+  ]}
+/>
+```
+
+## Group
+
+Several rows bundled into one `<List>`. Every row carries a leading icon and reaches for a different per-row variant — a drill-in row, a row with an inline `count` + drill-in chevron, a row with a trailing action — so the group reads as the realistic composition the single-variant sections below each isolate one facet of. Rows tile with a hairline divider between them; the last row drops its divider automatically (no `divider: false` needed).
+
+```preview
+list/standard-group
+---
+import { Badge, Button, List } from '@teamblind-chorus/ui';
+import { BellIcon, InvitationIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+
+<List
+  aria-label="Account"
+  items={[
+    { value: 'profile', label: 'Profile', supportingText: 'Display name, avatar, bio', icon: <ProfileIcon />, nav: true },
+    { value: 'notif', label: 'Notifications', icon: <BellIcon />, count: <Badge>3</Badge>, nav: true },
+    {
+      value: 'email',
+      label: 'Email',
+      supportingText: 'work@example.com',
+      icon: <InvitationIcon />,
+      trailingIcon: (
+        <Button variant="text" size="small" appearance="accent" onClick={() => {}}>
+          Edit
+        </Button>
+      ),
+    },
+  ]}
+/>
+```
+
 ## Slots
 
 - **container** — outer vertical stack (delegates to family).
@@ -231,6 +258,7 @@ import { List } from '@teamblind-chorus/ui';
 - **trailingIcon** *(optional, per-row)* — consumer-supplied node at the trailing edge. Each row decides independently. Canonical fills: a 16px icon (e.g. an external-link mark), or `<Button variant="text" appearance="accent">` (Follow / Invite) on leading-image rows. A status badge does **not** go here — it tiles next to the label via `count`. Its own hit target: a tap on this slot stops propagating before it reaches the row's `onClick`. Overrides the nav chevron on the same row.
 - **navChevron** *(optional, per-row)* — auto-rendered 16px right-pointing chevron, painted when the row sets `nav: true`. `onSurfaceVariant`, decorative; never a separate hit target.
 - **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.
+- **banner** *(optional, per-row)* — an embedded [Banner](../banner/banner.md) below the row's text group, `8px` (`sys.layout.stack.xs`) down, spanning the row's full content width. The row stacks (text group over Banner). A nested-action region: its own controls never commit the row, and the row's hover / pressed overlay is suppressed over it. Canonical fill: `<Banner appearance="accent" neutralBody icon={…} trailingAction={…}>` — an in-row call-out tied to the row's subject.
 
 ## States
 
@@ -238,7 +266,7 @@ No `selected` state — selection belongs to the [Radio sub](./radio.md).
 
 ## Focus indicator
 
-Inward 3-layer ring inside the row's bounds — see the family-wide [Focus indicator](./list.md#cross-sub-contract). The preview pins **My channels** to its focused state via `forcedState: 'focused'` for static inspection.
+Inward single ring inside the row's bounds — see the family-wide [Focus indicator](./list.md#cross-sub-contract). The preview pins **My channels** to its focused state via `forcedState: 'focused'` for static inspection.
 
 ```preview
 list/focus-indicator
@@ -247,11 +275,7 @@ import { List } from '@teamblind-chorus/ui';
 
 <List
   items={[
-    { value: 'profile',  label: 'Profile',         supportingText: 'Display name, avatar, bio', nav: true },
-    { value: 'channels', label: 'My channels',     supportingText: '12 joined · 3 muted', nav: true, forcedState: 'focused' },
-    { value: 'notif',    label: 'Notifications', nav: true },
-    { value: 'privacy',  label: 'Privacy', nav: true },
-    { value: 'account',  label: 'Account', nav: true },
+    { value: 'channels', label: 'My channels', supportingText: '12 joined · 3 muted', nav: true, forcedState: 'focused' },
   ]}
 />
 ```