@teamblind-chorus/ui 1.1.0 → 2.0.0

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

@@ -3,7 +3,7 @@
   "name": "List",
   "family": "list",
   "subcomponent": "standard",
-  "description": "The default List variant — display or navigation rows over the shared List anatomy. The whole row is the click target; no selection model. A row is text-only by default (no leading slot); it opts into a **leading image** (the image type) by passing a `thumbnail`, which renders a 40px [Thumbnail](../thumbnail/thumbnail.md) at the leading edge with a 12px (`sys.layout.inline.lg`) gap to the text group, or into a **leading icon** (the icon type) by passing an `icon`, which renders a 24px (`sys.icon.lg`) glyph with an 8px (`sys.layout.inline.md`) gap. A row opts into a trailing drill-in chevron with `nav: true` (the drill-in case — the row routes the user to another surface); a per-item `trailingIcon` overrides the auto chevron. A row opts into an inline **count badge** to the right of the label via `count` — separated from the label by `sys.layout.inline.sm` (4), the unread / status-count case — and it composes with the chevron / trailing slot on the same row. For the richer directory shape (selectable 32/48/56 avatar + stacked `secondary` identity line) reach for [list/entry](./entry.md); Standard's leading image is single-density at the 40 rung.",
+  "description": "The default List variant — display or navigation rows over the shared List anatomy. The whole row is the click target; no selection model. A row is text-only by default (no leading slot); it opts into a **leading image** (the image type) by passing a `thumbnail`, which renders a 40px [Thumbnail](../thumbnail/thumbnail.md) at the leading edge with a 12px (`sys.layout.inline.lg`) gap to the text group, or into a **leading icon** (the icon type) by passing an `icon`, which renders a 24px (`sys.icon.lg`) glyph with an 8px (`sys.layout.inline.md`) gap. A row opts into a trailing drill-in chevron with `nav: true` (the drill-in case — the row routes the user to another surface); a per-item `trailingIcon` overrides the auto chevron. A row opts into an inline **count badge** to the right of the label via `count` — separated from the label by `sys.layout.inline.sm` (4), the unread / status-count case — and it composes with the chevron / trailing slot on the same row. For the richer directory shape (selectable 32/48/56 avatar + stacked `secondary` identity line) reach for [list/entry](./entry.md); Standard's leading image is single-density at the 40 rung. A row opts into an embedded **`banner`** — a [Banner](../banner/banner.md) painted below the row's text group at the row's full content width, `sys.layout.stack.xs` (8) below it — for an in-row call-out tied to that row's subject.",
   "element": "ul",
   "props": {
     "embedded": {
@@ -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",
@@ -67,6 +67,13 @@
     "navChevron": {
       "required": false,
       "description": "Auto-rendered 16px right-pointing chevron at the trailing edge, painted when the row sets `nav: true` — the drill-in affordance signalling the row routes to another surface. `onSurfaceVariant` tone, decorative (`aria-hidden`); never a separate hit target — the whole row is the click target. A per-item `trailingIcon` replaces it."
+    },
+    "banner": {
+      "required": false,
+      "description": "Optional embedded [Banner](../banner/banner.md) painted **below** the row's text group, separated by `sys.layout.stack.xs` (8). The row flips from a single horizontal line to a vertical stack — the normal leading + label + trailing line on top, the Banner spanning the row's **full content width** (aligned to the same 16px inline inset as the label above it) underneath. Reach for it when a list 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 own fill / radius / padding and its full prop surface (use `appearance=\"accent\"` + `neutralBody` for the quiet-tint call-out shape, a leading `icon`, a `trailingAction` Text Button). It is a **nested-action region**: clicks inside it stop propagating before they reach the row's `onClick`, and the row's hover / pressed overlay is suppressed while the pointer sits on it — same contract as `trailingIcon`.",
+      "accepts": [
+        "banner"
+      ]
     }
   },
   "rowProps": {
@@ -102,10 +109,15 @@
       "optional": true,
       "description": "Trailing-edge node. Wrapped in a slot that stops click propagation so the slot is its own hit target separate from the row's `onClick`."
     },
+    "banner": {
+      "type": "node",
+      "optional": true,
+      "description": "Embedded `<Banner>` rendered below the row's text group at the row's full content width, `sys.layout.stack.xs` (8) below it. A nested-action region: its own controls (e.g. a `trailingAction` Text Button) never commit the row, and the row's hover / pressed overlay is suppressed over it. Canonical fill: `<Banner appearance=\"accent\" neutralBody icon={…} trailingAction={…}>…</Banner>`."
+    },
     "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",
@@ -147,21 +159,23 @@
     "leadingIconGapNote": "8px (`sys.layout.inline.md`) between a leading 24px (`sys.icon.lg`) icon (the icon type) and the text group — the icon-leading rung of the family's role-based row spacing (the base leading gap), narrower than the 12px image rung. Applies only to rows that carry an `icon`.",
     "trailingActionGap": "sys.layout.inline.md",
     "trailingActionGapNote": "Fixed 8px (`sys.layout.inline.md`) between the text group and a trailing icon / nav chevron — the family-wide trailing gap, identical across every List variant.",
+    "bannerGap": "sys.layout.stack.xs",
+    "bannerGapNote": "8px (`sys.layout.stack.xs`) vertical gap between the row's text group and an embedded `banner` below it. The Banner spans the row's full content width (the 16px inline inset is the row's own padding, not paid again by the Banner — see banner.md § Layout inset).",
     "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": {
@@ -179,28 +193,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 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)"
@@ -217,6 +247,8 @@
     "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
 

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

@@ -24,7 +24,7 @@
     "timestamp": {
       "type": "string",
       "optional": true,
-      "description": "Inline timestamp painted after the name on the primary line, in `label.sm` / `sys.color.outline` — one tonal step further than the name. Reach for it on Feed Post; omit on Feed Ad."
+      "description": "Inline timestamp painted after the name on the primary line, in `label.sm` / `sys.color.border.boldest` — one tonal step further than the name. Reach for it on Feed Post; omit on Feed Ad."
     },
     "followAction": {
       "type": "boolean",
@@ -78,26 +78,26 @@
     },
     "name": {
       "required": true,
-      "description": "Entity name. `sys.typo.label.sm` (12 / Semibold) / `sys.color.onSurface`. Renders as `<a>` when `nameHref` is set, `<span>` otherwise. Single line; truncates with ellipsis.",
+      "description": "Entity name. `sys.typo.label.sm` (12 / Semibold) / `sys.color.text.default`. Renders as `<a>` when `nameHref` is set, `<span>` otherwise. Single line; truncates with ellipsis.",
       "accepts": [
         "text"
       ]
     },
     "timestamp": {
       "required": false,
-      "description": "Inline timestamp after the name. `sys.typo.label.sm` (12 / Semibold) / `sys.color.outline` — one tonal step further than the name so the timestamp recedes.",
+      "description": "Inline timestamp after the name. `sys.typo.label.sm` (12 / Semibold) / `sys.color.border.boldest` — one tonal step further than the name so the timestamp recedes.",
       "accepts": [
         "text"
       ]
     },
     "followAction": {
       "required": false,
-      "description": "Inline follow toggle at the primary line's trailing edge. Bare text affordance (no chrome) — `sys.color.primary` at rest, `sys.color.onSurfaceVariant` when active. A `·` separator precedes it.",
+      "description": "Inline follow toggle at the primary line's trailing edge. Bare text affordance (no chrome) — `sys.color.background.primary` at rest, `sys.color.text.subtle` when active. A `·` separator precedes it.",
       "intrinsic": true
     },
     "subtitle": {
       "required": false,
-      "description": "Secondary line plain text. `sys.typo.label.sm` / `sys.color.onSurfaceVariant`. Mutually exclusive with `meta`.",
+      "description": "Secondary line plain text. `sys.typo.label.sm` / `sys.color.text.subtle`. Mutually exclusive with `meta`.",
       "accepts": [
         "text"
       ]
@@ -121,14 +121,14 @@
     "containerAlign": "center",
     "avatarSize": 32,
     "nameTypo": "sys.typo.label.sm",
-    "nameColor": "sys.color.onSurface",
+    "nameColor": "sys.color.text.default",
     "timestampTypo": "sys.typo.label.sm",
-    "timestampColor": "sys.color.outline",
+    "timestampColor": "sys.color.border.boldest",
     "subtitleTypo": "sys.typo.label.sm",
-    "subtitleColor": "sys.color.onSurfaceVariant",
+    "subtitleColor": "sys.color.text.subtle",
     "metaTypo": "sys.typo.label.sm",
-    "metaColor": "sys.color.onSurfaceVariant",
-    "dotColor": "sys.color.outline",
+    "metaColor": "sys.color.text.subtle",
+    "dotColor": "sys.color.border.boldest",
     "dotLineHeight": "1",
     "dotLineHeightNote": "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 — keeps the row's text-line tight even when the inherited line-height would otherwise allow extra vertical space around the middot.",
     "primaryRowGap": "sys.layout.inline.md",

package/agents/components/nav-card/nav-card.md

@@ -20,9 +20,7 @@ import { NavCard } from '@teamblind-chorus/ui';
 <NavCard label="Cell label here" href="#" />
 ```
 
-## Use cases
-
-### Nav (with trailing chevron)
+## Nav
 
 `variant="nav"` auto-renders the right-pointing chevron — the explicit drill-in form. Reach for it when the card routes into another surface (settings detail, picker, sub-flow).
 
@@ -34,7 +32,7 @@ import { NavCard } from '@teamblind-chorus/ui';
 <NavCard variant="nav" label="Cell label here" href="#" />
 ```
 
-### With supporting text
+## Supporting text
 
 Two-line variant — primary label on top, supporting metadata below at `onSurfaceVariant`. Works with either variant; pair with `nav` when the drill-in is metadata-bearing.
 
@@ -51,7 +49,7 @@ import { NavCard } from '@teamblind-chorus/ui';
 />
 ```
 
-### With leading icon
+## Leading icon
 
 A leading 16 × 16 glyph at the inline padding edge. The icon vertically centres on the row's parent block — same `align-items: center` axis as the label column and trailing slot, so the glyph sits on the same midline as the label (one-line) or label + supportingText block (two-line).
 
@@ -69,7 +67,7 @@ import { BellIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### With leading thumbnail
+## Leading thumbnail
 
 A leading 32-rung [Thumbnail](../thumbnail/thumbnail.md) — used when the drill target is an entity (channel, person, brand) rather than a chrome action. The thumbnail block-centres on the row's vertical midline, same as an icon leading.
 
@@ -87,24 +85,7 @@ import { NavCard, Thumbnail } from '@teamblind-chorus/ui';
 />
 ```
 
-### Group
-
-Multiple NavCards stacked vertically as a `NavCardGroup` — each card stays its own outlined affordance, separated by `sys.layout.stack.xs` (8px) gap. Use when several drill-in cards share a section but should read as discrete cards (vs a List drill-in rail — `text` rows with `nav: true` — where rows tile flush with hairline dividers).
-
-```preview
-nav-card/group
----
-import { NavCard, NavCardGroup } from '@teamblind-chorus/ui';
-import { BellIcon, BookmarkIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
-
-<NavCardGroup aria-label="Account">
-  <NavCard variant="nav" label="Profile" supportingText="Display name, avatar, bio" leading={<ProfileIcon size={16} />} href="#" />
-  <NavCard variant="nav" label="Saved posts" supportingText="47 posts across 9 channels" leading={<BookmarkIcon size={16} />} href="#" />
-  <NavCard variant="nav" label="Notifications" leading={<BellIcon size={16} />} href="#" />
-</NavCardGroup>
-```
-
-### Surface (opaque tier on a non-`surface` host)
+## Surface
 
 `appearance="surface"` paints the card with its own `sys.color.surface` fill so it reads as an opaque tier. Reach for it when the card sits on a transparent / non-`surface` host (coloured hero, tonal band, BottomSheet content slot) and the default transparent fill would let the card blend in.
 
@@ -129,9 +110,26 @@ import { BellIcon, BookmarkIcon, ProfileIcon } from '@teamblind-chorus/ui/icons'
 </div>
 ```
 
+## Group
+
+Multiple NavCards stacked vertically as a `NavCardGroup` — each card stays its own outlined affordance, separated by `sys.layout.stack.xs` (8px) gap. Use when several drill-in cards share a section but should read as discrete cards (vs a List drill-in rail — `text` rows with `nav: true` — where rows tile flush with hairline dividers).
+
+```preview
+nav-card/group
+---
+import { NavCard, NavCardGroup } from '@teamblind-chorus/ui';
+import { BellIcon, BookmarkIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+
+<NavCardGroup aria-label="Account">
+  <NavCard variant="nav" label="Profile" supportingText="Display name, avatar, bio" leading={<ProfileIcon size={16} />} href="#" />
+  <NavCard variant="nav" label="Saved posts" supportingText="47 posts across 9 channels" leading={<BookmarkIcon size={16} />} href="#" />
+  <NavCard variant="nav" label="Notifications" leading={<BellIcon size={16} />} href="#" />
+</NavCardGroup>
+```
+
 ## Slots
 
-- **container** — outlined rounded box. `surface` fill, `radius.md` corners, hairline `outlineVariant` stroke painted as inset box-shadow (never `border:`).
+- **container** — outlined rounded box. `surface` fill, `radius.md` corners, hairline `border.default` stroke painted as inset box-shadow (never `border:`).
 - **leading** *(optional)* — 16px icon (`currentColor`) or 32-rung [Thumbnail](../thumbnail/thumbnail.md). Block-centred on the row's vertical midline — same contract for icon and thumbnail. Omitted by default; label flushes to the inline padding edge.
 - **labelCol** — vertical column holding label and (optional) supportingText. `min-width: 0` so both lines truncate.
 - **label** — primary card text. 14px / Regular / `onSurface`. Single line; truncates.
@@ -142,7 +140,7 @@ import { BellIcon, BookmarkIcon, ProfileIcon } from '@teamblind-chorus/ui/icons'
 
 | Slot           | Token bindings |
 |----------------|----------------|
-| container      | `surface` fill, `radius.md` corners, hairline `outlineVariant` inset box-shadow, `48px` min-height, `8px` block / `16px` inline padding |
+| container      | `surface` fill, `radius.md` corners, hairline `border.default` inset box-shadow, `48px` min-height, `8px` block / `16px` inline padding |
 | leading        | 16 × 16 (`sys.icon.md`) glyph in `currentColor` or 32 × 32 [Thumbnail](../thumbnail/thumbnail.md). Block-centred on the row's vertical midline (same contract for icon and thumbnail). `sys.layout.inline.md` (8px) gap to label column |
 | labelCol       | Flex column, `min-width: 0`, no inter-line margin (line-height carries the rhythm) |
 | label          | `sys.typo.body.sm` (14 / Regular) / `onSurface` |
@@ -172,7 +170,7 @@ A single rung. Min-height 48 (touch-target floor); consumers cannot shrink or gr
 
 ## Focus indicator
 
-Outward 3-layer ring painted on the container's outer edge via an `::after` overlay (rest stroke sits on `::before`). Trigger: `:focus-visible`. NavCard sits as its own bounded surface with margin to siblings, so an outward ring reads cleanly — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+Outward single ring painted on the container's outer edge via an `::after` overlay (rest stroke sits on `::before`). Trigger: `:focus-visible`. NavCard sits as its own bounded surface with margin to siblings, so an outward ring reads cleanly — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
 
 ## Behavior
 

package/agents/components/nav-card/nav-card.spec.json

@@ -2,7 +2,7 @@
   "$schema": "../../spec.schema.json",
   "name": "NavCard",
   "family": "nav-card",
-  "description": "Outlined, rounded single-row card. Single label (optional supporting line) over a `surface`-toned box with a hairline `outlineVariant` inset-shadow stroke and `radius.md` corners. Two variants select the trailing affordance: `default` ships no trailing icon (bare labelled card — settings entry, scope tile, informational drill-target), `nav` auto-renders the right-pointing chevron for explicit drill-in semantics. Whole card is the click target — keyboard focus, hover overlay, and tap commit all sit on the card. Reach for it when one row needs to read as its own discrete affordance rather than as one entry in a [List](../list/list.md) drill-in stack (`text` rows with `nav: true`).",
+  "description": "Outlined, rounded single-row card. Single label (optional supporting line) over a `surface`-toned box with a hairline `border.default` inset-shadow stroke and `radius.md` corners. Two variants select the trailing affordance: `default` ships no trailing icon (bare labelled card — settings entry, scope tile, informational drill-target), `nav` auto-renders the right-pointing chevron for explicit drill-in semantics. Whole card is the click target — keyboard focus, hover overlay, and tap commit all sit on the card. Reach for it when one row needs to read as its own discrete affordance rather than as one entry in a [List](../list/list.md) drill-in stack (`text` rows with `nav: true`).",
   "element": "button",
   "props": {
     "variant": {
@@ -35,7 +35,7 @@
       "type": "enum",
       "values": ["default", "surface"],
       "default": "default",
-      "description": "Container fill. `default` is transparent — the card's identity is the outlined chrome (hairline + radius + label + chevron) and the host surface tone reads through. `surface` paints `sys.color.surface` so the card reads as its own opaque tier; reach for it when the card sits on a transparent / non-`surface` host (between bare-surface sections, on a tonal band the card needs to break out of)."
+      "description": "Container fill. `default` is transparent — the card's identity is the outlined chrome (hairline + radius + label + chevron) and the host surface tone reads through. `surface` paints `sys.color.surface.default` so the card reads as its own opaque tier; reach for it when the card sits on a transparent / non-`surface` host (between bare-surface sections, on a tonal band the card needs to break out of)."
     },
     "href": {
       "type": "string",
@@ -60,7 +60,7 @@
   "slots": {
     "container": {
       "required": true,
-      "description": "Outlined rounded box. Transparent fill by default (host tone reads through) — `surface` fill via `appearance=\"surface\"`. `radius.md` corners, hairline `outlineVariant` stroke painted as inset box-shadow (never `border:`). Whole container is the interactive target.",
+      "description": "Outlined rounded box. Transparent fill by default (host tone reads through) — `surface` fill via `appearance=\"surface\"`. `radius.md` corners, hairline `border.default` stroke painted as inset box-shadow (never `border:`). Whole container is the interactive target.",
       "intrinsic": true
     },
     "leading": {
@@ -95,17 +95,17 @@
     "paddingBlock": "sys.layout.container.xs",
     "paddingInline": "sys.layout.container.md",
     "outlineWidth": "sys.borderWidth.hairline",
-    "outlineColor": "sys.color.outlineVariant",
+    "outlineColor": "sys.color.border.default",
     "leadingGap": "sys.layout.inline.md",
     "trailingGap": "sys.layout.inline.md",
     "leadingIconSize": "sys.icon.md",
     "labelTypo": "sys.typo.body.sm",
-    "labelColor": "sys.color.onSurface",
+    "labelColor": "sys.color.text.default",
     "supportingTypo": "sys.typo.label.sm",
-    "supportingColor": "sys.color.onSurfaceVariant",
+    "supportingColor": "sys.color.text.subtle",
     "supportingOffset": "0",
     "trailingIconSize": "sys.icon.md",
-    "trailingIconColor": "sys.color.onSurfaceVariant",
+    "trailingIconColor": "sys.color.text.subtle",
     "groupGap": "sys.layout.stack.xs"
   },
   "appearances": {
@@ -114,7 +114,7 @@
       "note": "No fill — the host surface tone reads through. The canonical NavCard: its identity is the outlined chrome (hairline + radius + label + chevron), not a fill. Hover / pressed paint as label-tone overlays mixed on the transparent base so the host tone keeps reading through underneath the state paint."
     },
     "surface": {
-      "background": "sys.color.surface",
+      "background": "sys.color.surface.default",
       "note": "Opaque `surface` fill. Reach for it when the card sits on a transparent / non-`surface` host (a `surfaceContainerLow` tonal band, a coloured hero, a BottomSheet's content slot) and should read as its own opaque tier rather than blending into the host. Outline, label, chevron, and state overlays are unchanged."
     }
   },
@@ -126,21 +126,30 @@
     "pressed": {
       "overlay": { "color": "label", "opacity": "sys.state.pressed" }
     },
+    "focused": {
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, 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 outward ring on the card's outer edge, 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 card 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): card text to text.disabled, icons to icon.disabled. Border stays border.default."
     }
   },
   "focusIndicator": {
-    "description": "Keyboard-focus visual painted as a three-layer ring on the card's outer edge. Composes over whichever lifecycle state the card is in.",
+    "description": "Keyboard-focus visual painted as a single ring on the card's outer edge. Composes over whichever lifecycle state the card is in.",
     "composition": "outward",
     "compositionReason": "NavCard sits as its own bounded surface with margin to siblings; an outward ring reads cleanly without colliding with a neighbouring row's stroke.",
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset",
-      "implementation": "outset box-shadow on the container's `::after` overlay; the rest stroke stays painted on `::before` so the two layers don't fight."
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
+      "implementation": "outset box-shadow on the container's `::after` overlay; the rest stroke stays painted on `::before` so the rest stroke and focus ring don't fight."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },

package/agents/components/nav-list/nav-list.md

@@ -33,9 +33,7 @@ import { NavList } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### With header action
+## Header action
 
 Extends the header with a trailing `accent` Text Button when the screen has a broader index page or "Manage" route.
 
@@ -48,11 +46,7 @@ import { NavList } from '@teamblind-chorus/ui';
   label="Settings"
   headerAction={{ label: 'Manage', href: '/settings/manage' }}
   items={[
-    { value: 'account',      label: 'Account',       href: '/settings/account' },
-    { value: 'notifications',label: 'Notifications', href: '/settings/notifications' },
-    { value: 'privacy',      label: 'Privacy',       href: '/settings/privacy' },
-    { value: 'appearance',   label: 'Appearance',    href: '/settings/appearance' },
-    { value: 'language',     label: 'Language',      href: '/settings/language' },
+    { value: 'account', label: 'Account', href: '/settings/account' },
   ]}
 />
 ```

package/agents/components/nav-list/nav-list.spec.json

@@ -55,17 +55,17 @@
     }
   },
   "sizing": {
-    "containerFill": "sys.color.surface",
+    "containerFill": "sys.color.surface.default",
     "containerPaddingBlock": "sys.layout.container.lg",
     "containerPaddingInline": "sys.layout.container.md",
     "headerToListGap": "sys.layout.stack.md",
     "labelTypo": "sys.typo.heading.md",
-    "labelColor": "sys.color.onSurface",
+    "labelColor": "sys.color.text.default",
     "headerActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' — link-affordance accent rule.",
     "rowComposition": "list/entry label-only row (no thumbnail) — label.md primary, optional label.sm description line, family-default min-height (ref.space.600 = 48), leading column collapsed (0 leading-to-text gap), trailing slot filled with a default Icon Button (variant='icon', size='medium', icon=<ChevronRightIcon />).",
     "rowInlinePaddingNote": "Each row keeps the list/entry native sys.layout.container.md inline padding (the tap target reaches the surface edge) and adds margin-inline: calc(-1 * sys.layout.container.md) so the visible label lines up with the section's content rail (aligned with the header label at 16 from the surface).",
     "dividerWidth": "sys.borderWidth.hairline",
-    "dividerColor": "sys.color.outlineVariant",
+    "dividerColor": "sys.color.border.default",
     "dividerInset": "list/entry default — 16 / 16 inset from both row edges. Label-only rows always take the default inset regardless of `size` (no avatar column to anchor against)."
   },
   "rowProps": {