@teamblind-chorus/ui 1.1.0 → 2.0.0

package/agents/components/button/text.md

@@ -20,9 +20,7 @@ import { Button } from '@teamblind-chorus/ui';
 <Button variant="text">Not now</Button>
 ```
 
-## Use cases
-
-### Accent
+## Accent
 
 Brand-blue label (`primary`) — the inline commit. Reach for `accent` when the button reads as a navigational link (*See all*, *Follow*, *View details*).
 
@@ -34,7 +32,7 @@ import { Button } from '@teamblind-chorus/ui';
 <Button variant="text" appearance="accent">Skip</Button>
 ```
 
-### On primary
+## On primary
 
 Always-white label on top of a `primary`-filled host (Tooltip `default`). Theme-stable.
 
@@ -46,7 +44,7 @@ import { Button } from '@teamblind-chorus/ui';
 <Button variant="text" appearance="onPrimary">Got it</Button>
 ```
 
-### Inverse
+## Inverse
 
 For inverse hosts (Toast, coach-mark, snackbar). Label paints `inverseOnSurface`; tokens flip with theme.
 
@@ -58,7 +56,7 @@ import { Button } from '@teamblind-chorus/ui';
 <Button variant="text" appearance="inverse">Undo</Button>
 ```
 
-### With leading icon
+## Leading icon
 
 16px (`sys.icon.md`) glyph before the label at 4px gap — fixed across rungs.
 
@@ -70,7 +68,7 @@ import { Button, ChevronLeftIcon } from '@teamblind-chorus/ui';
 <Button variant="text" leadingIcon={<ChevronLeftIcon />}>Back</Button>
 ```
 
-### With trailing icon
+## Trailing icon
 
 Destination glyph after the label — chevron-right *Continue*, external-link *Open in new tab*.
 
@@ -82,7 +80,7 @@ import { Button, ChevronRightIcon } from '@teamblind-chorus/ui';
 <Button variant="text" trailingIcon={<ChevronRightIcon />}>Continue</Button>
 ```
 
-### Dropdown
+## Dropdown
 
 Disclosure trigger: the label reads as the **current value**, the trailing chevron flips with state — `ChevronDownIcon` at rest, `ChevronUpIcon` while the menu is open. Pair `aria-haspopup` + `aria-expanded` on the trigger and portal the menu so it escapes any clipping ancestor; never freeze the chevron when the menu is open.
 
@@ -112,31 +110,31 @@ function Example() {
 }
 ```
 
-### Group
+## Focus ring
 
-Optical alignment means chrome-to-chrome gap **is** the visible label-to-label distance. Row gap: `medium`/`small` → 16px (`sys.layout.inline.xl`); `xsmall` → 12px (`sys.layout.inline.lg`).
+Standard ring.
 
 ```preview
-button/text/group
+button/text/focused
 ---
 import { Button } from '@teamblind-chorus/ui';
 
-<div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-md)' }}>
-  <Button variant="text">Cancel</Button>
-  <Button variant="text" appearance="accent">Save</Button>
-</div>
+<Button variant="text" state="focused">Skip</Button>
 ```
 
-### Focus indicator
+## Group
 
-Standard ring.
+Optical alignment means chrome-to-chrome gap **is** the visible label-to-label distance. Row gap: `medium`/`small` → 16px (`sys.layout.inline.xl`); `xsmall` → 12px (`sys.layout.inline.lg`).
 
 ```preview
-button/text/focused
+button/text/group
 ---
 import { Button } from '@teamblind-chorus/ui';
 
-<Button variant="text" state="focused">Skip</Button>
+<div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-md)' }}>
+  <Button variant="text">Cancel</Button>
+  <Button variant="text" appearance="accent">Save</Button>
+</div>
 ```
 
 ## Slots
@@ -151,10 +149,10 @@ A **destructive** flavor swaps the label to `error` across every appearance.
 
 | Appearance  | Background (rest) | Label color                       | When to reach for it                                                                 |
 |-------------|-------------------|-----------------------------------|--------------------------------------------------------------------------------------|
-| `default`   | `transparent`     | `sys.color.onSurfaceVariant`      | Base inline action — "Not now", secondary inline trail commits. |
-| `accent`    | `transparent`     | `sys.color.primary`               | Brand-blue inline commit — "Skip", "See all". One per row. |
-| `onPrimary` | `transparent`     | `sys.color.onPrimary`             | On a `primary`-filled host (Tooltip `default`). Theme-stable. |
-| `inverse`   | `transparent`     | `sys.color.inverseOnSurface`      | Inside an inverse host (Toast, coach-mark). |
+| `default`   | `transparent`     | `sys.color.text.subtle`      | Base inline action — "Not now", secondary inline trail commits. |
+| `accent`    | `transparent`     | `sys.color.background.primary`               | Brand-blue inline commit — "Skip", "See all". One per row. |
+| `onPrimary` | `transparent`     | `sys.color.text.onFill`             | On a `primary`-filled host (Tooltip `default`). Theme-stable. |
+| `inverse`   | `transparent`     | `sys.color.text.inverse`      | Inside an inverse host (Toast, coach-mark). |
 
 ## Sizes
 

package/agents/components/button/text.spec.json

@@ -100,26 +100,26 @@
     "default": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.onSurfaceVariant",
+      "label": "sys.color.text.subtle",
       "note": "The base neutral inline action — the canonical Text Button. Quiet enough to live next to typographic content without claiming commit-rank attention."
     },
     "accent": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.primary",
+      "label": "sys.color.text.link",
       "note": "Brand-blue label for the inline commit affordance. Use sparingly — never two `accent` Text Buttons in the same row.",
       "linkAffordanceRecommendation": "Prefer `accent` whenever the Text Button reads as a **link affordance** — a section header's trailing 'See all' / 'See more', a card-header 'Follow', an inline 'View details' next to a body paragraph. Link-like affordances should carry chromatic emphasis so the navigational intent is unambiguous; `default` (onSurfaceVariant) is for quieter inline commits that should recede into the body copy. Override to `default` only when a parent surface (e.g. a busy chrome bar) already carries enough chromatic weight that an `accent` label would compete."
     },
     "onPrimary": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.onPrimary",
+      "label": "sys.color.text.onFill",
       "note": "Always-white label for use on top of a `primary`-filled host (e.g. the Tooltip `default` appearance). Both `primary` and `onPrimary` are theme-stable (blue / white in light and dark mode), so the label reads as white against the brand-blue fill in either theme — unlike `inverse`, which flips with the theme."
     },
     "inverse": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.inverseOnSurface",
+      "label": "sys.color.text.inverse",
       "note": "Mirror for use inside an inverse host (Toast, coach-mark, snackbar). Label paints in `inverseOnSurface` so it reads against the host's `inverseSurface` fill; state overlays mix from the same token so the recipe carries over without per-host tuning. The `inverseOnSurface` token FLIPS with the theme (white in light mode, dark in dark mode) — that's correct against the also-flipping `inverseSurface` host. When the host fill does NOT flip (e.g. a `primary`-filled Tooltip in `default` appearance), reach for `onPrimary` instead so the label stays white in both themes."
     }
   },
@@ -130,22 +130,22 @@
         "default": {
           "background": "transparent",
           "border": null,
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         },
         "accent": {
           "background": "transparent",
           "border": null,
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         },
         "onPrimary": {
           "background": "transparent",
           "border": null,
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         },
         "inverse": {
           "background": "transparent",
           "border": null,
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         }
       }
     }
@@ -166,6 +166,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "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. 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 button is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",
@@ -176,16 +195,14 @@
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the button is in. The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
     "composition": "outward",
-    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding layout.",
+    "compositionReason": "Action affordance with breathing room around it; the 1px outward ring is reserved by the surrounding layout.",
     "overlay": {
       "color": "label",
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset"
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused"
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },

package/agents/components/button/toggle.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/button/toggle.md`](../../../i18n/ko/schema/components/button/toggle.md)
 
-Commit-and-record action — a Toolbar-footprint button with two states. **Inactive** invites the commit (`primary` fill); **active** records it (`transparent` fill + hairline `outlineVariant` outline).
+Commit-and-record action — a Toolbar-footprint button with two states. **Inactive** invites the commit (`primary` fill); **active** records it (`transparent` fill + hairline `border.default` outline).
 
 **Reach for this when** you need a reversible commit that persists across views — *Follow / Following*, *Subscribe / Subscribed*, *Join / Joined*. **Skip when** the action is one-shot ([Standard Button](./standard.md)), the row is a dense toolbar ([Toolbar Button](./toolbar.md)), or the toggle belongs to a filter set ([Filter Chip](../chip/filter.md)).
 
@@ -24,7 +24,7 @@ import { Button } from '@teamblind-chorus/ui';
 
 ## Active
 
-The committed form — `transparent` fill with hairline `outlineVariant` stroke. The transparent fill lets the button sit on any host surface tier (page `surface`, card `surfaceContainer`, raised `surfaceContainerHigh`) without re-painting a background that would clash with the host. Use the same element across both states and toggle the `active` flag; the consumer swaps the label text. Reports state via `aria-pressed`.
+The committed form — `transparent` fill with hairline `border.default` stroke. The transparent fill lets the button sit on any host surface tier (page `surface`, card `surfaceContainer`, raised `surfaceContainerHigh`) without re-painting a background that would clash with the host. Use the same element across both states and toggle the `active` flag; the consumer swaps the label text. Reports state via `aria-pressed`.
 
 ```preview
 button/toggle/active
@@ -36,9 +36,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-## Use cases
-
-### With icon
+## Leading icon
 
 A check glyph on commit reinforces the active read. Inactive form stays glyph-less.
 
@@ -53,7 +51,7 @@ import { CheckedIcon } from '@teamblind-chorus/ui/icons';
 </Button>
 ```
 
-### Focus indicator
+## Focus ring
 
 Both forms take the same standard ring; below shows inactive. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
 
@@ -71,7 +69,7 @@ import { Button } from '@teamblind-chorus/ui';
 
 - **label** — accessible name. Required, single line. Consumer swaps the verb between states ("Follow" → "Following"); no auto-rewrite.
 - **leadingIcon** (optional) — context glyph before the label. Inherits colour via `currentColor` per the [family rule](./button.md#icon-colour-inheritance-family-wide).
-- **trailingIcon** (optional) — directional/destination glyph after the label. Same contract as [Toolbar Button](./toolbar.md#with-trailing-icon).
+- **trailingIcon** (optional) — directional/destination glyph after the label. Same contract as [Toolbar Button](./toolbar.md#trailing-icon).
 
 ## Sizes
 
@@ -93,8 +91,8 @@ A single visual variant — inactive/active is expressed as a state on the same
 
 | State        | Background                          | Border (always 1px `sys.borderWidth.hairline`)          | Label / icon color                | Notes                                                                |
 |--------------|-------------------------------------|---------------------------------------------------------|-----------------------------------|----------------------------------------------------------------------|
-| inactive     | `sys.color.primary`                 | `transparent`                                           | `sys.color.onPrimary`             | Brand-loud fill inviting commit. Border `transparent` but 1px width held so footprint never changes between states. |
-| active       | `transparent`                       | `sys.color.outlineVariant`                              | `sys.color.onSurface`             | Committed form — hairline-outlined ghost over whatever host surface the button sits on. Transparent fill records state without claiming attention or clashing with the host tier. |
+| inactive     | `sys.color.background.primary`                 | `transparent`                                           | `sys.color.text.onFill`             | Brand-loud fill inviting commit. Border `transparent` but 1px width held so footprint never changes between states. |
+| active       | `transparent`                       | `sys.color.border.default`                              | `sys.color.text.default`             | Committed form — hairline-outlined ghost over whatever host surface the button sits on. Transparent fill records state without claiming attention or clashing with the host tier. |
 
 ## States
 

package/agents/components/button/toggle.spec.json

@@ -63,16 +63,16 @@
   },
   "selectionStates": {
     "unselected": {
-      "background": "sys.color.primary",
-      "label": "sys.color.onPrimary",
+      "background": "sys.color.background.primary",
+      "label": "sys.color.text.onFill",
       "border": null
     },
     "selected": {
       "background": "transparent",
-      "label": "sys.color.onSurface",
+      "label": "sys.color.text.default",
       "border": {
         "width": "sys.borderWidth.hairline",
-        "color": "sys.color.outlineVariant"
+        "color": "sys.color.border.default"
       }
     }
   },
@@ -92,6 +92,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "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. 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 button is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",
@@ -102,21 +121,19 @@
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the button is in. The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
     "composition": "outward",
-    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding layout.",
+    "compositionReason": "Action affordance with breathing room around it; the 1px outward ring is reserved by the surrounding layout.",
     "overlay": {
       "color": "label",
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset"
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused"
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },
   "forbidden": [
-    "active state painted with sys.color.primary fill — active is transparent + hairline outline (the active state recedes, not asserts)",
+    "active state painted with sys.color.background.primary fill — active is transparent + hairline outline (the active state recedes, not asserts)",
     "active state painted with any opaque surface fill (surface, surfaceContainer, surfaceContainerHigh) — the committed form is transparent so the host surface shows through; do not re-bind to a tier'd fill",
     "rest state without an explicit `active={false}` — toggle is a binary contract, never tristate",
     "manual width override that breaks the full-card stretch when used inside ProfileCarousel.followAction"

package/agents/components/button/toolbar.md

@@ -22,9 +22,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-## Use cases
-
-### Accent
+## Accent
 
 Brand-blue fill, `onPrimary` label — the single-commit form. Used when the Toolbar Button IS the surface's commit affordance.
 
@@ -38,7 +36,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### Inverse
+## Inverse
 
 Mirror for inverse hosts (snackbars, coach-mark surfaces). Geometry identical; colour pair flips.
 
@@ -52,7 +50,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### With icon
+## Leading icon
 
 Context glyph before the label — tag for *Filters*, calendar for *Pick date*.
 
@@ -70,7 +68,7 @@ import { PlusIcon } from '@teamblind-chorus/ui/icons';
 </Button>
 ```
 
-### With trailing icon
+## Trailing icon
 
 Directional/destination glyph — chevron-down to open a menu, "×" to clear. Unlike standard [Button](./button.md), Toolbar Button carries trailing icons because its role is often *trigger* rather than commit.
 
@@ -88,7 +86,7 @@ import { CheckedIcon } from '@teamblind-chorus/ui/icons';
 </Button>
 ```
 
-### Icon only
+## Icon only
 
 Glyph-only 32×32 square. Requires `aria-label`. When the label slot is absent, inline padding drops to `sys.layout.container.xs` (8) so the glyph centers.
 
@@ -105,7 +103,22 @@ import { PlusIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### Group
+## Focus ring
+
+Hairline stroke is kept underneath the standard ring.
+
+```preview
+button/toolbar/focused
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button variant="toolbar" state="focused" leadingIcon={<PlusIcon />}>
+  Add row
+</Button>
+```
+
+## Group
 
 Adjacent Toolbar Buttons share `4px` gap (`sys.layout.inline.sm`) with Filter chips. Mix freely.
 
@@ -128,21 +141,6 @@ import { PlusIcon, CheckedIcon } from '@teamblind-chorus/ui/icons';
 </div>
 ```
 
-### Focus indicator
-
-Hairline stroke is kept underneath the standard ring.
-
-```preview
-button/toolbar/focused
----
-import { Button } from '@teamblind-chorus/ui';
-import { PlusIcon } from '@teamblind-chorus/ui/icons';
-
-<Button variant="toolbar" state="focused" leadingIcon={<PlusIcon />}>
-  Add row
-</Button>
-```
-
 ## Slots
 
 - **label** — accessible name. Required, single line.
@@ -155,9 +153,9 @@ Only the container ↔ label colour pair flips; geometry identical. For inline d
 
 | Appearance  | Background                          | Border                                          | Label / icon                       | When to reach for it |
 |-------------|-------------------------------------|--------------------------------------------------|------------------------------------|----------------------|
-| `default`   | `sys.color.surfaceContainerHigh`    | 1px `sys.color.outlineVariant`                   | `sys.color.onSurface`              | Quiet inline action — toolbar opener, "Edit" beside a row title. |
-| `accent`    | `sys.color.primary`                 | none                                             | `sys.color.onPrimary`              | The single commit — a [Page](../navigation-bar/sub.md) bar's "Save". Never two in a row. |
-| `inverse`   | `sys.color.inverseSurface`          | none                                             | `sys.color.inverseOnSurface`       | Inside an inverse host (Toast, coach-mark). |
+| `default`   | `sys.color.surfaceContainerHigh`    | 1px `sys.color.border.default`                   | `sys.color.text.default`              | Quiet inline action — toolbar opener, "Edit" beside a row title. |
+| `accent`    | `sys.color.background.primary`                 | none                                             | `sys.color.text.onFill`              | The single commit — a [Page](../navigation-bar/sub.md) bar's "Save". Never two in a row. |
+| `inverse`   | `sys.color.background.inverse`          | none                                             | `sys.color.text.inverse`       | Inside an inverse host (Toast, coach-mark). |
 
 ## Sizes
 

package/agents/components/button/toolbar.spec.json

@@ -61,23 +61,23 @@
   },
   "appearances": {
     "default": {
-      "background": "sys.color.surfaceContainerHigh",
-      "label": "sys.color.onSurface",
+      "background": "sys.color.surface.default",
+      "label": "sys.color.text.default",
       "border": {
         "width": "sys.borderWidth.hairline",
-        "color": "sys.color.outlineVariant"
+        "color": "sys.color.border.default"
       },
       "note": "The canonical Toolbar Button chrome (mirrors Filter chip's unselected state). The chip-shape signals an inline action that lives within a row of peers (a toolbar, a card footer, a Page bar where the affordance is one of several actions the user might pick)."
     },
     "accent": {
-      "background": "sys.color.primary",
-      "label": "sys.color.onPrimary",
+      "background": "sys.color.background.primary",
+      "label": "sys.color.text.onFill",
       "border": null,
       "note": "Brand-blue commit chip — reach for it when the Toolbar Button IS the surface's commit affordance (a Page bar's 'Save', a sheet's 'Confirm', a flow step's 'Done'). The accent fill claims commit-rank attention while keeping the 32px Toolbar Button footprint, so the bar reads at one density even though the action is the screen's most important. Pair sparingly — never two accent Toolbar Buttons in the same row."
     },
     "inverse": {
-      "background": "sys.color.inverseSurface",
-      "label": "sys.color.inverseOnSurface",
+      "background": "sys.color.background.inverse",
+      "label": "sys.color.text.inverse",
       "border": null,
       "note": "Inverse-toned chip for use inside an inverse host (snackbars, coach-mark surfaces, dark coach overlays). Same chrome geometry as `default`; the colour pair flips to the inverse cluster so the chip reads against the host's `inverseSurface` fill without a per-host tweak."
     }
@@ -88,16 +88,14 @@
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the button is in. Visual ring is delegated to Filter chip's composition; this block restates the contract for external readers.",
     "composition": "outward",
-    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding toolbar row.",
+    "compositionReason": "Action affordance with breathing room around it; the 1px outward ring is reserved by the surrounding toolbar row.",
     "overlay": {
       "color": "label",
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset"
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused"
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },

package/agents/components/carousel/carousel.md

@@ -19,7 +19,7 @@ Both subs share the same pager geometry — a `ref.space.500` (40px) trailing pe
 
 Every Carousel paints a [Header](../header/header.md) (`size="large"`) at the top:
 
-- **Label** *(required)* — `sys.typo.heading.md` / Semibold / `sys.color.onSurface`. Leading position.
+- **Label** *(required)* — `sys.typo.heading.md` / Semibold / `sys.color.text.default`. Leading position.
 - **headerAction** *(optional)* — trailing [Text Button](../button/text.md) (`size={'xsmall'}`, `appearance={'accent'}`) per the link-affordance rule. Extends the header when there's an index page to route to.
 
 Carousel forwards `label` and `headerAction` to [Header](../header/header.md) verbatim; the header anatomy lives in Header's spec. Other hosts (in-sheet sub-sections, bounded cards, [SuggestionList](../suggestion-list/suggestion-list.md)) reach for `<Header />` directly — Carousel is the labelled-region host, Header the leading-row primitive it composes.

package/agents/components/carousel/post.md

@@ -55,9 +55,7 @@ import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
 </Carousel>
 ```
 
-## Use cases
-
-### With header action
+## Header action
 
 Extend the header with a trailing `accent` Text Button when there's an index page to route to. Lifts the `headerAction` prop on the `<Carousel>` wrapper.
 
@@ -69,17 +67,15 @@ import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
 <Carousel label="Trending right now" headerAction={{ label: 'See all', href: '#' }}>
   <PostCarousel
     items={[
-      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Engineering',  verified: true, followAction: true, title: 'The migration that finally landed after three quarters', body: 'Internal postmortem turned editorial — the scaffolding that held the rewrite together when the timeline did not.', mention: '@infra-talk', views: '14K' },
-      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Compensation', verified: true, followAction: true, title: 'Equity refresh negotiations — what actually moves',       body: 'A read on the conversations that get an actual refresh on the calendar versus the ones that get a polite no.',   mention: '@career',     views: '9K'  },
-      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Plant People', verified: false, followAction: true, title: 'Monstera dropping aerial roots — repot or train?',          body: 'Two-year-old monstera, roots crawling out of the drainage holes. Light and watering are dialed in.',              mention: '@plant-parents', views: '3K' },
+      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Engineering', verified: true, followAction: true, title: 'The migration that finally landed after three quarters', body: 'Internal postmortem turned editorial — the scaffolding that held the rewrite together when the timeline did not.', mention: '@infra-talk', views: '14K' },
     ]}
   />
 </Carousel>
 ```
 
-### Editorial cards (no follow, no verified)
+## Editorial card
 
-Cards drop `verified` and `followAction` — each card's header collapses to avatar + channel name. Reach for it on editorial collections where the card is informational only (round-ups, archives, *what we're reading*); the surface should not invite a per-card commit.
+The card drops `verified` and `followAction` — its header collapses to avatar + channel name. Reach for it on editorial collections where the card is informational only (round-ups, archives, *what we're reading*); the surface should not invite a per-card commit.
 
 ```preview
 carousel/post-editorial
@@ -89,9 +85,7 @@ import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
 <Carousel label="Editor picks">
   <PostCarousel
     items={[
-      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Career',       title: 'The quiet math of staying versus leaving',                body: 'Salary checks, offer evaluations, and the long thread that runs longer than any single conversation can.',                       views: '18K' },
-      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Compensation', title: 'Equity refresh negotiations — what actually moves',       body: 'A read on the conversations that get an actual refresh on the calendar versus the ones that get a polite no.',                     views: '9K'  },
-      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Engineering',  title: 'The migration that finally landed after three quarters', body: 'Internal postmortem turned editorial — the scaffolding that held the rewrite together when the timeline did not.',                 views: '14K' },
+      { avatar: { src: '/placeholder.png', alt: 'Channel' }, channel: 'Career', title: 'The quiet math of staying versus leaving', body: 'Salary checks, offer evaluations, and the long thread that runs longer than any single conversation can.', views: '18K' },
     ]}
   />
 </Carousel>
@@ -103,12 +97,12 @@ import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
 - **pager** — horizontal scroll-snap track. `scroll-snap-type: x mandatory`; native scrollbar hidden.
 - **card** — one compact post card per page; outline-only surface.
   - **avatar** — [Thumbnail](../thumbnail/thumbnail.md) `size={40}`, every prop (`src`, `alt`, `updateDot`, `logoBadge`) forwarded verbatim.
-  - **verified** *(optional)* — `VerifiedFillIcon` (`sys.icon.md`, `sys.color.primary`) to the LEFT of the channel name so the trust signal reads first.
-  - **channel** — channel / author name. `sys.typo.label.md` / Semibold / `sys.color.onSurface`.
-  - **followAction** *(optional)* — trailing [Text Button](../button/text.md) (`xsmall`). `accent` inactive (link-affordance) → `default` active (recedes). Same trailing-Text-Button shape as [List/entry](../list/entry.md)'s [attribution-row case](../list/entry.md#with-trailing-text-button-compact-attribution-row) — see the Behavior note below.
-  - **title** — `sys.typo.label.md` / Semibold / `sys.color.onSurface`. Single line, truncates.
-  - **body** — `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. Three-line clamp.
-  - **mention** *(optional)* — `sys.typo.body.sm` / `sys.color.primary` (not italic).
+  - **verified** *(optional)* — `VerifiedFillIcon` (`sys.icon.md`, `sys.color.background.primary`) to the LEFT of the channel name so the trust signal reads first.
+  - **channel** — channel / author name. `sys.typo.label.md` / Semibold / `sys.color.text.default`.
+  - **followAction** *(optional)* — trailing [Text Button](../button/text.md) (`xsmall`). `accent` inactive (link-affordance) → `default` active (recedes). Same trailing-Text-Button shape as [List/entry](../list/entry.md)'s [attribution-row case](../list/entry.md#trailing-text-button) — see the Behavior note below.
+  - **title** — `sys.typo.label.md` / Semibold / `sys.color.text.default`. Single line, truncates.
+  - **body** — `sys.typo.body.sm` / `sys.color.text.subtle`. Three-line clamp.
+  - **mention** *(optional)* — `sys.typo.body.sm` / `sys.color.background.primary` (not italic).
   - **footer** — leading 'See more' [Text Button](../button/text.md) (`xsmall` / `secondary`) + trailing view count (`EyeIcon` + count `<span>`).
 - **pagination** — [Pagination](../pagination/pagination.md) component, one dot per card (`count` = card count, `activeIndex` from scroll position). Decorative — dot tokens and the `aria-hidden` contract live on its spec; the carousel centers the intrinsic-width row (`align-self: center`).
 
@@ -118,11 +112,11 @@ import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
 |-------------------|----------------|
 | container         | No fill / padding — surrounding [Carousel](../carousel/carousel.md) provides chrome; `sys.layout.stack.md` pager→dots gap |
 | pager             | `gap: sys.layout.inline.md`, `padding-left: sys.layout.container.md` + `scroll-padding-left: sys.layout.container.md` (the 16 rail; full-bleed host → trailing edge reached intrinsically, no negative margin), `scroll-snap-type: x mandatory`, `scrollbar-width: none` |
-| card              | `flex: 0 0 calc(100% - sys.layout.inline.md - ref.space.500)`; `sys.color.surface` fill, `sys.radius.md`, `sys.borderWidth.hairline sys.color.outlineVariant` outline (inset box-shadow), `sys.layout.container.md` padding, `sys.layout.stack.sm` between blocks, `scroll-snap-align: start` |
+| card              | `flex: 0 0 calc(100% - sys.layout.inline.md - ref.space.500)`; `sys.color.surface` fill, `sys.radius.md`, `sys.borderWidth.hairline sys.color.border.default` outline (inset box-shadow), `sys.layout.container.md` padding, `sys.layout.stack.sm` between blocks, `scroll-snap-align: start` |
 | header            | Row: avatar + verified mark + name + spacer + follow action; `align-items: center`; `sys.layout.inline.md` gap |
-| avatar / verified | [Thumbnail](../thumbnail/thumbnail.md) `size={40}` delegated verbatim · `VerifiedFillIcon` at `sys.icon.md` / `sys.color.primary` (resolves to `ref.palette.blue.500`), leading of the channel name |
-| channel / title   | `sys.typo.label.md`, `sys.color.onSurface`, single-line truncate |
-| body / mention    | `sys.typo.body.sm` / `sys.color.onSurfaceVariant` (three-line clamp) · mention in `sys.color.primary` |
+| avatar / verified | [Thumbnail](../thumbnail/thumbnail.md) `size={40}` delegated verbatim · `VerifiedFillIcon` at `sys.icon.md` / `sys.color.background.primary` (resolves to `ref.palette.blue.500`), leading of the channel name |
+| channel / title   | `sys.typo.label.md`, `sys.color.text.default`, single-line truncate |
+| body / mention    | `sys.typo.body.sm` / `sys.color.text.subtle` (three-line clamp) · mention in `sys.color.background.primary` |
 | followAction      | [Text Button](../button/text.md) `size={'xsmall'}`, `appearance={'accent'}` inactive → `appearance={'default'}` active; state tokens delegate to Text Button |
 | footer            | Row: leading 'See more' Text Button (`xsmall` / `secondary`) + trailing view count `<span>`; `justify-content: space-between` |
 | pagination dot    | [Pagination](../pagination/pagination.md) component delegated verbatim — 6 × 6 dots, active/inactive colors, and row gap bind on its spec |