@teamblind-chorus/ui 1.1.0 → 2.0.0

package/agents/components/header/main.spec.json

@@ -56,7 +56,7 @@
     },
     "label": {
       "required": false,
-      "description": "Heading text. `<h3>` by default. Size `large` → `sys.typo.heading.md`; size `medium` → `sys.typo.heading.sm`. Color `sys.color.onSurface`."
+      "description": "Heading text. `<h3>` by default. Size `large` → `sys.typo.heading.md`; size `medium` → `sys.typo.heading.sm`. Color `sys.color.text.default`."
     },
     "action": {
       "required": false,
@@ -85,10 +85,10 @@
     "medium": {
       "labelTypo": "sys.typo.heading.sm (16 / Semibold)"
     },
-    "labelColor": "sys.color.onSurface",
+    "labelColor": "sys.color.text.default",
     "actionSize": "Text Button xsmall, appearance accent",
     "iconButtonSize": "Button variant=\"icon\" size=\"medium\" (32 × 32 capsule, 16-glyph)",
-    "iconColor": "sys.color.onSurfaceVariant (glyph inherits via `currentColor` from the Icon Button)"
+    "iconColor": "sys.color.text.subtle (glyph inherits via `currentColor` from the Icon Button)"
   },
   "appearance": {
     "background": "transparent",

package/agents/components/header/sub.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/header/sub.md`](../../../i18n/ko/schema/components/header/sub.md)
 
-Quiet section-dividing label — a 14px (`sys.typo.label.md`, 14 / Semibold) line in the muted `sys.color.onSurfaceVariant` tone that names the group of rows beneath it ("Following", "More Topics to follow"). The muted tone is the dividing device: it reads as a region label rather than a heading that competes with the page title, while the label-weight typo keeps it from dissolving into body copy. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label.
+Quiet section-dividing label — a 14px (`sys.typo.label.md`, 14 / Semibold) line in the muted `sys.color.text.subtle` tone that names the group of rows beneath it ("Following", "More Topics to follow"). The muted tone is the dividing device: it reads as a region label rather than a heading that competes with the page title, while the label-weight typo keeps it from dissolving into body copy. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label.
 
 It may carry one quiet trailing affordance — a single [Text Button](../button/text.md) `action` ("See all", "Edit", "Manage") — for a region-level commit that stays subordinate to the muted label. Icon drill-in and dropdown disclosure are *not* SubHeader's: those belong on [Main](./main.md), whose louder `onSurface` heading earns the heavier affordance set.
 
@@ -22,9 +22,7 @@ import { SubHeader } from '@teamblind-chorus/ui';
 <SubHeader label="Following" />
 ```
 
-## Use cases
-
-### Grouping a list
+## Grouping a list
 
 The canonical placement — a SubHeader labels each group of rows, splitting one stacked list into named sections. The muted label sits at the same `16px` inset as the rows; the block rhythm (more above, less below) reads as "new group starts here".
 
@@ -69,7 +67,7 @@ function Example() {
 }
 ```
 
-### With a trailing action
+## Trailing action
 
 Pass `action={{ label, href, onClick }}` for a single quiet commit on the trailing edge — "See all" above a previewed group, "Edit" above an editable cluster. The wrapper becomes a full-bleed flex row: the muted label holds the leading edge, the [Text Button](../button/text.md) (`size="xsmall"`, `appearance="accent"`) hugs the trailing edge at the same 16 inset. The action stays subordinate to the label — this is still a quiet region marker, not a [Main](./main.md) heading row. Use Main instead when the region needs the louder `onSurface` heading, an icon drill-in, or a sort dropdown.
 
@@ -91,7 +89,7 @@ import { SubHeader, List } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### Host owns the heading
+## Host owns the heading
 
 When the surrounding host already carries the section semantics, override the wrapping element with `as="div"` so the document outline doesn't gain a stray heading — the label keeps its muted tone and inset.
 
@@ -106,7 +104,7 @@ import { SubHeader } from '@teamblind-chorus/ui';
 ## Slots
 
 - **container** — the full-bleed label line. `16px` (`layout.container.md`) inline inset to align with the rows beneath, `24px` (`layout.stack.lg`) block padding above and `8px` (`layout.stack.xs`) below. Non-interactive. Without `action` the container *is* the heading element (`as`); with `action` it is a non-semantic flex `<div>` (`space-between`, `8px` `layout.inline.md` gap) holding the nested label and the trailing action on opposite edges.
-- **label** — required. Section label text. `<h3>` by default (override via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.onSurfaceVariant`. Single line.
+- **label** — required. Section label text. `<h3>` by default (override via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.text.subtle`. Single line.
 - **action** — optional. Trailing [Text Button](../button/text.md) (`size="xsmall"`, `appearance="accent"`) from `action={{ label, href, onClick }}`. The one trailing affordance SubHeader carries; owns its own tap target. Present only when `action` is set.
 
 ## Anatomy
@@ -114,7 +112,7 @@ import { SubHeader } from '@teamblind-chorus/ui';
 | Slot      | Token bindings |
 |-----------|----------------|
 | container | `sys.layout.container.md` (16) inline padding, `sys.layout.stack.lg` (24) block-start, `sys.layout.stack.xs` (8) block-end, full inline width, no border, no radius; in `action` mode flex `space-between` with `sys.layout.inline.md` (8) gap |
-| label     | `sys.typo.label.md` (14 / Semibold) typo, `sys.color.onSurfaceVariant` color |
+| label     | `sys.typo.label.md` (14 / Semibold) typo, `sys.color.text.subtle` color |
 | action    | [Text Button](../button/text.md) `size="xsmall"`, `appearance="accent"`; intrinsic width, never grows |
 
 ## Appearance

package/agents/components/header/sub.spec.json

@@ -3,7 +3,7 @@
   "name": "SubHeader",
   "family": "header",
   "subcomponent": "sub",
-  "description": "The quiet member of the Header family — a section-dividing label. A single line of 14px (`sys.typo.label.md`, 14 / Semibold) text in the muted `sys.color.onSurfaceVariant` tone that names the group of rows beneath it (\"Following\", \"More Topics to follow\"). No size axis — the muted tone is the dividing device, and the label-weight typo keeps it reading as a section label rather than body copy. Reached as `<SubHeader>`; its louder sibling is [Main](./main.md) (`<Header>`), an `onSurface` heading at 16 / 20. Optionally carries a single trailing `action` Text Button (`size=\"xsmall\"`, `appearance=\"accent\"`) for a quiet region-level commit (\"See all\", \"Edit\", \"Manage\"); icon drill-in and dropdown disclosure stay Main's territory, where the louder `onSurface` heading tone belongs. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label; consumers may override the wrapping element via the `as` prop (e.g. `as=\"div\"` when the host already owns the heading semantics). Full-bleed: pays the same 16 (`sys.layout.container.md`) inline inset as the List rows it labels, with asymmetric block padding (24 above to break from the previous region, 8 below to bind the label to its group).",
+  "description": "The quiet member of the Header family — a section-dividing label. A single line of 14px (`sys.typo.label.md`, 14 / Semibold) text in the muted `sys.color.text.subtle` tone that names the group of rows beneath it (\"Following\", \"More Topics to follow\"). No size axis — the muted tone is the dividing device, and the label-weight typo keeps it reading as a section label rather than body copy. Reached as `<SubHeader>`; its louder sibling is [Main](./main.md) (`<Header>`), an `onSurface` heading at 16 / 20. Optionally carries a single trailing `action` Text Button (`size=\"xsmall\"`, `appearance=\"accent\"`) for a quiet region-level commit (\"See all\", \"Edit\", \"Manage\"); icon drill-in and dropdown disclosure stay Main's territory, where the louder `onSurface` heading tone belongs. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label; consumers may override the wrapping element via the `as` prop (e.g. `as=\"div\"` when the host already owns the heading semantics). Full-bleed: pays the same 16 (`sys.layout.container.md`) inline inset as the List rows it labels, with asymmetric block padding (24 above to break from the previous region, 8 below to bind the label to its group).",
   "element": "h3",
   "props": {
     "label": {
@@ -40,7 +40,7 @@
     },
     "label": {
       "required": false,
-      "description": "Section label text. `<h3>` by default (overridable via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.onSurfaceVariant`. Single line.",
+      "description": "Section label text. `<h3>` by default (overridable via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.text.subtle`. Single line.",
       "accepts": ["text"]
     },
     "action": {
@@ -53,7 +53,7 @@
   "appearance": {
     "containerFill": "transparent",
     "labelTypo": "sys.typo.label.md",
-    "labelColor": "sys.color.onSurfaceVariant",
+    "labelColor": "sys.color.text.subtle",
     "paddingInline": "sys.layout.container.md",
     "paddingBlockStart": "sys.layout.stack.lg",
     "paddingBlockEnd": "sys.layout.stack.xs",

package/agents/components/list/accordion.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/list/accordion.md`](../../../i18n/ko/schema/components/list/accordion.md)
 
-Expandable-row List sub. Each item exposes a List-row trigger (label + auto-rendered trailing chevron that rotates `180°` on expand) and a body that paints below it when open. Rows tile flush with the family hairline `outlineVariant` divider between them; an extra rule paints between the open trigger and its child row group.
+Expandable-row List sub. Each item exposes a List-row trigger (label + auto-rendered trailing chevron that rotates `180°` on expand) and a body that paints below it when open. Rows tile flush with the family hairline `border.default` divider between them; an extra rule paints between the open trigger and its child row group.
 
 **Reach for this when** a list of titled sections is too long to keep open at once — FAQs, T&C sections, expandable filter groups, settings groups with infrequent edits, hierarchical menus (companies → channels, regions → cities). **Skip when** bodies are short enough to read inline (use [Carousel](../carousel/carousel.md) per group), the user needs to act on labels (use a [List/standard](./standard.md) drill-in row or [List/radio](./radio.md)), or every item should be visible at once (stack [Carousel](../carousel/carousel.md)s).
 
@@ -12,7 +12,7 @@ Row geometry, label typography, divider, state overlays, and inward focus ring a
 
 ## Default
 
-Single-mode form. One item open at a time; clicking an open item collapses it (`collapsible={true}` by default).
+A single expandable row — the atomic Accordion item. Click the trigger to expand its body; click again to collapse (`collapsible` by default). The Group / Multiple sections below stack several. `type="single"` keeps one item open at a time.
 
 ```preview
 accordion/default
@@ -23,42 +23,12 @@ import { Accordion } from '@teamblind-chorus/ui';
   <Accordion.Item value="why" label="Why does Blind anonymise posts?">
     Anonymity is the only way employees can compare salaries, escalate misconduct, or ask candid culture questions without retaliation. Verified company badges keep the channel trustworthy without unmasking the author.
   </Accordion.Item>
-  <Accordion.Item value="verify" label="How is my company verified?">
-    Sign up with your corporate email — the verification code lands in your inbox, never on a public profile. Once verified, the badge persists across job changes (we re-verify when you update your employer).
-  </Accordion.Item>
-  <Accordion.Item value="data" label="What can other users see?">
-    Other users see your company badge, your career stage, and the content you post. Your email, name, and exact title are never exposed.
-  </Accordion.Item>
-</Accordion>
-```
-
-## Use cases
-
-### Multiple
-
-`type="multiple"` lets the user open any number of items at once. Use when rows are independent and the user reads across several — comparing T&C clauses, expanding filter groups, reviewing policy sections.
-
-```preview
-accordion/multiple
----
-import { Accordion } from '@teamblind-chorus/ui';
-
-<Accordion type="multiple" defaultValue={['salary', 'tenure']} aria-label="Active filters">
-  <Accordion.Item value="salary" label="Compensation">
-    Filter posts by salary range, equity, sign-on bonus.
-  </Accordion.Item>
-  <Accordion.Item value="tenure" label="Tenure">
-    Filter authors by years at current company.
-  </Accordion.Item>
-  <Accordion.Item value="role" label="Role">
-    Filter by IC level, manager track, or specialty.
-  </Accordion.Item>
 </Accordion>
 ```
 
-### Nested list
+## Nested list
 
-When the body holds a same-kind row group rather than prose — directory sub-entries, settings sub-options, filter children, menu sub-items — drop a `<List>` into the content slot with `embedded={true}` so the list defers its own chrome to the host. The body recognises the embedded child via `:has([data-embedded='true'])` and switches to compact-host geometry: body inline padding flips from prose's `32 leading / 16 trailing` to `16 / 0` (sub-list stretches flush right), a hairline `outlineVariant` top group-divider paints via the body's `::before`, and sub-list rows compress to `body.sm` at `40px` min-height with inter-row dividers suppressed. Call sites pass no extra mode prop — dropping `<List embedded>` (or a nested `<Accordion embedded>`) activates it automatically.
+When the body holds a same-kind row group rather than prose — directory sub-entries, settings sub-options, filter children, menu sub-items — drop a `<List>` into the content slot with `embedded={true}` so the list defers its own chrome to the host. The body recognises the embedded child via `:has([data-embedded='true'])` and switches to compact-host geometry: body inline padding flips from prose's `32 leading / 16 trailing` to `16 / 0` (sub-list stretches flush right), a hairline `border.default` top group-divider paints via the body's `::before`, and sub-list rows compress to `body.sm` at `40px` min-height with inter-row dividers suppressed. Call sites pass no extra mode prop — dropping `<List embedded>` (or a nested `<Accordion embedded>`) activates it automatically.
 
 ```preview
 accordion/nested-list
@@ -107,7 +77,7 @@ import { Accordion, List } from '@teamblind-chorus/ui';
 </Accordion>
 ```
 
-### Disabled item
+## Disabled item
 
 A `disabled` row fades to `sys.state.disabled` opacity and ignores click / keyboard activation. Stays in the DOM so surrounding items keep their stable index.
 
@@ -123,8 +93,27 @@ import { Accordion } from '@teamblind-chorus/ui';
   <Accordion.Item value="billing" label="Billing" disabled>
     Available for verified enterprise accounts only.
   </Accordion.Item>
-  <Accordion.Item value="notifications" label="Notifications">
-    Email, push, and in-app notification preferences.
+</Accordion>
+```
+
+## Group
+
+`type="multiple"` lets the user open any number of items at once. Use when rows are independent and the user reads across several — comparing T&C clauses, expanding filter groups, reviewing policy sections.
+
+```preview
+accordion/multiple
+---
+import { Accordion } from '@teamblind-chorus/ui';
+
+<Accordion type="multiple" defaultValue={['salary', 'tenure']} aria-label="Active filters">
+  <Accordion.Item value="salary" label="Compensation">
+    Filter posts by salary range, equity, sign-on bonus.
+  </Accordion.Item>
+  <Accordion.Item value="tenure" label="Tenure">
+    Filter authors by years at current company.
+  </Accordion.Item>
+  <Accordion.Item value="role" label="Role">
+    Filter by IC level, manager track, or specialty.
   </Accordion.Item>
 </Accordion>
 ```
@@ -132,25 +121,25 @@ import { Accordion } from '@teamblind-chorus/ui';
 ## Slots
 
 - **container** — outer stack. Transparent fill so the host surface tone reads through. `role="region"` carries the accordion's accessible name (`aria-label`).
-- **item** — single expandable row. Hairline `outlineVariant` divider inset 16px on both inline edges, painted as an `::after` overlay on every row except the last.
+- **item** — single expandable row. Hairline `border.default` divider inset 16px on both inline edges, painted as an `::after` overlay on every row except the last.
 - **trigger** — header button. Holds the label and the auto-rendered trailing chevron. Same geometry as a List row (48px min-height, 8 × 16 padding). `aria-expanded` reflects open-state, `aria-controls` references the content region.
 - **label** — trigger label. `16 / Regular / onSurface` — matches the List family `label` spec so the trigger reads as a List row that happens to expand. Wraps to a second line; no truncation.
 - **chevron** — auto-rendered 16px `ChevronDownIcon`. Rotates `0°` → `180°` over 120ms `ease-out` on expand. Decorative.
-- **content** — body region. Paints below the trigger when open; toggled via the `hidden` attribute when closed. `min-height: 40px` keeps short single-line bodies on a touch-target rhythm. Two padding modes by content kind: *prose body* (text, icon, button, form-field) uses `32 leading / 16 trailing` inline padding so prose reads as nested inside the trigger's label column, body text at `body.sm` (one rung below the trigger label), no top group-divider. *Embedded row group* (`<List embedded>` or nested `<Accordion embedded>`, detected via `:has([data-embedded='true'])`) uses `16 / 0` inline padding with a hairline `outlineVariant` top divider via `::before`; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
+- **content** — body region. Paints below the trigger when open; toggled via the `hidden` attribute when closed. `min-height: 40px` keeps short single-line bodies on a touch-target rhythm. Two padding modes by content kind: *prose body* (text, icon, button, form-field) uses `32 leading / 16 trailing` inline padding so prose reads as nested inside the trigger's label column, body text at `body.sm` (one rung below the trigger label), no top group-divider. *Embedded row group* (`<List embedded>` or nested `<Accordion embedded>`, detected via `:has([data-embedded='true'])`) uses `16 / 0` inline padding with a hairline `border.default` top divider via `::before`; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
 
 ## Anatomy
 
 | Slot          | Token bindings |
 |---------------|----------------|
 | container     | Transparent fill, no padding (full-bleed, edge-to-edge) |
-| item          | Hairline `outlineVariant` divider inset 16px on both inline edges, omitted on the last row — family-wide List divider |
+| item          | Hairline `border.default` divider inset 16px on both inline edges, omitted on the last row — family-wide List divider |
 | trigger       | 48px min-height, 8px block / 16px inline padding, full-row click target |
 | label         | `16 / Regular`, `onSurface` — matches the List `label` spec |
 | chevron       | 16 × 16, `onSurfaceVariant`, rotates 0° → 180° over 120ms `ease-out` |
 | content (prose)          | 8px block padding, `32 leading / 16 trailing` inline padding, `min-height: 40px`, `sys.typo.body.sm` (14 / Regular) at `onSurfaceVariant` |
 | content (embedded group) | 8px block padding, `16 leading / 0 trailing` inline padding; sub-list rows render at `body.sm` (14 / Regular), `min-height: 40px`, with `::after` row dividers suppressed |
-| divider       | `sys.borderWidth.hairline` × `sys.color.outlineVariant`, inset 16px on both inline edges via `::after` overlay |
-| groupDivider  | `sys.borderWidth.hairline` × `sys.color.outlineVariant`, inset 16px on both inline edges via `::before` overlay on the content body, painted ONLY when the body hosts a `<List embedded>` child group |
+| divider       | `sys.borderWidth.hairline` × `sys.color.border.default`, inset 16px on both inline edges via `::after` overlay |
+| groupDivider  | `sys.borderWidth.hairline` × `sys.color.border.default`, inset 16px on both inline edges via `::before` overlay on the content body, painted ONLY when the body hosts a `<List embedded>` child group |
 
 ## Appearance
 
@@ -167,14 +156,14 @@ A single appearance — Accordion paints no fill of its own and offers no emphas
 
 ## Focus indicator
 
-Inward 3-layer ring painted inside the trigger's footprint via a `::before` overlay. Trigger: `:focus-visible`. Items tile flush with only a hairline divider between them, so an outward ring would overlap the divider and the neighbouring row — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+Inward single ring painted inside the trigger's footprint via a `::before` overlay. Trigger: `:focus-visible`. Items tile flush with only a hairline divider between them, so an outward ring would overlap the divider and the neighbouring row — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
 
 ## Behavior
 
 - **Edge-to-edge composition.** `layoutInset: full-bleed` — direct child of the page shell. Wrapping in another `padding-inline` / `px-*` div double-pays the rail. Use the negative-margin opt-out inside a bounded surface.
-- **Inset divider.** 1px `outlineVariant` rule inset 16px on both inline edges — same as every other List sub.
+- **Inset divider.** 1px `border.default` rule inset 16px on both inline edges — same as every other List sub.
 - **Indented prose.** Expanded body sits one extra 16px in from the trigger's label edge for parent ↔ child hierarchy.
-- **Embedded groups switch the body to compact-host geometry.** When the body hosts a `<List embedded>`, three things change at once: body inline padding flips from `32 / 16` to `16 / 0` (sub-list flush right); a hairline `outlineVariant` rule paints at the body's top edge so parent and child read as a hierarchy; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
+- **Embedded groups switch the body to compact-host geometry.** When the body hosts a `<List embedded>`, three things change at once: body inline padding flips from `32 / 16` to `16 / 0` (sub-list flush right); a hairline `border.default` rule paints at the body's top edge so parent and child read as a hierarchy; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
 - **Whole trigger is the click target.** Chevron is decorative.
 - **Element swap.** Trigger is `<button>`; content region is `<div role="region">` with `hidden` toggled.
 - **Keyboard.** Space / Enter toggle. Arrow up/down moves focus between triggers.

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

@@ -85,7 +85,7 @@
     },
     "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.",
+      "description": "Single expandable row. Hairline `border.default` 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": {
@@ -105,12 +105,12 @@
     },
     "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.",
+      "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 `border.default` 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.",
+      "description": "Hairline `border.default` 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
     }
   },
@@ -119,9 +119,9 @@
     "triggerPaddingBlock": "sys.layout.container.xs",
     "triggerPaddingInline": "sys.layout.container.md",
     "triggerLabelTypo": "sys.typo.body.md",
-    "triggerLabelColor": "sys.color.onSurface",
+    "triggerLabelColor": "sys.color.text.default",
     "chevronSize": "sys.icon.md",
-    "chevronColor": "sys.color.onSurfaceVariant",
+    "chevronColor": "sys.color.text.subtle",
     "chevronGap": "sys.layout.inline.md",
     "chevronRotationDuration": "120ms",
     "chevronRotationTiming": "ease-out",
@@ -133,15 +133,15 @@
     "contentIndent": "sys.layout.container.md",
     "contentMinHeight": "ref.space.500",
     "contentBodyTypo": "sys.typo.body.sm",
-    "contentBodyColor": "sys.color.onSurfaceVariant",
+    "contentBodyColor": "sys.color.text.subtle",
     "embeddedRowLabelTypo": "sys.typo.body.sm",
     "embeddedRowMinHeight": "ref.space.500",
     "embeddedRowDivider": "none",
     "dividerWidth": "sys.borderWidth.hairline",
-    "dividerColor": "sys.color.outlineVariant",
+    "dividerColor": "sys.color.border.default",
     "dividerInsetInline": "sys.layout.container.md",
     "groupDividerWidth": "sys.borderWidth.hairline",
-    "groupDividerColor": "sys.color.outlineVariant",
+    "groupDividerColor": "sys.color.border.default",
     "groupDividerInsetInline": "sys.layout.container.md"
   },
   "appearances": {
@@ -158,20 +158,29 @@
     "pressed": {
       "overlay": { "color": "label", "opacity": "sys.state.pressed" }
     },
+    "focused": {
+      "focusRing": {
+        "composition": "inward",
+        "layer": "::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 — a single inward ring inside the trigger's footprint, with no state-overlay tint (the ring alone carries focus here). Mirrors the `focusIndicator` block for spec-only renderers. Composes over the lifecycle state the trigger is in."
+    },
     "disabled": {
-      "containerOpacity": "sys.state.disabled",
-      "pointerEvents": "none"
+      "text": "sys.color.text.disabled",
+      "icon": "sys.color.icon.disabled",
+      "pointerEvents": "none",
+      "note": "Explicit disabled (no opacity): trigger text to text.disabled, chevron/icons to icon.disabled."
     }
   },
   "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.",
+    "description": "Keyboard-focus visual painted as an inward single 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.",
+    "compositionReason": "Items tile flush with only a hairline `border.default` 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",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "implementation": "inset box-shadow on the trigger's `::before` overlay."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
@@ -194,7 +203,7 @@
     "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.",
+    "child list group rendered WITHOUT the top `border.default` 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

@@ -10,7 +10,7 @@ Directory-entry [List](./list.md) sub — an entity row pairing an optional lead
 
 ## 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.
+A single directory entry row — the atomic Entry component: leading Thumbnail + identity group (label + stacked `secondary` + single-line `description`) + a trailing follow toggle. Pick the Thumbnail rung via the **Size** dropdown (`xlarge` 56 → `small` 32); the row payload stays constant, only the leading avatar footprint changes.
 
 ```preview
 list/entry
@@ -31,23 +31,11 @@ import { Button, List } from '@teamblind-chorus/ui';
         <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)
+## Trailing Text Button
 
 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.
 
@@ -68,21 +56,13 @@ import { Button, List } from '@teamblind-chorus/ui';
         <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
+## 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.
+Uses the **single-shape fill-only contract**: always `<StarFillIcon>`, color flips by state (active = `var(--sys-color-icon-accent-yellow-default)`, inactive = `var(--sys-color-icon-subtle)`). 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
@@ -106,30 +86,7 @@ import { StarFillIcon } from '@teamblind-chorus/ui/icons';
           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)' }}
+          style={{ color: 'var(--sys-color-icon-accent-yellow-default)' }}
           onClick={() => {}}
         />
       ),
@@ -138,9 +95,9 @@ import { StarFillIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### As nav option (trailing chevron Icon Button)
+## Nav option
 
-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).
+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).
 
 ```preview
 list/entry-as-nav-option
@@ -167,26 +124,11 @@ import { ChevronRightIcon } from '@teamblind-chorus/ui/icons';
         />
       ),
     },
-    {
-      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)
+## Label only
 
 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.
 
@@ -206,25 +148,61 @@ import { ChevronRightIcon } from '@teamblind-chorus/ui/icons';
         <Button variant="icon" size="medium" aria-label="Open Location" icon={<ChevronRightIcon />} onClick={() => {}} />
       ),
     },
+  ]}
+/>
+```
+
+## Group
+
+Several directory rows bundled into one `<List>`, each with the leading Thumbnail and a different trailing affordance — a Follow toggle, a star favorite, a drill-in chevron — the realistic directory 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. 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-group
+---
+import { Button, List } from '@teamblind-chorus/ui';
+import { ChevronRightIcon, StarFillIcon } from '@teamblind-chorus/ui/icons';
+
+<List
+  variant="entry"
+  size="medium"
+  aria-label="Channels"
+  items={[
     {
-      value: 'job',
-      label: 'Job Function',
+      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 Job Function" icon={<ChevronRightIcon />} onClick={() => {}} />
+        <Button variant="toggle" onClick={() => {}}>Follow</Button>
       ),
     },
     {
-      value: 'learning',
-      label: 'Learning & Advising',
+      value: 'stocks',
+      label: 'Stocks & Investing',
+      secondary: '8,210 Followers',
+      thumbnail: { src: '/placeholder.png', alt: 'Stocks & Investing' },
       trailingIcon: (
-        <Button variant="icon" size="medium" aria-label="Open Learning & Advising" icon={<ChevronRightIcon />} onClick={() => {}} />
+        <Button
+          variant="icon" size="medium"
+          aria-label="Favorited" aria-pressed="true"
+          icon={<StarFillIcon />}
+          style={{ color: 'var(--sys-color-icon-accent-yellow-default)' }}
+          onClick={() => {}}
+        />
       ),
     },
     {
-      value: 'money',
-      label: 'Money',
+      value: 'indiedev',
+      label: 'Indie Game Devs',
+      secondary: '3 new this week',
+      thumbnail: { src: '/placeholder.png', alt: 'Indie Game Devs' },
       trailingIcon: (
-        <Button variant="icon" size="medium" aria-label="Open Money" icon={<ChevronRightIcon />} onClick={() => {}} />
+        <Button
+          variant="icon" size="medium"
+          aria-label="Open Indie Game Devs"
+          icon={<ChevronRightIcon />}
+          onClick={() => {}}
+        />
       ),
     },
   ]}
@@ -236,11 +214,11 @@ import { ChevronRightIcon } from '@teamblind-chorus/ui/icons';
 - **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.
+- **label** — primary row text. `sys.typo.label.md` (14 / Semibold) / `sys.color.text.default`. 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.
+- **secondary** *(optional)* — stacked meta line below the label inside the identity group (follower count, location). `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.
+- **description** *(optional)* — single-line caption-tone supporting line below the identity group. `sys.typo.label.sm` (12 / Semibold) / `sys.color.text.subtle`. 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](#trailing-text-button)), `<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
@@ -259,7 +237,7 @@ import { ChevronRightIcon } from '@teamblind-chorus/ui/icons';
 | 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`. |
+| inter-row divider          | `1px` `border.default`. 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
 
@@ -267,7 +245,7 @@ No `selected` state. State overlays (hover / pressed / disabled) delegate to the
 
 ## 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.
+Inward single 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