@teamblind-chorus/ui 1.2.0 → 2.0.0

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": {
@@ -152,11 +152,11 @@
         "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.focusInset"
+          "color": "sys.color.border.focused"
         },
         "outerRing": {
           "width": "sys.borderWidth.thin",
-          "color": "sys.color.focus"
+          "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."
@@ -165,27 +165,23 @@
       "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)"
@@ -200,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,17 +176,17 @@ import { List } from '@teamblind-chorus/ui';
 />
 ```
 
-### With an embedded Banner
+## 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 rows lead with fill-type category glyphs (`BriefcaseFillIcon`, `FlagFillIcon`) that the leading slot tones to `onSurfaceVariant`.
+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, FlagFillIcon } from '@teamblind-chorus/ui/icons';
+import { BriefcaseFillIcon, CheckCircleFillIcon, ChevronRightIcon } from '@teamblind-chorus/ui/icons';
 
 <List
   aria-label="Career"
@@ -242,7 +200,7 @@ import { BriefcaseFillIcon, CheckCircleFillIcon, ChevronRightIcon, FlagFillIcon
         <Banner
           appearance="accent"
           neutralBody
-          icon={<CheckCircleFillIcon size={16} style={{ color: 'var(--sys-color-primary)' }} />}
+          icon={<CheckCircleFillIcon size={16} style={{ color: 'var(--sys-color-background-primary)' }} />}
           trailingAction={(
             <Button variant="text" appearance="accent" size="small" trailingIcon={<ChevronRightIcon />}>
               Expert Q&A
@@ -253,11 +211,35 @@ import { BriefcaseFillIcon, CheckCircleFillIcon, ChevronRightIcon, FlagFillIcon
         </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: 'roadmap',
-      label: 'View career roadmap',
-      icon: <FlagFillIcon />,
-      nav: true,
+      value: 'email',
+      label: 'Email',
+      supportingText: 'work@example.com',
+      icon: <InvitationIcon />,
+      trailingIcon: (
+        <Button variant="text" size="small" appearance="accent" onClick={() => {}}>
+          Edit
+        </Button>
+      ),
     },
   ]}
 />
@@ -284,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
@@ -293,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' },
   ]}
 />
 ```

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

@@ -20,7 +20,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,
@@ -28,7 +28,7 @@
     },
     "leading": {
       "required": false,
-      "fallbackOnMissingSrc": "sys.color.surfaceContainerHigh",
+      "fallbackOnMissingSrc": "sys.color.surface.sunken",
       "description": "The leading slot — omitted by default (no reserved leading whitespace), hosting one of two mutually exclusive types. **Image type** (`thumbnail`): a [Thumbnail](../thumbnail/thumbnail.md) at the 40 rung, vertically centred against the label column, with a 12px (`sys.layout.inline.lg`) gap to the text group; `thumbnail` props (`src`, `alt`, `updateDot`, `logoBadge`) forward verbatim, and `fallbackOnMissingSrc` is the dim-tone fill it paints when `src` is empty / fails to load (at scaffold time, agents fill `src` with `/placeholder.png` rather than relying on the fallback). **Icon type** (`icon`): a 24px (`sys.icon.lg`) decorative glyph in `onSurfaceVariant`, vertically centred, with an 8px (`sys.layout.inline.md`) gap to the text group — the category-mark shape for settings / menu rows. The slot enforces the 24 rung regardless of the glyph's own `size`. A row passes `thumbnail` or `icon`, never both.",
       "accepts": [
         "thumbnail",
@@ -117,7 +117,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. The last row already omits its divider via `:not(:last-child)`."
+      "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. The last row already omits its divider via `:not(:last-child)`."
     },
     "nav": {
       "type": "boolean",
@@ -164,18 +164,18 @@
     "labelToCountGap": "sys.layout.inline.sm",
     "labelToCountGapNote": "4px (`sys.layout.inline.sm`) between the label and an inline `count` badge — they tile flush on the primary line as one label+count block, narrower than the 8px trailing gap. Mirrors list/entry's identity-group spacing.",
     "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.",
     "leadingThumbnailSize": 40,
     "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",
     "trailingIconSize": "16 × 16",
-    "trailingIconColor": "sys.color.onSurfaceVariant",
+    "trailingIconColor": "sys.color.text.subtle",
     "navChevronSize": "16 × 16",
-    "navChevronColor": "sys.color.onSurfaceVariant"
+    "navChevronColor": "sys.color.text.subtle"
   },
   "states": {
     "default": {
@@ -203,37 +203,34 @@
         "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.focusInset"
+          "color": "sys.color.border.focused"
         },
         "outerRing": {
           "width": "sys.borderWidth.thin",
-          "color": "sys.color.focus"
+          "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 an independent trailing action (a `trailingIcon` button — favorite / mute / Follow). The small control owns the state; the large row does NOT also read as hovered / pressed. The decorative nav chevron is exempt — it is the row's own drill-in affordance, so hovering it still lights the whole row. 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. The inter-row divider and focus overlay are unaffected (they were never part of the content tone)."
     }
   },
   "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)"
@@ -250,7 +247,7 @@
     "nav chevron as a separate hit target — the drill-in chevron is decorative; the whole row is the click target",
     "leading thumbnail at a size other than the row's intrinsic 40 rung",
     "compact directory rows (selectable 32/48/56 avatar + stacked secondary line + optional toggle) built as a leading-image Standard row — that directory anatomy is [list/entry](./entry.md); Standard's image type is single-density at the 40 rung. (Standard does carry an inline `count` badge next to the label for unread / status counts, but not the avatar-rung directory shape.)",
-    "raw `border:` on the row — list seam is the family's bottom divider via outlineVariant",
+    "raw `border:` on the row — list seam is the family's bottom divider via border.default",
     "embedded `banner` painted with a per-child `margin-block` / `padding-block` wrapper to fake the 8px gap — the text-group↔Banner gap is the row stack's `gap: sys.layout.stack.xs`, and the Banner's horizontal inset is the row's own 16px padding; Banner ships no outer margin",
     "embedded `banner` as a separate `<List>` row beneath the header — the call-out belongs to its row's subject, so it nests inside that row via `item.banner`, not as a sibling row that the divider would fence off"
   ]

package/agents/components/metadata/compact.md

@@ -25,9 +25,7 @@ import { Metadata } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### With role badge
+## Role badge
 
 An object identity item carries `badge` — a single presentational mark rendered after the nickname's link, outside the `<a>`, at the middots' 4px gap. At most one badge rides the nickname, never a stack.
 
@@ -59,9 +57,9 @@ import { Metadata, Badge } from '@teamblind-chorus/ui';
 | Slot          | Token bindings |
 |---------------|----------------|
 | avatar        | [Thumbnail](../thumbnail/thumbnail.md) `size={32}` |
-| meta          | `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, links inherit; underline on hover |
-| timestamp     | `sys.typo.label.sm` / `sys.color.outline` |
-| dot separator | `·` glyph, `color: sys.color.outline`, **`line-height: 1`** so its line-box equals its font-size — never inflates the text line |
+| meta          | `sys.typo.label.sm` / `sys.color.text.subtle`, links inherit; underline on hover |
+| timestamp     | `sys.typo.label.sm` / `sys.color.border.boldest` |
+| dot separator | `·` glyph, `color: sys.color.border.boldest`, **`line-height: 1`** so its line-box equals its font-size — never inflates the text line |
 
 ## States
 

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

@@ -3,7 +3,7 @@
   "name": "Metadata",
   "family": "metadata",
   "subcomponent": "compact",
-  "description": "One-line channel-detail attribution — the slimmed [Standard](standard.md) head that keeps the leading 32-rung [Thumbnail](../thumbnail/thumbnail.md) but drops the primary name line, follow toggle, and subtitle (the info that is unnecessary once the channel context is already established). A leading avatar plus the identity meta-link row, with the posting time relocated to the line's trailing edge: avatar · company name · nickname (bare, no @ prefix, optional single role badge) · timestamp. The identity items keep the standard meta-row grammar (independent `<a>` links, middot separators, badge outside the link); the timestamp is plain text in `sys.color.outline` so the line reads identity-first, time-last. `layoutInset: inline` — atom-shaped, pays no padding of its own; the host row owns the gutter / divider / click target.",
+  "description": "One-line channel-detail attribution — the slimmed [Standard](standard.md) head that keeps the leading 32-rung [Thumbnail](../thumbnail/thumbnail.md) but drops the primary name line, follow toggle, and subtitle (the info that is unnecessary once the channel context is already established). A leading avatar plus the identity meta-link row, with the posting time relocated to the line's trailing edge: avatar · company name · nickname (bare, no @ prefix, optional single role badge) · timestamp. The identity items keep the standard meta-row grammar (independent `<a>` links, middot separators, badge outside the link); the timestamp is plain text in `sys.color.border.boldest` so the line reads identity-first, time-last. `layoutInset: inline` — atom-shaped, pays no padding of its own; the host row owns the gutter / divider / click target.",
   "element": "div",
   "props": {
     "variant": {
@@ -23,7 +23,7 @@
     "timestamp": {
       "type": "string",
       "required": true,
-      "description": "Posting time at the line's trailing edge — plain text (never a link), in `label.sm` / `sys.color.outline` so it recedes behind the identity links. NOT preceded by a middot: the time is separated from the identity cluster by an `inline.md` (8) gap so it reads as a distinct trailing element rather than another identity item (mirrors the Standard head's name↔time treatment). Required: the timestamp is what distinguishes a compact attribution from a bare identity row."
+      "description": "Posting time at the line's trailing edge — plain text (never a link), in `label.sm` / `sys.color.border.boldest` so it recedes behind the identity links. NOT preceded by a middot: the time is separated from the identity cluster by an `inline.md` (8) gap so it reads as a distinct trailing element rather than another identity item (mirrors the Standard head's name↔time treatment). Required: the timestamp is what distinguishes a compact attribution from a bare identity row."
     }
   },
   "slots": {
@@ -47,7 +47,7 @@
     },
     "timestamp": {
       "required": true,
-      "description": "Trailing plain-text posting time after the identity cluster — no leading middot, separated by an `inline.md` (8) gap. `sys.typo.label.sm` / `sys.color.outline` — one tonal step further than the identity links.",
+      "description": "Trailing plain-text posting time after the identity cluster — no leading middot, separated by an `inline.md` (8) gap. `sys.typo.label.sm` / `sys.color.border.boldest` — one tonal step further than the identity links.",
       "accepts": [
         "text"
       ]
@@ -55,10 +55,10 @@
   },
   "sizing": {
     "metaTypo": "sys.typo.label.sm",
-    "metaColor": "sys.color.onSurfaceVariant",
+    "metaColor": "sys.color.text.subtle",
     "timestampTypo": "sys.typo.label.sm",
-    "timestampColor": "sys.color.outline",
-    "dotColor": "sys.color.outline",
+    "timestampColor": "sys.color.border.boldest",
+    "dotColor": "sys.color.border.boldest",
     "dotLineHeight": "1",
     "dotLineHeightNote": "Same family-wide rule as the standard sub: the middot separator inherits the surrounding text's font-size but uses `line-height: 1` so its line-box never exceeds the glyph's font-size — the dot never inflates the single text line.",
     "metaSeparatorInset": "sys.layout.inline.sm"

package/agents/components/metadata/metadata.md

@@ -12,7 +12,7 @@ Three rules hold across every family member.
 
 ### Dot height
 
-Every middot separator inherits the surrounding text's font-size but uses `line-height: 1`, so its line-box never exceeds the glyph's font-size — the U+00B7 glyph's natural vertical extent never inflates the host text line. The dot paints in `sys.color.outline` and is always inline, never a block element.
+Every middot separator inherits the surrounding text's font-size but uses `line-height: 1`, so its line-box never exceeds the glyph's font-size — the U+00B7 glyph's natural vertical extent never inflates the host text line. The dot paints in `sys.color.border.boldest` and is always inline, never a block element.
 
 ### Bare nickname, single badge
 

package/agents/components/metadata/standard.md

@@ -26,11 +26,9 @@ import { Metadata } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
+## Follow action
 
-### With follow action
-
-The inline follow toggle. A middot separates it from the timestamp; the toggle paints in `sys.color.primary` at rest and `sys.color.onSurfaceVariant` when active. The dot's line-box stays inside its font-size so the row's text-line stays tight.
+The inline follow toggle. A middot separates it from the timestamp; the toggle paints in `sys.color.background.primary` at rest and `sys.color.text.subtle` when active. The dot's line-box stays inside its font-size so the row's text-line stays tight.
 
 ```preview
 metadata/standard/follow
@@ -47,7 +45,7 @@ import { Metadata } from '@teamblind-chorus/ui';
 />
 ```
 
-### Sponsored (ad)
+## Sponsored
 
 Feed Ad shape — `subtitle="Sponsored"` paints a plain caption-tone line under the brand name (no link affordance, no meta row). Pair with `trailing` to host the dismiss × button.
 
@@ -69,7 +67,7 @@ import { XIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### With role badge
+## Role badge
 
 A meta item in object form carries `badge` — a single presentational mark rendered after the item's link, outside the `<a>`, at the middots' 4px gap. Canonical fill: a role [Badge](../badge/badge.md) on the trailing nickname. At most one badge rides the nickname, never a stack.
 
@@ -96,8 +94,8 @@ import { Metadata, Badge } from '@teamblind-chorus/ui';
 - **container** — outer flex row. `align-items: center`, `sys.layout.inline.md` (8px) gap between avatar, text column, and trailing slot.
 - **avatar** *(optional)* — leading [Thumbnail](../thumbnail/thumbnail.md) at `size={32}`. Forwards every Thumbnail prop verbatim.
 - **text** — two-line text column. Primary line on top, optional secondary line below. `flex: 1 1 auto`, `min-width: 0` so both lines truncate.
-- **name** — entity name. `<a>` when `nameHref` is set, `<span>` otherwise. `sys.typo.label.sm` / `sys.color.onSurface`. Single line; truncates.
-- **timestamp** *(optional)* — inline timestamp after the name. `sys.typo.label.sm` / `sys.color.outline`.
+- **name** — entity name. `<a>` when `nameHref` is set, `<span>` otherwise. `sys.typo.label.sm` / `sys.color.text.default`. Single line; truncates.
+- **timestamp** *(optional)* — inline timestamp after the name. `sys.typo.label.sm` / `sys.color.border.boldest`.
 - **followAction** *(optional)* — bare-text follow toggle at the primary line's trailing edge. Preceded by a middot.
 - **subtitle** *(optional, ad)* — plain caption-tone secondary line. Mutually exclusive with `meta`.
 - **meta** *(optional, post)* — secondary line meta-link row. Each item is its own `<a>`; siblings separate by middot. The last item is canonically the user's nickname, displayed bare (no @ prefix). An object item may carry `badge` — a single presentational mark node rendered after the link, outside the `<a>` (canonical fill: [badge/role](../badge/badge.md) on the nickname — at most one badge rides the nickname, never a stack).
@@ -109,12 +107,12 @@ import { Metadata, Badge } from '@teamblind-chorus/ui';
 |---------------|----------------|
 | container     | Flex row, `sys.layout.inline.md` (8) gap, `align-items: center` |
 | avatar        | [Thumbnail](../thumbnail/thumbnail.md) `size={32}` |
-| name          | `sys.typo.label.sm` / Semibold / `sys.color.onSurface`, single-line ellipsis |
-| timestamp     | `sys.typo.label.sm` / `sys.color.outline` |
-| dot separator | `·` glyph, `color: sys.color.outline`, **`line-height: 1`** so its line-box equals its font-size — never inflates the text line |
-| follow        | `sys.typo.label.sm` / Semibold / `sys.color.primary` (active → `sys.color.onSurfaceVariant`) |
-| subtitle      | `sys.typo.label.sm` / `sys.color.onSurfaceVariant` |
-| meta          | `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, links inherit; underline on hover |
+| name          | `sys.typo.label.sm` / Semibold / `sys.color.text.default`, single-line ellipsis |
+| timestamp     | `sys.typo.label.sm` / `sys.color.border.boldest` |
+| dot separator | `·` glyph, `color: sys.color.border.boldest`, **`line-height: 1`** so its line-box equals its font-size — never inflates the text line |
+| follow        | `sys.typo.label.sm` / Semibold / `sys.color.background.primary` (active → `sys.color.text.subtle`) |
+| subtitle      | `sys.typo.label.sm` / `sys.color.text.subtle` |
+| meta          | `sys.typo.label.sm` / `sys.color.text.subtle`, links inherit; underline on hover |
 
 ## States