@teamblind-chorus/ui 1.2.0 → 2.0.0

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."
     }
   },
@@ -130,26 +130,26 @@
       "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.focusInset" },
-        "outerRing": { "width": "sys.borderWidth.thin", "color": "sys.color.focus" }
+        "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 three-layer 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."
+      "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": {

package/agents/components/navigation-bar/main.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/navigation-bar/main.md`](../../../i18n/ko/schema/components/navigation-bar/main.md)
 
-The landing-screen top bar — anchored to a tab root (feed, inbox, profile). A leading menu glyph plus left-aligned page name sit at the start; **up to four** trailing icon actions (conventionally search, chat, profile) sit at the end. Title carries the system's largest page-level rung (`typo.heading.lg`, 24/Semibold). The same row also serves a **drill-in (content-detail) screen** — pass `onBack` instead of `onMenuClick` and the leading glyph swaps to a back chevron, with the trailing cluster carrying up to four actions (see [Use cases](#use-cases)).
+The landing-screen top bar — anchored to a tab root (feed, inbox, profile). A leading menu glyph plus left-aligned page name sit at the start; **up to four** trailing icon actions (conventionally search, chat, profile) sit at the end. Title carries the system's largest page-level rung (`typo.heading.lg`, 24/Semibold). The same row also serves a **drill-in (content-detail) screen** — pass `onBack` instead of `onMenuClick` and the leading glyph swaps to a back chevron, with the trailing cluster carrying up to four actions (see [Drill-in](#drill-in)).
 
 **Reach for this when** the screen is a tab root and needs the menu drawer plus a small set of global affordances, **or** when it's a content-detail drill-in (a post / article reached from a feed) needing back navigation plus a share-and-save cluster. **Skip when** you need a centred title with a single action (use [Sub](./sub.md)) or are on a dedicated search page (use [Search](./search.md)).
 
@@ -36,9 +36,7 @@ import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-## Use cases
-
-### With a text title in place of the logotype
+## Text title
 
 Names the screen in words. Plain text at `typo.heading.lg` (24/Semibold) `onSurface`; same 24-tall rhythm as the logotype, ellipsis on narrow.
 
@@ -60,7 +58,7 @@ import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### With one trailing action
+## Single action
 
 Single trailing affordance — e.g. search on an Inbox screen.
 
@@ -79,7 +77,7 @@ import { SearchIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### Drill-in detail screen (back chevron)
+## Drill-in
 
 A content-detail screen reached from a feed / list (a post, an article, a saved item). Pass `onBack` — the leading glyph becomes a back chevron — and the trailing cluster carries up to four actions (share / notify / bookmark / more). Same row, same 56-tall geometry; only the entry point differs.
 
@@ -108,7 +106,7 @@ import { ShareIcon, BellOffIcon, BookmarkIcon, EllipsisHorizontalIcon } from '@t
 />
 ```
 
-### Drill-in with a text title and a smaller cluster
+## Drill-in text title
 
 Names the source — the channel or author the post belongs to. The cluster is `1..4` actions; drop to just the essentials (share + more) when the screen has fewer affordances.
 
@@ -129,7 +127,7 @@ import { ShareIcon, EllipsisHorizontalIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### Truncation (safety net)
+## Truncation
 
 Long page name truncates with ellipsis. Author concise titles (*Home*, *Inbox*) so the bar never resorts to ellipsis.
 
@@ -162,9 +160,9 @@ import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
 | Slot                  | Container          | Color                                   |
 |-----------------------|--------------------|------------------------------------------|
 | **Bar container**     | `sys.color.surface` fill, 8px block / 16px inline padding, no border, no shadow at rest. | — |
-| **Leading icon**      | Transparent capsule, 24px glyph centred. | `sys.color.onSurface` |
-| **Title**             | Brand logotype `<img>` at 24px tall (width auto) by default; plain-text fallback at `heading.lg`. Not interactive. | `sys.color.onSurface` (text fallback) |
-| **Trailing icon(s)**  | Transparent capsule, 24px glyph centred. Capsules sit flush, no inter-icon gap. | `sys.color.onSurface` |
+| **Leading icon**      | Transparent capsule, 24px glyph centred. | `sys.color.text.default` |
+| **Title**             | Brand logotype `<img>` at 24px tall (width auto) by default; plain-text fallback at `heading.lg`. Not interactive. | `sys.color.text.default` (text fallback) |
+| **Trailing icon(s)**  | Transparent capsule, 24px glyph centred. Capsules sit flush, no inter-icon gap. | `sys.color.text.default` |
 
 ## Sizes
 

package/agents/components/navigation-bar/main.spec.json

@@ -80,13 +80,13 @@
     "trailingIconSize": "sys.icon.lg"
   },
   "appearance": {
-    "containerFill": "sys.color.surface",
-    "leadingIconColor": "sys.color.onSurface",
-    "titleColor": "sys.color.onSurface",
-    "trailingIconColor": "sys.color.onSurface"
+    "containerFill": "sys.color.surface.default",
+    "leadingIconColor": "sys.color.icon.default",
+    "titleColor": "sys.color.text.default",
+    "trailingIconColor": "sys.color.icon.default"
   },
   "states": {
-    "note": "Bar itself has no interactive state. Icon slots carry the standard Icon Button state recipe — default / hovered (sys.state.hover overlay) / pressed (sys.state.pressed overlay) / disabled / focused (three-layer focus ring). Title carries no states."
+    "note": "Bar itself has no interactive state. Icon slots carry the standard Icon Button state recipe — default / hovered (sys.state.hover overlay) / pressed (sys.state.pressed overlay) / disabled / focused (single focus ring). Title carries no states."
   },
   "focusIndicator": {
     "description": "The bar itself isn't a focus target. Its action slots (leading menu, trailing icons) inherit each control's own focus composition — Icon Button → Outward — so the ring belongs to whichever capsule the keyboard lands on. See the contained sub-components for the visual contract.",
@@ -100,7 +100,7 @@
     "trailingIconCeiling": "Three is the conventional ceiling on a tab root; the drill-in (content-detail) action cluster uses up to four (share / notify / bookmark / more). A fifth belongs in the `more` (•••) overflow — the component slices to four."
   },
   "forbidden": [
-    "brand color on the title / wordmark — header chrome stays on sys.color.surface; the wordmark paints sys.color.onSurface",
+    "brand color on the title / wordmark — header chrome stays on sys.color.surface.default; the wordmark paints sys.color.text.default",
     "more than four trailing actions — the action cluster caps at four; a fifth belongs in the `more` overflow",
     "leading glyph other than the menu (tab root) or back chevron (drill-in, via onBack) — never an arbitrary custom glyph",
     "centred title — the Main title is left-aligned next to the leading glyph (a centred title is the `sub` variant)",

package/agents/components/navigation-bar/search.md

@@ -20,9 +20,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 <NavigationBar variant="search" placeholder="Search by keyword" onBack={() => {}} />
 ```
 
-## Use cases
-
-### With value (clear visible)
+## Value
 
 A non-empty value swaps placeholder for `onSurface` text and reveals the trailing clear (*×*) at the medium 32 × 32 capsule — smaller than the leading back-arrow so it never out-shouts the input. Clicking clear wipes the value, returns focus, and the trailing column collapses; the input's leading edge stays pixel-stable.
 
@@ -42,7 +40,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 ## Slots
 
 - **leading** *(required)* — 24px back-arrow as the canonical [Icon Button](../button/icon.md) capsule (40 × 40 transparent, 24px glyph).
-- **input** *(required)* — single-line *bare* text input filling the leftover middle column. Bare means no border, no background, no inset stroke — not a [Search](../form-field/search.md) field. Value in `sys.color.onSurface`, placeholder in `sys.color.outline` (`typo.body.md`, 16/Regular). Caret follows the [system caret rule](../../DESIGN.md#caret).
+- **input** *(required)* — single-line *bare* text input filling the leftover middle column. Bare means no border, no background, no inset stroke — not a [Search](../form-field/search.md) field. Value in `sys.color.text.default`, placeholder in `sys.color.border.boldest` (`typo.body.md`, 16/Regular). Caret follows the [system caret rule](../../DESIGN.md#caret).
 - **trailing** *(conditional)* — clear (*×*) [Icon Button](../button/icon.md) hosting `XCircleFillIcon`. Always Icon Button's `medium` size (32 × 32 capsule, 16px glyph) so it never over-claims weight against the bare input. Rendered only when value is non-empty; wipes value and returns focus.
 
 ## Anatomy
@@ -51,10 +49,10 @@ Three-column grid (leading / input / trailing) — side columns size to content,
 
 | Slot                  | Container                                                                               | Color                                                                          |
 |-----------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
-| **Bar container**     | `sys.color.surface` fill, 8px block / 16px inline padding, no shadow at rest, **1px bottom divider in `sys.color.outlineVariant`** painted as inset `box-shadow`. | —                                                                              |
-| **Leading**           | Transparent Icon Button capsule (8 padding around 24px glyph).                           | `sys.color.onSurface`                                                          |
-| **Input**             | Bare text — no border, no background, no inset stroke.                                   | Value: `sys.color.onSurface`. Placeholder: `sys.color.outline`. Caret: `sys.color.primary`. |
-| **Trailing (clear)**  | Transparent Icon Button **medium** capsule (32 × 32, 16px glyph).                        | `sys.color.onSurface`                                                          |
+| **Bar container**     | `sys.color.surface` fill, 8px block / 16px inline padding, no shadow at rest, **1px bottom divider in `sys.color.border.default`** painted as inset `box-shadow`. | —                                                                              |
+| **Leading**           | Transparent Icon Button capsule (8 padding around 24px glyph).                           | `sys.color.text.default`                                                          |
+| **Input**             | Bare text — no border, no background, no inset stroke.                                   | Value: `sys.color.text.default`. Placeholder: `sys.color.border.boldest`. Caret: `sys.color.background.primary`. |
+| **Trailing (clear)**  | Transparent Icon Button **medium** capsule (32 × 32, 16px glyph).                        | `sys.color.text.default`                                                          |
 
 The 1px bottom divider (unique to Search) keeps the bare input from bleeding into the results list below; painted as inset `box-shadow` so it never participates in layout.
 

package/agents/components/navigation-bar/search.spec.json

@@ -65,7 +65,7 @@
     },
     "input": {
       "required": true,
-      "description": "Single-line bare text input that fills the leftover middle column. Bare = no `border`, no `background`, no inset stroke — it is *not* a [Search bar](../form-field/search.md) field. Renders the value in `sys.color.onSurface` when present; renders the placeholder in `sys.color.outline` when empty. `body.md` (16/Regular). The bar carries the visible search affordance via the placeholder and the page context; the field itself has no chrome of its own.",
+      "description": "Single-line bare text input that fills the leftover middle column. Bare = no `border`, no `background`, no inset stroke — it is *not* a [Search bar](../form-field/search.md) field. Renders the value in `sys.color.text.default` when present; renders the placeholder in `sys.color.border.boldest` when empty. `body.md` (16/Regular). The bar carries the visible search affordance via the placeholder and the page context; the field itself has no chrome of its own.",
       "accepts": [
         "text"
       ]
@@ -91,20 +91,20 @@
     "trailingIconSize": "sys.icon.md"
   },
   "appearance": {
-    "containerFill": "sys.color.surface",
-    "containerBottomDivider": "sys.color.outlineVariant",
-    "leadingColor": "sys.color.onSurface",
-    "inputText": "sys.color.onSurface",
-    "inputPlaceholder": "sys.color.outline",
-    "inputCaret": "sys.color.onSurface",
-    "trailingColor": "sys.color.onSurface"
+    "containerFill": "sys.color.surface.default",
+    "containerBottomDivider": "sys.color.border.default",
+    "leadingColor": "sys.color.text.default",
+    "inputText": "sys.color.text.default",
+    "inputPlaceholder": "sys.color.border.boldest",
+    "inputCaret": "sys.color.text.default",
+    "trailingColor": "sys.color.text.default"
   },
   "layout": {
     "grid": "Three-column grid: leading / input / trailing. Side columns size to content (auto); the input column takes the leftover space (`minmax(0, 1fr)`). Same shape as Page's grid — only the centre slot's contents differ (a bare input instead of a centred title). When the trailing column collapses (value empty → clear hidden), the input column expands to consume the freed space; the field never reflows its leading edge.",
     "noTitleSlot": "There is no separate title slot; the input fills the role the Page bar would give the title. Adding a title above or beside the input would compete with the placeholder for the search affordance and break the bar's 56 footprint."
   },
   "states": {
-    "note": "The bar carries no interactive state of its own. The leading and trailing slots inherit Icon Button's recipe (default / hovered / pressed / focused — overlays + three-layer focus ring). The Search bar deliberately omits a `disabled` state: the only screen a `navigation-bar/search` ever lives on is the search results page itself, and a non-typable search bar on that page reduces the surface to a dead chrome strip with no escape affordance beyond the back-arrow. If search must be gated (offline / throttled / paused indexing), gate the *trigger* on the prior screen instead and never route into this bar. The input slot follows the bare-text-field shape — no border, no fill, no rest-vs-active stroke; only the caret and the placeholder→value colour swap signal interaction. See `inputStates` for the input-only details.",
+    "note": "The bar carries no interactive state of its own. The leading and trailing slots inherit Icon Button's recipe (default / hovered / pressed / focused — overlays + single focus ring). The Search bar deliberately omits a `disabled` state: the only screen a `navigation-bar/search` ever lives on is the search results page itself, and a non-typable search bar on that page reduces the surface to a dead chrome strip with no escape affordance beyond the back-arrow. If search must be gated (offline / throttled / paused indexing), gate the *trigger* on the prior screen instead and never route into this bar. The input slot follows the bare-text-field shape — no border, no fill, no rest-vs-active stroke; only the caret and the placeholder→value colour swap signal interaction. See `inputStates` for the input-only details.",
     "inputStates": {
       "default": {
         "caret": "hidden",

package/agents/components/navigation-bar/sub.md

@@ -25,9 +25,7 @@ import { NavigationBar, Button } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### With icon trailing
+## Icon trailing
 
 The trailing slot carries a single icon.
 
@@ -44,7 +42,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### With text button trailing
+## Text Button trailing
 
 The trailing slot carries a [Text Button](../button/text.md) — *Skip* or *Done*. Reads as inline 16/Semibold `primary` type at rest.
 
@@ -61,7 +59,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### Text button pair (composer)
+## Text Button pair
 
 Modal composer bars carry a [Text Button](../button/text.md) on **both** sides — leading `default` appearance for the dismissing *Cancel*, trailing `accent` for the committing *Post* — and **omit the page title**: the pair says everything, and the centre cell keeps a non-heading placeholder so both buttons hold their edge columns. The accent side is the single CTA of the bar; never paint both sides accent, and never swap the sides (commit always trails).
 
@@ -77,7 +75,7 @@ import { Button, NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### External page (close-only)
+## External page
 
 External content visited in-app (embedded webview, in-app browser). Leading drops — no flow to step back; trailing is a single close (×) [Icon Button](../button/icon.md).
 
@@ -93,7 +91,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### Title only
+## Title only
 
 Both side slots empty — for non-dismissible sub-pages (forced confirmation, terms gate).
 
@@ -108,7 +106,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### Overlay (on hero / cover image)
+## Overlay
 
 `appearance="overlay"` paints a transparent container with fixed-white icons and title — the bar floats over a hero / cover image (canonical host: [Profile header](../profile-header/profile-header.md)). The image beneath provides contrast; theme tokens don't apply. The bar still pays its own `env(safe-area-inset-top)` so the status-bar zone reads cleanly. Staged here via [ProfileHeader](../profile-header/profile-header.md) so the preview matches a real-world consumer.
 
@@ -137,9 +135,9 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 | Slot                  | Container          | Color                                   |
 |-----------------------|--------------------|------------------------------------------|
 | **Bar container**     | `sys.color.surface` fill, 8px block / 16px inline padding, no border, no shadow at rest. | — |
-| **Leading**           | Transparent icon capsule (8 padding around 24px glyph). | `sys.color.onSurface` |
-| **Title**             | Plain text, centred horizontally — not interactive. | `sys.color.onSurface` |
-| **Trailing**          | Transparent icon capsule, [Toolbar Button](../button/toolbar.md), or [Text Button](../button/text.md). | `sys.color.onSurface` (icon / Toolbar) or `sys.color.primary` (Text Button) |
+| **Leading**           | Transparent icon capsule (8 padding around 24px glyph). | `sys.color.text.default` |
+| **Title**             | Plain text, centred horizontally — not interactive. | `sys.color.text.default` |
+| **Trailing**          | Transparent icon capsule, [Toolbar Button](../button/toolbar.md), or [Text Button](../button/text.md). | `sys.color.text.default` (icon / Toolbar) or `sys.color.background.primary` (Text Button) |
 
 ## Sizes
 

package/agents/components/navigation-bar/sub.spec.json

@@ -17,7 +17,7 @@
         "overlay"
       ],
       "default": "surface",
-      "description": "Container fill and foreground tone. `surface` (default) — opaque `sys.color.surface` fill, `onSurface` icons and title; the canonical page-chrome treatment. `overlay` — transparent container with **fixed white** icons (`ref.palette.white.1000`), used when the bar floats over a hero/cover image (e.g. inside [Profile header](../profile-header/profile-header.md)). In `overlay`, the title slot is intentionally muted — pass `title=\"\"` (empty string) when the host already carries page identity below the bar."
+      "description": "Container fill and foreground tone. `surface` (default) — opaque `sys.color.surface.default` fill, `onSurface` icons and title; the canonical page-chrome treatment. `overlay` — transparent container with **fixed white** icons (`ref.palette.white.1000`), used when the bar floats over a hero/cover image (e.g. inside [Profile header](../profile-header/profile-header.md)). In `overlay`, the title slot is intentionally muted — pass `title=\"\"` (empty string) when the host already carries page identity below the bar."
     },
     "title": {
       "type": "string",
@@ -74,11 +74,11 @@
   },
   "appearances": {
     "surface": {
-      "containerFill": "sys.color.surface",
-      "leadingColor": "sys.color.onSurface",
-      "titleColor": "sys.color.onSurface",
-      "trailingColor": "sys.color.onSurface",
-      "trailingTextButtonColor": "sys.color.primary",
+      "containerFill": "sys.color.surface.default",
+      "leadingColor": "sys.color.text.default",
+      "titleColor": "sys.color.text.default",
+      "trailingColor": "sys.color.text.default",
+      "trailingTextButtonColor": "sys.color.text.link",
       "default": true,
       "note": "Canonical page chrome — opaque surface fill with onSurface foreground."
     },
@@ -96,7 +96,7 @@
     "titleCentring": "Title is anchored to the bar's geometric horizontal centre — measured against the page component container, not against the side slots. A 40px back arrow paired with a 80px primary Toolbar Button still leaves the title perfectly centred; the side slots anchor at the start / end of their respective halves and never displace the title. The action always stays intact; title truncation (ellipsis) kicks in if the natural width exceeds what the bar can give it."
   },
   "states": {
-    "note": "Bar itself has no interactive state. Side slots inherit the state recipe of whichever control they host (Icon Button / Toolbar Button / Text Button) — default / hovered / pressed / disabled / focused via the standard overlays + three-layer focus ring. Title carries no states."
+    "note": "Bar itself has no interactive state. Side slots inherit the state recipe of whichever control they host (Icon Button / Toolbar Button / Text Button) — default / hovered / pressed / disabled / focused via the standard overlays + single focus ring. Title carries no states."
   },
   "focusIndicator": {
     "description": "The bar itself isn't a focus target. Its action slots inherit each control's own focus composition — Icon Button → Outward, Toolbar Button → Outward, Text Button → Outward — so the ring belongs to whichever control the keyboard lands on. See the contained sub-components for the visual contract.",

package/agents/components/pagination/pagination.family.json

@@ -2,7 +2,7 @@
   "$schema": "../../family.schema.json",
   "family": "pagination",
   "name": "Pagination",
-  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span` / inline-flex) sized to its dots — one 6px dot per page; the active dot paints `sys.color.onSurface`, the rest paint `sys.color.outlineVariant`. Presentational only (`aria-hidden`) — the host pager owns horizontal placement (the carousels center it), scroll position, active-index tracking, and keyboard reach; tapping a dot does not navigate. Renders nothing below two pages. Single appearance, single rung. Single-spec family.",
+  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span` / inline-flex) sized to its dots — one 6px dot per page; the active dot paints `sys.color.text.default`, the rest paint `sys.color.border.default`. Presentational only (`aria-hidden`) — the host pager owns horizontal placement (the carousels center it), scroll position, active-index tracking, and keyboard reach; tapping a dot does not navigate. Renders nothing below two pages. Single appearance, single rung. Single-spec family.",
   "useCases": [
     "carousel page position (PostCarousel / ProfileCarousel)",
     "swipeable media gallery position",