@teamblind-chorus/ui 1.1.0 → 2.0.0

package/agents/components/carousel/post.spec.json

@@ -26,12 +26,12 @@
     },
     "card": {
       "required": true,
-      "description": "One compact post card per page. `flex: 0 0 calc(100% - sys.layout.inline.md - ref.space.500)` so a 40px peek of the next card always surfaces at the trailing edge. `scroll-snap-align: start`. Inner padding `sys.layout.container.md`, `sys.color.surface` fill, `sys.radius.md` corner, `sys.borderWidth.hairline` outline in `sys.color.outlineVariant`.",
+      "description": "One compact post card per page. `flex: 0 0 calc(100% - sys.layout.inline.md - ref.space.500)` so a 40px peek of the next card always surfaces at the trailing edge. `scroll-snap-align: start`. Inner padding `sys.layout.container.md`, `sys.color.surface.default` fill, `sys.radius.md` corner, `sys.borderWidth.hairline` outline in `sys.color.border.default`.",
       "intrinsic": true
     },
     "header": {
       "required": true,
-      "description": "Top row of the card: avatar (Thumbnail size 40) + channel name + optional VerifiedIcon (size sys.icon.md, sys.color.primary) + trailing follow affordance. Rendered by the **shared `EntryRow` atom** — the same component [List/entry](../list/entry.md) rows render — wrapped in a carousel-specific `chorus-post-carousel__card-header`. See `behavior.headerReusesEntryCombo`.",
+      "description": "Top row of the card: avatar (Thumbnail size 40) + channel name + optional VerifiedIcon (size sys.icon.md, sys.color.background.primary) + trailing follow affordance. Rendered by the **shared `EntryRow` atom** — the same component [List/entry](../list/entry.md) rows render — wrapped in a carousel-specific `chorus-post-carousel__card-header`. See `behavior.headerReusesEntryCombo`.",
       "intrinsic": true
     },
     "avatar": {
@@ -44,16 +44,16 @@
     },
     "verified": {
       "required": false,
-      "description": "Inline `VerifiedFillIcon` at `sys.icon.md`, painted in `sys.color.primary` (resolves to `ref.palette.blue.500`). Sits to the **LEFT** of the channel name so the reader's eye lands on the trust signal first, then the name. Decorative — pair with a textual affordance elsewhere if the verified status itself is meaningful.",
+      "description": "Inline `VerifiedFillIcon` at `sys.icon.md`, painted in `sys.color.background.primary` (resolves to `ref.palette.blue.500`). Sits to the **LEFT** of the channel name so the reader's eye lands on the trust signal first, then the name. Decorative — pair with a textual affordance elsewhere if the verified status itself is meaningful.",
       "accepts": [
         "icon"
       ],
       "defaultIcon": "VerifiedFillIcon",
-      "defaultIconColor": "sys.color.primary"
+      "defaultIconColor": "sys.color.icon.accent.blue.default"
     },
     "channel": {
       "required": true,
-      "description": "Channel / author name. `sys.typo.label.md` / Semibold / `sys.color.onSurface`. Single line; truncates. Sits to the right of the optional `verified` mark inside the channel-row sub-container.",
+      "description": "Channel / author name. `sys.typo.label.md` / Semibold / `sys.color.text.default`. Single line; truncates. Sits to the right of the optional `verified` mark inside the channel-row sub-container.",
       "accepts": [
         "text"
       ]
@@ -68,28 +68,28 @@
     },
     "title": {
       "required": true,
-      "description": "Post title. `sys.typo.label.md` / Semibold / `sys.color.onSurface`. One line; truncates with ellipsis.",
+      "description": "Post title. `sys.typo.label.md` / Semibold / `sys.color.text.default`. One line; truncates with ellipsis.",
       "accepts": [
         "text"
       ]
     },
     "body": {
       "required": true,
-      "description": "Post excerpt. `sys.typo.body.sm` / Regular / `sys.color.onSurfaceVariant`. Three-line clamp with trailing ellipsis.",
+      "description": "Post excerpt. `sys.typo.body.sm` / Regular / `sys.color.text.subtle`. Three-line clamp with trailing ellipsis.",
       "accepts": [
         "text"
       ]
     },
     "mention": {
       "required": false,
-      "description": "Tap-anywhere mention / tag line below the body. `sys.typo.body.sm` / `sys.color.primary` (no italic — the carousel card reads tags as part of its body block, unlike the Feed · Post card which italicises a single mention).",
+      "description": "Tap-anywhere mention / tag line below the body. `sys.typo.body.sm` / `sys.color.background.primary` (no italic — the carousel card reads tags as part of its body block, unlike the Feed · Post card which italicises a single mention).",
       "accepts": [
         "text"
       ]
     },
     "footer": {
       "required": true,
-      "description": "Bottom row: leading `more` affordance + trailing view count. The 'See more' label renders as a [Text Button](../button/text.md) (`size={'xsmall'}`, `appearance={'secondary'}`) — same family as the card-header follow action — so both card affordances share one state contract. The view count renders as a non-interactive `<span>` matching the same `xsmall` rhythm (`EyeIcon` at `sys.icon.md` + `sys.typo.label.sm` / `sys.color.onSurfaceVariant`).",
+      "description": "Bottom row: leading `more` affordance + trailing view count. The 'See more' label renders as a [Text Button](../button/text.md) (`size={'xsmall'}`, `appearance={'secondary'}`) — same family as the card-header follow action — so both card affordances share one state contract. The view count renders as a non-interactive `<span>` matching the same `xsmall` rhythm (`EyeIcon` at `sys.icon.md` + `sys.typo.label.sm` / `sys.color.text.subtle`).",
       "intrinsic": true
     },
     "pagination": {
@@ -106,8 +106,8 @@
     "pagePeek": "ref.space.500",
     "pagePeekNote": "Guaranteed minimum visibility of the next card at the trailing edge. Pinned to `ref.space.500` (40px) — a raw ref step rather than a responsive sys-layout rung — because the carousel wants a fixed-pixel visibility floor independent of the responsive sys-layout shift. The card's flex-basis is `calc(100% - sys.layout.inline.md - ref.space.500)`, so the inter-card gap plus the peek subtract from the pager's inline space in lock-step.",
     "pageSnapAnchor": "Cards stick to the leading edge of the pager (the pager's own `padding-left: sys.layout.container.md`, the 16 rail). `scroll-snap-align: start` on each card plus the pager's `scroll-padding-left: sys.layout.container.md` together guarantee that, after every swipe, the snapped card aligns flush with the 16 rail — and the trailing edge holds the 40px peek of the next card.",
-    "cardFill": "sys.color.surface",
-    "cardOutline": "sys.borderWidth.hairline sys.color.outlineVariant",
+    "cardFill": "sys.color.surface.default",
+    "cardOutline": "sys.borderWidth.hairline sys.color.border.default",
     "cardRadius": "sys.radius.md",
     "cardPadding": "sys.layout.container.md",
     "cardStackGap": "sys.layout.stack.sm",
@@ -115,23 +115,23 @@
     "cardAvatarSize": 40,
     "cardAvatarRendersAs": "Thumbnail at size 40 — the carousel does not paint its own circular crop or fallback; both come from the Thumbnail family.",
     "cardChannelTypo": "sys.typo.label.md",
-    "cardChannelColor": "sys.color.onSurface",
+    "cardChannelColor": "sys.color.text.default",
     "cardVerifiedIcon": "VerifiedFillIcon",
     "cardVerifiedSize": "sys.icon.md",
-    "cardVerifiedColor": "sys.color.primary",
+    "cardVerifiedColor": "sys.color.text.link",
     "cardVerifiedColorResolved": "ref.palette.blue.500",
     "cardVerifiedPosition": "Leading — sits to the LEFT of the channel name inside the channel-row sub-container.",
     "cardFollowActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' (inactive — link-affordance rule) → appearance='default' (active — followed state recedes). All state tokens delegate to the Text Button family.",
     "cardMoreActionRendersAs": "Button variant='text' size='xsmall' appearance='secondary'. Same Text Button rung as the follow action so the card's two affordances share one state contract.",
     "cardTitleTypo": "sys.typo.label.md",
-    "cardTitleColor": "sys.color.onSurface",
+    "cardTitleColor": "sys.color.text.default",
     "cardBodyTypo": "sys.typo.body.sm",
-    "cardBodyColor": "sys.color.onSurfaceVariant",
+    "cardBodyColor": "sys.color.text.subtle",
     "cardBodyLineClamp": 3,
     "cardMentionTypo": "sys.typo.body.sm",
-    "cardMentionColor": "sys.color.primary",
+    "cardMentionColor": "sys.color.text.mention",
     "cardFooterTypo": "sys.typo.label.sm",
-    "cardFooterColor": "sys.color.onSurfaceVariant",
+    "cardFooterColor": "sys.color.text.subtle",
     "cardFooterIcon": "EyeIcon",
     "cardFooterIconSize": "sys.icon.md",
     "paginationRendersAs": "Pagination component — dot size / gap / radius and active / inactive colors all delegate to the [Pagination](../pagination/pagination.md) spec.",

package/agents/components/carousel/profile.md

@@ -56,9 +56,7 @@ import { Carousel, ProfileCarousel } 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.
 
@@ -80,33 +78,12 @@ import { Carousel, ProfileCarousel } from '@teamblind-chorus/ui';
           { icon: 'heart', value: '81%' },
         ],
       },
-      {
-        avatar: { src: '/placeholder.png', alt: 'Tesla' },
-        name: 'Tesla',
-        followers: '1.4K followers',
-        metrics: [
-          { icon: 'star', value: '4.7' },
-          { icon: 'pulse', value: '86' },
-          { icon: 'heart', value: '85.3%' },
-        ],
-        followed: true,
-      },
-      {
-        avatar: { src: '/placeholder.png', alt: 'Stripe' },
-        name: 'Stripe',
-        followers: '2.1K followers',
-        metrics: [
-          { icon: 'star', value: '4.5' },
-          { icon: 'pulse', value: '92.4' },
-          { icon: 'heart', value: '88%' },
-        ],
-      },
     ]}
   />
 </Carousel>
 ```
 
-### With description
+## With description
 
 The metrics row swaps out for a two-line description. Use for editorial collections where the value of each profile is best explained in copy (channel topic, hot pitch) rather than numeric signals. The description block is fixed to the same two-line height as the metrics row, so cards stay flush across both modes even when description copy clamps with an ellipsis.
 
@@ -124,19 +101,6 @@ import { Carousel, ProfileCarousel } from '@teamblind-chorus/ui';
         followers: '12.4K followers',
         description: 'Hands-on threads about systems, infra, and the work behind the launch.',
       },
-      {
-        avatar: { src: '/placeholder.png', alt: 'Compensation' },
-        name: 'Compensation',
-        followers: '8.1K followers',
-        description: 'Salary checks, offer evaluations, and the quiet math of staying versus leaving — the channel that runs longer than any single conversation can.',
-        followed: true,
-      },
-      {
-        avatar: { src: '/placeholder.png', alt: 'Career' },
-        name: 'Career',
-        followers: '5.3K followers',
-        description: 'Promotion packets, scope debates, and the rewrites that actually cleared.',
-      },
     ]}
   />
 </Carousel>
@@ -149,9 +113,9 @@ import { Carousel, ProfileCarousel } from '@teamblind-chorus/ui';
 - **card** — one profile card per page; fixed at **176px** wide.
   - **cover** — top band; 88px tall image-area slot. Renders an `<img>` defaulting to `/placeholder.png` (universal Chorus placeholder). `object-fit: cover` crops to fill the band; `sys.color.surfaceContainerHigh` underlies as the no-image fallback. Consumers override via `items[i].cover.src`.
   - **avatar** — [Thumbnail](../thumbnail/thumbnail.md) `size={64}` with [`outlined={true}`](../thumbnail/thumbnail.md#with-surface-outline), centered and overlapping the cover band's bottom edge. The 2-token (`sys.borderWidth.thin`) `surface`-tone outset halo separating the circle from the cover image is owned by Thumbnail's outlined case — the carousel forwards the prop instead of painting a halo on its own wrapper.
-  - **name** — entity name; `sys.typo.label.md` / Semibold / `sys.color.onSurface`; centered, single line truncate.
-  - **followers** — follower count; `sys.typo.label.sm` / `sys.color.onSurfaceVariant`; centered.
-  - **metrics** *(optional)* — row of `icon + value` chips: `star → StarFillIcon (sys.color.icon.yellow)`, `pulse → PulseFillIcon (sys.color.success)`, `heart → HeartFillIcon (sys.color.icon.red)`. Mutually exclusive with `description`.
+  - **name** — entity name; `sys.typo.label.md` / Semibold / `sys.color.text.default`; centered, single line truncate.
+  - **followers** — follower count; `sys.typo.label.sm` / `sys.color.text.subtle`; centered.
+  - **metrics** *(optional)* — row of `icon + value` chips: `star → StarFillIcon (sys.color.icon.accent.yellow.default)`, `pulse → PulseFillIcon (sys.color.text.success)`, `heart → HeartFillIcon (sys.color.icon.accent.red.default)`. Mutually exclusive with `description`.
   - **description** *(optional)* — two-line clamped paragraph that replaces the metrics row when present. Block height fixed to two lines of `sys.typo.label.sm` regardless of copy length, so card height stays consistent across metrics-carrying and copy-carrying cards.
   - **followAction** — full-width [Toggle Button](../button/text.md) (`variant={'toggle'}`); `Follow` (inactive) / `Following` (active).
 - **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`).
@@ -164,11 +128,11 @@ import { Carousel, ProfileCarousel } from '@teamblind-chorus/ui';
 | card           | Fixed `width: 176px`, `sys.color.surface` fill, `sys.radius.md`, inset hairline outline, `scroll-snap-align: start` |
 | cover          | 88px tall image-area slot. Default `src` = `/placeholder.png` (universal image placeholder), `object-fit: cover`, `sys.color.surfaceContainerHigh` underlay |
 | avatar         | [Thumbnail](../thumbnail/thumbnail.md) `size={64}` `outlined`, vertical center on cover's bottom edge. The 2-token `surface`-tone halo separating the circle from the cover image is painted by Thumbnail's `outlined` case (outset `box-shadow: 0 0 0 sys.borderWidth.thin sys.color.surface`) — wrapper has no halo of its own |
-| name           | `sys.typo.label.md`, `sys.color.onSurface`, centered |
-| followers      | `sys.typo.label.sm`, `sys.color.onSurfaceVariant`, centered |
+| name           | `sys.typo.label.md`, `sys.color.text.default`, centered |
+| followers      | `sys.typo.label.sm`, `sys.color.text.subtle`, centered |
 | metrics row    | `sys.layout.inline.md` gap, centered. Fixed-height slot — `calc(sys.typo.label.sm.size * sys.typo.label.sm.line * 2)` so the row always reserves two lines of `label.sm` regardless of content. |
-| metric chip    | `sys.icon.md` glyph + `sys.typo.label.sm` value; star → `StarFillIcon` (`sys.color.icon.yellow`), pulse → `PulseFillIcon` (`sys.color.success`), heart → `HeartFillIcon` (`sys.color.icon.red`) |
-| description    | `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, centered, two-line clamp with trailing ellipsis. Two-layer DOM — outer container owns the same fixed-height slot as `metrics row` (min/max-height = 2 label.sm lines); inner `<p>` owns the `-webkit-line-clamp: 2` truncation. Split sidesteps a Chrome quirk where `display: -webkit-box` and explicit `height` on one element break the third-line clip. |
+| metric chip    | `sys.icon.md` glyph + `sys.typo.label.sm` value; star → `StarFillIcon` (`sys.color.icon.accent.yellow.default`), pulse → `PulseFillIcon` (`sys.color.text.success`), heart → `HeartFillIcon` (`sys.color.icon.accent.red.default`) |
+| description    | `sys.typo.label.sm` / `sys.color.text.subtle`, centered, two-line clamp with trailing ellipsis. Two-layer DOM — outer container owns the same fixed-height slot as `metrics row` (min/max-height = 2 label.sm lines); inner `<p>` owns the `-webkit-line-clamp: 2` truncation. Split sidesteps a Chrome quirk where `display: -webkit-box` and explicit `height` on one element break the third-line clip. |
 | followAction   | [Toggle Button](../button/text.md) (Chip-toggle anatomy), stretched to full card width |
 | pagination dot | [Pagination](../pagination/pagination.md) component delegated verbatim — 6 × 6 dots, active/inactive colors, and row gap bind on its spec |
 

package/agents/components/carousel/profile.spec.json

@@ -26,7 +26,7 @@
     },
     "card": {
       "required": true,
-      "description": "One profile card per page. **Width is fixed at 176px** — every card paints the same footprint regardless of how many entries the rail carries. Vertical stack: cover band → avatar (overlapping) → name → followers → metrics row → follow toggle. `sys.color.surface` fill, `sys.radius.md` corner, `sys.borderWidth.hairline sys.color.outlineVariant` inset outline. `scroll-snap-align: start`.",
+      "description": "One profile card per page. **Width is fixed at 176px** — every card paints the same footprint regardless of how many entries the rail carries. Vertical stack: cover band → avatar (overlapping) → name → followers → metrics row → follow toggle. `sys.color.surface.default` fill, `sys.radius.md` corner, `sys.borderWidth.hairline sys.color.border.default` inset outline. `scroll-snap-align: start`.",
       "intrinsic": true
     },
     "cover": {
@@ -46,33 +46,33 @@
     },
     "name": {
       "required": true,
-      "description": "Entity name (channel / profile / company). `sys.typo.label.md` / Semibold / `sys.color.onSurface`. Centered; single line, truncates with ellipsis.",
+      "description": "Entity name (channel / profile / company). `sys.typo.label.md` / Semibold / `sys.color.text.default`. Centered; single line, truncates with ellipsis.",
       "accepts": [
         "text"
       ]
     },
     "followers": {
       "required": true,
-      "description": "Follower count line. `sys.typo.label.sm` / Semibold / `sys.color.onSurfaceVariant`. Centered; single line.",
+      "description": "Follower count line. `sys.typo.label.sm` / Semibold / `sys.color.text.subtle`. Centered; single line.",
       "accepts": [
         "text"
       ]
     },
     "metrics": {
       "required": false,
-      "description": "Row of metric chips below the name / followers stack. Each chip is `icon + value` painted in `sys.typo.label.sm` / `sys.color.onSurface`. Three default kinds: { icon: 'star', … } → `StarFillIcon` in `sys.color.icon.yellow`; { icon: 'pulse', … } → `PulseFillIcon` in `sys.color.success`; { icon: 'heart', … } → `HeartFillIcon` in `sys.color.icon.red`. Consumers may pass custom { icon: <ReactNode>, value, color? } entries for other shapes. Mutually exclusive with `description` — when both are present `description` wins.",
+      "description": "Row of metric chips below the name / followers stack. Each chip is `icon + value` painted in `sys.typo.label.sm` / `sys.color.text.default`. Three default kinds: { icon: 'star', … } → `StarFillIcon` in `sys.color.icon.accent.yellow.default`; { icon: 'pulse', … } → `PulseFillIcon` in `sys.color.text.success`; { icon: 'heart', … } → `HeartFillIcon` in `sys.color.icon.accent.red.default`. Consumers may pass custom { icon: <ReactNode>, value, color? } entries for other shapes. Mutually exclusive with `description` — when both are present `description` wins.",
       "intrinsic": true
     },
     "description": {
       "required": false,
-      "description": "Two-line clamped descriptive paragraph that replaces the metrics row when present. `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, centered. The slot reserves a fixed height of two `label.sm` lines so card height stays consistent across cards that carry metrics and cards that carry copy — extra content clamps with a trailing ellipsis.",
+      "description": "Two-line clamped descriptive paragraph that replaces the metrics row when present. `sys.typo.label.sm` / `sys.color.text.subtle`, centered. The slot reserves a fixed height of two `label.sm` lines so card height stays consistent across cards that carry metrics and cards that carry copy — extra content clamps with a trailing ellipsis.",
       "accepts": [
         "text"
       ]
     },
     "followAction": {
       "required": true,
-      "description": "Trailing full-width [Toggle Button](../button/text.md) at the foot of the card. `Follow` (inactive) → `Following` (active). The carousel does not paint its own follow chrome — every state binding lives on the Toggle Button (Chip-toggle) contract, which paints `sys.color.primary` while inactive and a `transparent` fill with a hairline outline while active so the followed state recedes against the card's own `surface` tier without re-painting a tone that would clash.",
+      "description": "Trailing full-width [Toggle Button](../button/text.md) at the foot of the card. `Follow` (inactive) → `Following` (active). The carousel does not paint its own follow chrome — every state binding lives on the Toggle Button (Chip-toggle) contract, which paints `sys.color.background.primary` while inactive and a `transparent` fill with a hairline outline while active so the followed state recedes against the card's own `surface` tier without re-painting a tone that would clash.",
       "accepts": [
         "button"
       ],
@@ -90,8 +90,8 @@
     "pagePeek": "ref.space.500",
     "pagePeekNote": "Guaranteed minimum visibility of the next card at the trailing edge — pinned to 40px (ref.space.500). Identical contract to PostCarousel.",
     "pageSnapAnchor": "Cards stick to the leading edge of the pager (the pager's own `padding-left`, the 16 rail). `scroll-snap-align: start` plus the pager's `scroll-padding-left: sys.layout.container.md` produce this anchor.",
-    "cardFill": "sys.color.surface",
-    "cardOutline": "sys.borderWidth.hairline sys.color.outlineVariant",
+    "cardFill": "sys.color.surface.default",
+    "cardOutline": "sys.borderWidth.hairline sys.color.border.default",
     "cardOutlineComposition": "overlay",
     "cardOutlineCompositionNote": "Painted on a dedicated `::after` overlay layer (`position: absolute; inset: 0; z-index: 2; pointer-events: none`), not as an inset `box-shadow` on the card box itself. The card hosts an opaque full-bleed cover band at the top; an inset shadow on the card would be masked by that fill at the top edge. Same overlay idiom DESIGN.md prescribes for the focus ring — so the stroke renders above every child regardless of edge-painting content.",
     "cardRadius": "sys.radius.md",
@@ -99,25 +99,25 @@
     "cardWidthNote": "Fixed pixel width — every profile card paints the same 176px footprint regardless of card count or screen width. The pager scrolls horizontally so the 176px footprint never reflows.",
     "cardStackGap": "sys.layout.stack.sm",
     "coverHeight": "88px",
-    "coverFill": "sys.color.surfaceContainerHigh (background underlay — the placeholder image paints on top via `object-fit: cover`)",
+    "coverFill": "sys.color.surface.default (background underlay — the placeholder image paints on top via `object-fit: cover`)",
     "coverImageSource": "Same `/placeholder.png` asset every Chorus image-area slot falls back to. Cropped to fill the 88px band via `object-fit: cover` — the placeholder's centered 'blind' wordmark stays visually centered. Decorative — `aria-hidden`. Consumers can override per-item via `items[i].cover.src` (any image URL preserving the same `object-fit: cover` crop).",
     "avatarSize": 64,
-    "avatarOverlap": "Avatar's vertical center sits on the cover band's bottom edge — the bottom half of the avatar bleeds onto the card surface. The 2-token (`sys.borderWidth.thin`) `sys.color.surface` halo separating the avatar from the cover band is owned by Thumbnail's `outlined={true}` case (see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline)) — outset `box-shadow`, not a wrapper border. Same contract as ProfileHeader's avatar.",
+    "avatarOverlap": "Avatar's vertical center sits on the cover band's bottom edge — the bottom half of the avatar bleeds onto the card surface. The 2-token (`sys.borderWidth.thin`) `sys.color.surface.default` halo separating the avatar from the cover band is owned by Thumbnail's `outlined={true}` case (see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline)) — outset `box-shadow`, not a wrapper border. Same contract as ProfileHeader's avatar.",
     "nameTypo": "sys.typo.label.md",
-    "nameColor": "sys.color.onSurface",
+    "nameColor": "sys.color.text.default",
     "followersTypo": "sys.typo.label.sm",
-    "followersColor": "sys.color.onSurfaceVariant",
+    "followersColor": "sys.color.text.subtle",
     "metricsRowGap": "sys.layout.inline.md",
     "metricChipTypo": "sys.typo.label.sm",
-    "metricChipColor": "sys.color.onSurface",
+    "metricChipColor": "sys.color.text.default",
     "metricIconSize": "sys.icon.md",
-    "metricIconStar": "StarFillIcon — sys.color.icon.yellow",
-    "metricIconPulse": "PulseFillIcon — sys.color.success",
-    "metricIconHeart": "HeartFillIcon — sys.color.icon.red",
+    "metricIconStar": "StarFillIcon — sys.color.icon.accent.yellow.default",
+    "metricIconPulse": "PulseFillIcon — sys.color.text.success",
+    "metricIconHeart": "HeartFillIcon — sys.color.icon.accent.red.default",
     "midSlotHeight": "calc(sys.typo.label.sm.size * sys.typo.label.sm.line * 2)",
     "midSlotHeightNote": "Shared fixed height for the metrics row and the description slot — exactly two `label.sm` lines (12 × 1.5 × 2 ≈ 36px). Cards that carry metrics and cards that carry a description paint the same outer height.",
     "descriptionTypo": "sys.typo.label.sm",
-    "descriptionColor": "sys.color.onSurfaceVariant",
+    "descriptionColor": "sys.color.text.subtle",
     "descriptionLineClamp": 2,
     "descriptionOverflow": "Two-line clamp with trailing ellipsis; copy exceeding two lines truncates so the slot height stays fixed.",
     "followActionRendersAs": "Button variant='toggle' — Chip-toggle anatomy. Stretched to full card width via a wrapper rule. All state tokens delegate to the Toggle Button (Chip) family.",

package/agents/components/chip/chip.md

@@ -8,5 +8,5 @@ A small, content-shaped control or label — chip-shaped affordance for two anch
 
 ## Sub-components
 
-- **[Filter](./filter.md)** — Selectable filter chip. Capsule (`radius.full`), `surfaceContainerHigh` raised tone with a hairline `outlineVariant` stroke at rest, swaps to an inverse fill when selected. Optional leading and trailing icons.
+- **[Filter](./filter.md)** — Selectable filter chip. Capsule (`radius.full`), `surfaceContainerHigh` raised tone with a hairline `border.default` stroke at rest, swaps to an inverse fill when selected. Optional leading and trailing icons.
 - **[Tag](./tag.md)** — Informational tag chip. Square-cornered (`radius.sm`), `secondaryContainer` fill that sits one tonal step *below* the lifted Filter so the label reads as attached metadata rather than a tappable choice. Optional trailing icon only — typically the dismiss "×" for opt-out flows.

package/agents/components/chip/filter.md

@@ -10,7 +10,7 @@ The selectable chip — a capsule-shaped toggle for refining a set. Unselected i
 
 ## Default
 
-At-rest — transparent fill with a hairline `outlineVariant` stroke so the chip sits on any surface without colliding with the surface ladder.
+At-rest — transparent fill with a hairline `border.default` stroke so the chip sits on any surface without colliding with the surface ladder.
 
 ```preview
 chip/filter/unselected
@@ -22,9 +22,7 @@ import { Chip } from '@teamblind-chorus/ui';
 </Chip>
 ```
 
-## Use cases
-
-### Selected
+## Selected
 
 Active — inverse-toned fill. Toggle the `selected` flag on the same chip element.
 
@@ -41,7 +39,7 @@ import { Chip } from '@teamblind-chorus/ui';
 </Chip>
 ```
 
-### With icon
+## Leading icon
 
 Facet glyph before the label — tag for category, magnifier for search, check on selection.
 
@@ -59,7 +57,7 @@ import { CheckedIcon } from '@teamblind-chorus/ui/icons';
 </Chip>
 ```
 
-### With trailing icon
+## Trailing icon
 
 Directional/dismiss glyph after the label — chevron-down to expand, *×* to clear.
 
@@ -77,7 +75,7 @@ import { XIcon } from '@teamblind-chorus/ui/icons';
 </Chip>
 ```
 
-### With trailing action
+## Trailing action
 
 Pair the chip rail with a trailing accent [Text Button](../button/text.md) (`size='small'`, `appearance='accent'`) for a destination outside the filter axis — managing the set, opening keyword settings. The button is *not* a filter toggle; the chip track scrolls horizontally with a trailing 48px `mask-image` fade painted only while overflowing, and the button stays pinned outside the scroll viewport at `sys.layout.inline.xl` gap.
 
@@ -128,7 +126,21 @@ import { ArrowDownIcon } from '@teamblind-chorus/ui/icons';
 </div>
 ```
 
-### Group
+## Focused
+
+Both selection states take the same standard ring; the case below shows unselected.
+
+```preview
+chip/filter/focused
+---
+import { Chip } from '@teamblind-chorus/ui';
+
+<Chip variant="filter" state="focused">
+  All
+</Chip>
+```
+
+## Group
 
 Adjacent filter chips share a 4px gap (`sys.layout.inline.sm`), left-to-right; selection is independent per chip — Filter does not enforce single-select.
 
@@ -153,20 +165,6 @@ import { Chip } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### Focus indicator
-
-Both selection states take the same standard ring; the case below shows unselected.
-
-```preview
-chip/filter/focused
----
-import { Chip } from '@teamblind-chorus/ui';
-
-<Chip variant="filter" state="focused">
-  All
-</Chip>
-```
-
 ## Slots
 
 - **label** — accessible name. Required, single line.
@@ -197,8 +195,8 @@ Single visual variant; the selected/unselected toggle swaps the container/label
 
 | State        | Background                          | Border (1px `sys.borderWidth.hairline`)                 | Label / icon color                |
 |--------------|-------------------------------------|---------------------------------------------------------|-----------------------------------|
-| unselected   | `transparent`                       | `sys.color.outlineVariant`                              | `sys.color.onSurface`             |
-| selected     | `sys.color.inverseSurface`          | `transparent`                                           | `sys.color.inverseOnSurface`      |
+| unselected   | `transparent`                       | `sys.color.border.default`                              | `sys.color.text.default`             |
+| selected     | `sys.color.background.inverse`          | `transparent`                                           | `sys.color.text.inverse`      |
 
 ## States
 

package/agents/components/chip/filter.spec.json

@@ -63,16 +63,16 @@
   "selectionStates": {
     "unselected": {
       "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"
       },
       "note": "Transparent fill so the chip adopts whatever surface sits behind it (page, raised card, sheet) without pinning to a fixed neutral step."
     },
     "selected": {
-      "background": "sys.color.inverseSurface",
-      "label": "sys.color.inverseOnSurface",
+      "background": "sys.color.background.inverse",
+      "label": "sys.color.text.inverse",
       "border": null
     }
   },
@@ -92,26 +92,49 @@
         "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 chip is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
-      "containerOpacity": "sys.state.disabled",
+      "background": "sys.color.background.disabled",
+      "label": "sys.color.text.disabled",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.border.bold"
+      },
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): neutral disabled fill + bold border so the shape reads on any surface, plus disabled label. Overrides the rest/selected appearance."
     }
   },
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the chip 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/chip/tag.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/chip/tag.md`](../../../i18n/ko/schema/components/chip/tag.md)
 
-The informational chip — square-cornered label naming attached metadata (categories, statuses, content labels). Shorter than Filter (24 vs 32 min-height) with `sys.radius.sm` corners. Two appearances: `default` paints a translucent `sys.color.scrimSubtle` overlay (~8% inverse-tone, adopts whatever surface sits behind it); `accent` paints a tonal pale-primary container with primary label.
+The informational chip — square-cornered label naming attached metadata (categories, statuses, content labels). Shorter than Filter (24 vs 32 min-height) with `sys.radius.sm` corners. Two appearances: `default` paints a translucent `sys.color.background.neutral` overlay (~8% inverse-tone, adopts whatever surface sits behind it); `accent` paints a tonal pale-primary container with primary label.
 
 **Reach for this when** you're naming attached metadata on rows, cards, or profiles. **Skip when** the marker signals unread / new activity on a host rather than describing it — use [Badge](../badge/badge.md) instead.
 
@@ -22,11 +22,9 @@ import { Chip } from '@teamblind-chorus/ui';
 </Chip>
 ```
 
-## Use cases
+## Accent
 
-### Accent
-
-Tonal pale-primary fill — `sys.color.primaryContainer` background, `sys.color.primary` label. Use when the tag should pop against the surface (Popular Tags in compose, highlighted hashtags); the default overlay is too quiet there.
+Tonal pale-primary fill — `sys.color.background.selected` background, `sys.color.background.primary` label. Use when the tag should pop against the surface (Popular Tags in compose, highlighted hashtags); the default overlay is too quiet there.
 
 ```preview
 chip/tag/accent
@@ -38,7 +36,7 @@ import { Chip } from '@teamblind-chorus/ui';
 </Chip>
 ```
 
-### Dismissable
+## Dismissable
 
 Opt-out — same chip with a trailing *×* to remove the tag. Trailing icon inherits label color via `currentColor`.
 
@@ -56,7 +54,22 @@ import { XIcon } from '@teamblind-chorus/ui/icons';
 </Chip>
 ```
 
-### Group
+## Focused
+
+Only the dismissable tag is focusable; the case below shows that form. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+```preview
+chip/tag/focused
+---
+import { Chip } from '@teamblind-chorus/ui';
+import { XIcon } from '@teamblind-chorus/ui/icons';
+
+<Chip variant="tag" state="focused" trailingIcon={<XIcon />}>
+  Newsletter
+</Chip>
+```
+
+## Group
 
 Adjacent tag chips share a 4px gap on both axes — `sys.layout.inline.sm` between siblings, `sys.layout.stack.2xs` between rows on wrap. Mixing with Filter is allowed — Tag's square + sunken tone vs Filter's pill + raised tone keeps roles legible. Tags are passive metadata, so collections exceeding the container's width **wrap** rather than scroll or truncate (set `display: flex; flex-wrap: wrap` on the container; do not use `overflow-x: auto` — horizontal scrolling belongs to tappable affordances).
 
@@ -76,21 +89,6 @@ import { Chip } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### Focus indicator
-
-Only the dismissable tag is focusable; the case below shows that form. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
-
-```preview
-chip/tag/focused
----
-import { Chip } from '@teamblind-chorus/ui';
-import { XIcon } from '@teamblind-chorus/ui/icons';
-
-<Chip variant="tag" state="focused" trailingIcon={<XIcon />}>
-  Newsletter
-</Chip>
-```
-
 ## Slots
 
 - **label** — accessible name. Required, single line.
@@ -120,8 +118,8 @@ Two appearances; Tag never toggles.
 
 | Appearance | Background                                                                                  | Label / icon color           |
 |------------|---------------------------------------------------------------------------------------------|------------------------------|
-| `default`  | `sys.color.scrimSubtle` (translucent inverse-tone overlay — black 8% light / white 8% dark) | `sys.color.onSurface`        |
-| `accent`   | `sys.color.primaryContainer` (theme-aware)                                                  | `sys.color.primary`          |
+| `default`  | `sys.color.background.neutral` (translucent inverse-tone overlay — black 8% light / white 8% dark) | `sys.color.text.default`        |
+| `accent`   | `sys.color.background.selected` (theme-aware)                                                  | `sys.color.background.primary`          |
 
 ## States