@teamblind-chorus/ui 1.2.0 → 2.0.0

package/agents/components/pagination/pagination.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/pagination/pagination.md`](../../../i18n/ko/schema/components/pagination/pagination.md)
 
-Decorative dot-position indicator for one-page-at-a-time pagers — an inline row of 6px dots, one per page, the active dot painted `sys.color.onSurface` and the rest `sys.color.outlineVariant`.
+Decorative dot-position indicator for one-page-at-a-time pagers — an inline row of 6px dots, one per page, the active dot painted `sys.color.text.default` and the rest `sys.color.border.default`.
 
 **Reach for this when** a horizontally-snapping pager needs to show where the user is — carousel cards ([PostCarousel](../carousel/post.md), [ProfileCarousel](../carousel/profile.md)), a swipeable media gallery, an onboarding pager. **Skip when** the position is a task-completion ratio (use [Progress](../progress/progress.md)), the pages need direct tap-to-jump navigation (dots here are non-interactive — use [Tabs](../tabs/tabs.md)), or the pager has only one page (the component renders nothing below two).
 
@@ -22,14 +22,14 @@ import { Pagination } from '@teamblind-chorus/ui';
 
 ## Slots
 
-- **dot** *(decorative, one per page)* — 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.onSurface`; inactive paints `sys.color.outlineVariant`.
+- **dot** *(decorative, one per page)* — 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.text.default`; inactive paints `sys.color.border.default`.
 
 ## Anatomy
 
 | Slot | Token bindings |
 |------|----------------|
 | row  | inline element — `display: inline-flex`, intrinsic width, `sys.layout.inline.sm` gap, `aria-hidden`; horizontal placement belongs to the host |
-| dot  | 6 × 6 (`ref.space.75`), `sys.radius.full`; active `sys.color.onSurface`, inactive `sys.color.outlineVariant` |
+| dot  | 6 × 6 (`ref.space.75`), `sys.radius.full`; active `sys.color.text.default`, inactive `sys.color.border.default` |
 
 ## Behavior
 

package/agents/components/pagination/pagination.spec.json

@@ -2,7 +2,7 @@
   "$schema": "../../spec.schema.json",
   "name": "Pagination",
   "family": "pagination",
-  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span`, `display: inline-flex`) sized to its dots — it never stretches or centers itself; the host owns horizontal placement (the carousels center it via `align-self: center`). Renders one 6px (`ref.space.75`) fully-rounded dot per page in a `sys.layout.inline.sm` row; the active dot paints `sys.color.onSurface`, the rest paint `sys.color.outlineVariant`. The row is presentational only (`aria-hidden`): the host pager (PostCarousel, ProfileCarousel, a media gallery) tracks the active index — typically via IntersectionObserver on its snap targets — and passes it down; tapping a dot does not navigate. Renders nothing when `count` < 2 — a one-page pager has no position to indicate.",
+  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span`, `display: inline-flex`) sized to its dots — it never stretches or centers itself; the host owns horizontal placement (the carousels center it via `align-self: center`). Renders one 6px (`ref.space.75`) fully-rounded dot per page in a `sys.layout.inline.sm` row; the active dot paints `sys.color.text.default`, the rest paint `sys.color.border.default`. The row is presentational only (`aria-hidden`): the host pager (PostCarousel, ProfileCarousel, a media gallery) tracks the active index — typically via IntersectionObserver on its snap targets — and passes it down; tapping a dot does not navigate. Renders nothing when `count` < 2 — a one-page pager has no position to indicate.",
   "element": "span",
   "props": {
     "count": {
@@ -19,7 +19,7 @@
   "slots": {
     "dot": {
       "required": true,
-      "description": "One per page. 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.onSurface`; inactive paints `sys.color.outlineVariant`.",
+      "description": "One per page. 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.text.default`; inactive paints `sys.color.border.default`.",
       "intrinsic": true
     }
   },
@@ -31,8 +31,8 @@
     "dotRadius": "sys.radius.full"
   },
   "appearance": {
-    "activeDot": "sys.color.onSurface",
-    "inactiveDot": "sys.color.outlineVariant"
+    "activeDot": "sys.color.text.default",
+    "inactiveDot": "sys.color.border.default"
   },
   "states": {
     "default": { "note": "Pagination carries no lifecycle states — the active index is its visual state, and the dots are non-interactive." }
@@ -45,7 +45,7 @@
   },
   "forbidden": [
     "Dots rendered as interactive controls (button / link, tap-to-navigate) — that needs a focusable, labelled tab-like contract this family deliberately does not carry; if navigation chrome is required, use a different component",
-    "Active dot painted with a chromatic primary / accent / brand tone — the indicator is position chrome, not emphasis; active is `sys.color.onSurface`, full stop",
+    "Active dot painted with a chromatic primary / accent / brand tone — the indicator is position chrome, not emphasis; active is `sys.color.text.default`, full stop",
     "Pagination used as a step / completion indicator for a linear task — that role is `progress`",
     "Numeric page labels, counters, or arrows composed into the row — the family is the dot row only; numbered pagination is a different pattern",
     "Rendering the row for a single page (`count` < 2) by bypassing the built-in guard — a one-page pager has no position to indicate",

package/agents/components/profile-header/profile-header.md

@@ -30,9 +30,7 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### Following
+## Following
 
 Active state — the trailing button has flipped to `Following` (`surfaceContainerHigh` + hairline outline) so the followed state recedes.
 
@@ -51,7 +49,7 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 />
 ```
 
-### Private
+## Private
 
 Private visibility — paints the [LockIcon](../../icons/svg/Lock.svg) on the meta row in place of the globe. Reach for it when the entity is gated (members-only channel, locked company channel).
 
@@ -69,7 +67,7 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 />
 ```
 
-### With cover image
+## Cover image
 
 A custom cover photo overrides the placeholder. The image is `object-fit: cover` — aspect ratio preserved, cropped to fill the `375 / 120` cover band (scales with the host column).
 
@@ -87,7 +85,7 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 />
 ```
 
-### With status bar
+## Status bar
 
 An edge-to-edge / immersive screen — `statusBar` paints an iOS-style app status bar (time + cellular / Wi-Fi / battery) above the overlay nav, at the very top of the cover. Its fill is transparent so the cover image shows through the OS-chrome zone; the glyphs are fixed white, matching the overlay nav. Reach for it when the route renders the cover full-bleed under a translucent system status bar.
 
@@ -116,8 +114,8 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 - **identity** — vertical column under the cover. Pays `sys.layout.container.md` (16px) inline / block-end padding, no block-start padding (the action row's avatar lifts into the cover from y=0). `sys.layout.stack.xs` (8px) stack gap between the action row and the heading sub-group.
 - **actionRow** — top row of the identity column. Avatar leads (overlapping the cover); follow [Toggle Button](../button/toggle.md) trails. The toggle sits `sys.layout.stack.md` (16px) below the cover bottom — independent of the avatar's lower edge — so it reads with its own breathing room.
 - **heading** — sub-group bundling the name and meta row at `sys.layout.stack.2xs` (4px) gap. Sits below the action row.
-- **name** — entity name. `<h1>` at `sys.typo.heading.lg` (24 / Semibold) / `sys.color.onSurface`. Single line; truncates with ellipsis.
-- **meta** — visibility + follower row. `[visibility icon] [visibility label] · [followers]` in `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. Single line.
+- **name** — entity name. `<h1>` at `sys.typo.heading.lg` (24 / Semibold) / `sys.color.text.default`. Single line; truncates with ellipsis.
+- **meta** — visibility + follower row. `[visibility icon] [visibility label] · [followers]` in `sys.typo.body.sm` / `sys.color.text.subtle`. Single line.
 - **followAction** — trailing [Toggle Button](../button/toggle.md) (`variant={'toggle'}`). `Follow` (inactive) → `Following` (active). Intrinsic width.
 
 ## Anatomy
@@ -132,9 +130,9 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 | identity      | Flex column, `padding-block: 0 sys.layout.container.md`, `padding-inline: sys.layout.container.md`, `sys.layout.stack.xs` (8) gap |
 | actionRow     | Flex row, `space-between` justify, `flex-start` align; follow button carries `margin-top: sys.layout.stack.md` (16) so it sits 16px below cover bottom |
 | heading       | Flex column, `sys.layout.stack.2xs` (4) gap between name and meta |
-| name          | `<h1>`, `sys.typo.heading.lg` (24 / Semibold), `sys.color.onSurface`, single-line ellipsis |
-| meta          | Flex row, `sys.layout.inline.sm` (4) gap, `sys.typo.body.sm` / Regular, `sys.color.onSurfaceVariant`; `·` separator before followers |
-| meta icon     | `sys.icon.md` (16 × 16), `sys.color.onSurfaceVariant` |
+| name          | `<h1>`, `sys.typo.heading.lg` (24 / Semibold), `sys.color.text.default`, single-line ellipsis |
+| meta          | Flex row, `sys.layout.inline.sm` (4) gap, `sys.typo.body.sm` / Regular, `sys.color.text.subtle`; `·` separator before followers |
+| meta icon     | `sys.icon.md` (16 × 16), `sys.color.text.subtle` |
 | followAction  | [Toggle Button](../button/toggle.md) (Toolbar-Button footprint); state tokens delegate to Toggle Button |
 
 ## States

package/agents/components/profile-header/profile-header.spec.json

@@ -37,7 +37,7 @@
     "followers": {
       "type": "string",
       "required": true,
-      "description": "Follower count line — formatted by the consumer so the unit / locale stays in their hands (e.g. '999 followers', '12.4K followers', '999 팔로워'). Paints in `sys.typo.body.sm` / `sys.color.onSurfaceVariant` to the right of a bullet separator on the meta row."
+      "description": "Follower count line — formatted by the consumer so the unit / locale stays in their hands (e.g. '999 followers', '12.4K followers', '999 팔로워'). Paints in `sys.typo.body.sm` / `sys.color.text.subtle` to the right of a bullet separator on the meta row."
     },
     "followed": {
       "type": "boolean",
@@ -93,7 +93,7 @@
   "slots": {
     "container": {
       "required": true,
-      "description": "Outer `<section>`. Vertical stack — cover band first, identity row second. `sys.color.surface` fill; no outer padding (the cover is full-bleed; the identity row pays its own inline padding).",
+      "description": "Outer `<section>`. Vertical stack — cover band first, identity row second. `sys.color.surface.default` fill; no outer padding (the cover is full-bleed; the identity row pays its own inline padding).",
       "intrinsic": true
     },
     "cover": {
@@ -137,12 +137,12 @@
     },
     "name": {
       "required": true,
-      "description": "Entity name. Renders as `<h1>` at `sys.typo.heading.lg` (24 / Semibold) / `sys.color.onSurface`. Single line; truncates with ellipsis. Sits inside the `heading` sub-group.",
+      "description": "Entity name. Renders as `<h1>` at `sys.typo.heading.lg` (24 / Semibold) / `sys.color.text.default`. Single line; truncates with ellipsis. Sits inside the `heading` sub-group.",
       "accepts": ["text"]
     },
     "meta": {
       "required": true,
-      "description": "Visibility + follower meta row. Composed as: [visibility icon] [visibility label] [bullet separator] [follower count]. `sys.typo.body.sm` (14 / Regular) / `sys.color.onSurfaceVariant`. Single line. Sits inside the `heading` sub-group, 4px below the name.",
+      "description": "Visibility + follower meta row. Composed as: [visibility icon] [visibility label] [bullet separator] [follower count]. `sys.typo.body.sm` (14 / Regular) / `sys.color.text.subtle`. Single line. Sits inside the `heading` sub-group, 4px below the name.",
       "intrinsic": true
     },
     "followAction": {
@@ -153,9 +153,9 @@
     }
   },
   "sizing": {
-    "containerFill": "sys.color.surface",
+    "containerFill": "sys.color.surface.default",
     "coverAspectRatio": "375 / 120 (W × H — the mobile-viewport / cover-band proportion; the band scales with the host column instead of locking to a hard pixel height)",
-    "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. Decorative — `aria-hidden`. Consumers override via the `cover.src` prop.",
     "avatarSize": 56,
     "avatarOverlap": "Avatar's vertical center sits on the cover band's bottom edge — the top half overlaps the cover, the bottom half sits on the identity surface (-28px margin-top). The 2-token `surface`-tone halo that separates the circle from the cover is owned by Thumbnail's `outlined={true}` case — see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline). The header does not paint a halo of its own on the wrapper; the Thumbnail's outset `box-shadow` is the contract.",
@@ -170,11 +170,11 @@
     "followMarginTop": "sys.layout.stack.md",
     "followMarginTopNote": "Follow Toggle Button sits 16px below the cover bottom edge so the affordance reads with its own breathing room rather than aligning to the avatar's lower edge.",
     "nameTypo": "sys.typo.heading.lg",
-    "nameColor": "sys.color.onSurface",
+    "nameColor": "sys.color.text.default",
     "metaTypo": "sys.typo.body.sm",
-    "metaColor": "sys.color.onSurfaceVariant",
+    "metaColor": "sys.color.text.subtle",
     "metaIconSize": "sys.icon.md",
-    "metaIconColor": "sys.color.onSurfaceVariant",
+    "metaIconColor": "sys.color.text.subtle",
     "metaGap": "sys.layout.inline.sm",
     "metaSeparator": "·",
     "followActionRendersAs": "Button variant='toggle' — Toolbar-Button footprint. State tokens delegate entirely to the Toggle Button (Chip-toggle) contract."

package/agents/components/progress/progress.family.json

@@ -2,7 +2,7 @@
   "$schema": "../../family.schema.json",
   "family": "progress",
   "name": "Progress",
-  "description": "Linear progress bar — a slim horizontal track that previews how far a long-running task has advanced. Determinate only: a filled segment parks at the value's ratio. One appearance, no emphasis axis: the track paints `sys.color.scrimSubtle` (a faint inverse-tone scrim that reads on any host surface tier) and the indicator paints `sys.color.inverseSurface` so the filled segment always contrasts against the bare track in either theme. A single 8px fully-rounded rung. If a screen needs a higher-attention progress mark, the emphasis belongs in the surrounding copy (e.g. a Banner), never in a chromatic indicator tone. Single-spec family.",
+  "description": "Linear progress bar — a slim horizontal track that previews how far a long-running task has advanced. Determinate only: a filled segment parks at the value's ratio. One appearance, no emphasis axis: the track paints `sys.color.background.neutral` (a faint inverse-tone scrim that reads on any host surface tier) and the indicator paints `sys.color.background.inverse` so the filled segment always contrasts against the bare track in either theme. A single 8px fully-rounded rung. If a screen needs a higher-attention progress mark, the emphasis belongs in the surrounding copy (e.g. a Banner), never in a chromatic indicator tone. Single-spec family.",
   "useCases": [
     "upload / download progress",
     "onboarding step progress",

package/agents/components/progress/progress.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/progress/progress.md`](../../../i18n/ko/schema/components/progress/progress.md)
 
-A single visual rung — 8px tall, fully rounded — that previews how far a long-running task has advanced. Determinate only: a filled indicator parks at the value's ratio. No emphasis axis: track paints with `sys.color.scrimSubtle` (the translucent inverse-tone scrim — ~8% black light, ~8% white dark); indicator paints in `inverseSurface` so the filled segment contrasts against the track regardless of theme.
+A single visual rung — 8px tall, fully rounded — that previews how far a long-running task has advanced. Determinate only: a filled indicator parks at the value's ratio. No emphasis axis: track paints with `sys.color.background.neutral` (the translucent inverse-tone scrim — ~8% black light, ~8% white dark); indicator paints in `inverseSurface` so the filled segment contrasts against the track regardless of theme.
 
 **Reach for this when** a screen holds a task long enough that the user would otherwise wonder if anything is happening — file uploads, onboarding step counters, background syncs, account migrations. **Skip when** the task resolves under 300ms, the wait is purely opaque (use [Skeleton](../skeleton/skeleton.md) for content placeholders, busy spinners for short opaque waits), or the metric is primary content rather than chrome (use a chart).
 
@@ -22,15 +22,15 @@ import { Progress } from '@teamblind-chorus/ui';
 
 ## Slots
 
-- **track** — fully-rounded background block. 8px tall, `sys.color.scrimSubtle` fill (translucent inverse-tone scrim — black 8% light, white 8% dark), no stroke. Carries `role="progressbar"` and the aria-value attributes.
-- **indicator** *(decorative)* — inner filled segment painted in `sys.color.inverseSurface`, `translateX`'d so the trailing edge lands at the value's ratio.
+- **track** — fully-rounded background block. 8px tall, `sys.color.background.neutral` fill (translucent inverse-tone scrim — black 8% light, white 8% dark), no stroke. Carries `role="progressbar"` and the aria-value attributes.
+- **indicator** *(decorative)* — inner filled segment painted in `sys.color.background.inverse`, `translateX`'d so the trailing edge lands at the value's ratio.
 
 ## Anatomy
 
 | Slot         | Token bindings |
 |--------------|----------------|
-| track        | `sys.color.scrimSubtle` fill (translucent inverse-tone scrim), `sys.radius.full`, 8px (`sys.layout.container.xs`) tall |
-| indicator    | `sys.color.inverseSurface` fill, fully rounded, `transform: translateX(…)` driven |
+| track        | `sys.color.background.neutral` fill (translucent inverse-tone scrim), `sys.radius.full`, 8px (`sys.layout.container.xs`) tall |
+| indicator    | `sys.color.background.inverse` fill, fully rounded, `transform: translateX(…)` driven |
 | transition   | 200ms `ease-out` on indicator transform as `value` changes |
 
 ## Behavior

package/agents/components/progress/progress.spec.json

@@ -2,7 +2,7 @@
   "$schema": "../../spec.schema.json",
   "name": "Progress",
   "family": "progress",
-  "description": "Linear progress bar. A single visual rung — 8px tall, fully rounded — that previews how far a long-running task has advanced. The track paints with `sys.color.scrimSubtle` (the Banner-style inverse-tone scrim — ~8% black in light, ~8% white in dark) so the bar reads cleanly on any host surface tier without colliding with a fixed surface-container step. The indicator paints in `sys.color.inverseSurface` so the filled segment always contrasts against the scrim track regardless of theme. The track owns no width of its own — it stretches to fill its host column. Determinate only — `role='progressbar'` with `aria-valuemin / max / now` reflects the value's ratio.",
+  "description": "Linear progress bar. A single visual rung — 8px tall, fully rounded — that previews how far a long-running task has advanced. The track paints with `sys.color.background.neutral` (the Banner-style inverse-tone scrim — ~8% black in light, ~8% white in dark) so the bar reads cleanly on any host surface tier without colliding with a fixed surface-container step. The indicator paints in `sys.color.background.inverse` so the filled segment always contrasts against the scrim track regardless of theme. The track owns no width of its own — it stretches to fill its host column. Determinate only — `role='progressbar'` with `aria-valuemin / max / now` reflects the value's ratio.",
   "element": "div",
   "props": {
     "value": {
@@ -24,29 +24,29 @@
   "slots": {
     "track": {
       "required": true,
-      "description": "Fully-rounded background block. 8px tall, `sys.color.scrimSubtle` fill (translucent inverse-tone scrim — black 8% light / white 8% dark), no stroke. Carries `role='progressbar'` and the aria-value attributes.",
+      "description": "Fully-rounded background block. 8px tall, `sys.color.background.neutral` fill (translucent inverse-tone scrim — black 8% light / white 8% dark), no stroke. Carries `role='progressbar'` and the aria-value attributes.",
       "intrinsic": true
     },
     "indicator": {
       "required": true,
-      "description": "Inner filled segment painted in `sys.color.inverseSurface`, translated horizontally so its trailing edge sits at the value's ratio.",
+      "description": "Inner filled segment painted in `sys.color.background.inverse`, translated horizontally so its trailing edge sits at the value's ratio.",
       "intrinsic": true
     }
   },
   "sizing": {
     "height": "sys.layout.container.xs",
-    "trackBackground": "sys.color.scrimSubtle",
+    "trackBackground": "sys.color.background.neutral",
     "trackRadius": "sys.radius.full",
-    "indicatorBackground": "sys.color.inverseSurface",
+    "indicatorBackground": "sys.color.background.inverse",
     "indicatorRadius": "inherit",
     "transitionDuration": "200ms",
     "transitionTiming": "ease-out"
   },
   "appearances": {
     "default": {
-      "track": "sys.color.scrimSubtle",
-      "indicator": "sys.color.inverseSurface",
-      "note": "The only appearance. Track paints `sys.color.scrimSubtle` — a faint inverse-tone scrim (~8% black light / ~8% white dark) visible against every surface tier in either theme. Indicator paints in `inverseSurface` so the filled segment always contrasts against the bare track regardless of theme. Progress has no emphasis axis; if a screen needs a higher-attention progress mark, it belongs as a Banner copy nearby, not as a chromatic indicator tone."
+      "track": "sys.color.background.neutral",
+      "indicator": "sys.color.background.inverse",
+      "note": "The only appearance. Track paints `sys.color.background.neutral` — a faint inverse-tone scrim (~8% black light / ~8% white dark) visible against every surface tier in either theme. Indicator paints in `inverseSurface` so the filled segment always contrasts against the bare track regardless of theme. Progress has no emphasis axis; if a screen needs a higher-attention progress mark, it belongs as a Banner copy nearby, not as a chromatic indicator tone."
     }
   },
   "states": {

package/agents/components/side-sheet/side-sheet.md

@@ -59,21 +59,21 @@ import { StarFillIcon } from '@teamblind-chorus/ui/icons';
           label: 'Sourdough Bakers',
           count: <Badge size="small" count={12} />,
           thumbnail: { alt: 'Sourdough Bakers' },
-          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorited" aria-pressed="true" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-yellow)' }} onClick={() => {}} />,
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorited" aria-pressed="true" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-accent-yellow-default)' }} onClick={() => {}} />,
         },
         {
           value: 'stocks',
           label: 'Stocks & Investing',
           count: <Badge size="small" count={142} />,
           thumbnail: { alt: 'Stocks & Investing' },
-          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorited" aria-pressed="true" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-yellow)' }} onClick={() => {}} />,
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorited" aria-pressed="true" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-accent-yellow-default)' }} onClick={() => {}} />,
         },
         {
           value: 'movie-talk',
           label: 'Movie Talk',
           count: <Badge size="small" count={24} />,
           thumbnail: { alt: 'Movie Talk' },
-          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorited" aria-pressed="true" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-yellow)' }} onClick={() => {}} />,
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorited" aria-pressed="true" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-accent-yellow-default)' }} onClick={() => {}} />,
         },
       ]}
     />
@@ -90,20 +90,20 @@ import { StarFillIcon } from '@teamblind-chorus/ui/icons';
           label: 'Career & Jobs',
           count: <Badge size="small" count={24} />,
           thumbnail: { alt: 'Career & Jobs' },
-          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorite" aria-pressed="false" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-muted)' }} onClick={() => {}} />,
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorite" aria-pressed="false" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-subtle)' }} onClick={() => {}} />,
         },
         {
           value: 'marketplace',
           label: 'Marketplace',
           count: <Badge size="small" count={12} />,
           thumbnail: { alt: 'Marketplace' },
-          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorite" aria-pressed="false" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-muted)' }} onClick={() => {}} />,
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorite" aria-pressed="false" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-subtle)' }} onClick={() => {}} />,
         },
         {
           value: 'fashion',
           label: 'Fashion & Beauty',
           thumbnail: { alt: 'Fashion & Beauty' },
-          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorite" aria-pressed="false" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-muted)' }} onClick={() => {}} />,
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorite" aria-pressed="false" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-subtle)' }} onClick={() => {}} />,
         },
       ]}
     />
@@ -111,13 +111,11 @@ import { StarFillIcon } from '@teamblind-chorus/ui/icons';
 </SideSheet>
 ```
 
-## Use cases
-
-### Single section
+## Single section
 
 One `SideSheetGroup` with a Header + List(entry) directory. Use for filter rails, settings groups, sub-navigation overlays.
 
-### With pinned commit
+## Pinned commit
 
 Set the `footer` prop with a Text Button to pin a primary commit at the bottom (e.g. "Browse all channels", "Apply filters"). Footer stays flush while the body scrolls.
 
@@ -127,7 +125,7 @@ Set the `footer` prop with a Text Button to pin a primary commit at the bottom (
 - **card** — off-canvas column. Fixed width, full viewport height, flush against the `anchor` edge. `sys.color.surface` fill + `sys.elevation.sheet` shadow.
 - **body** — vertical scroll surface inside the card. **Full-bleed** — no inline gutter; each child pays its own `container.md` (16) rail. Block padding is `0` at the top (each group's leading Header supplies the 24 top inset itself) and `24px` at the bottom; the body adds no inter-child gap — the Header-driven block rhythm is the single source of truth.
 - **group** *(SideSheetGroup)* — bundle of one Header + a directory primitive (canonical: an embedded [list/entry](../list/entry.md) stack) inside the body. The full-bleed Header drives the rhythm: its `24px` (`layout.stack.lg`) block-start is both the gap **between groups** and the body's top inset for the first group; its `16px` (`layout.stack.md`) block-end is the header↔directory gap. The group adds no sibling margin of its own. Because the body is full-bleed, the `<List variant="entry">` aligns at the same 16 rail as the Header with no opt-out.
-- **footer** *(optional)* — pinned bottom action rail. Single Text Button or compact action node; separated by an `outlineVariant` hairline.
+- **footer** *(optional)* — pinned bottom action rail. Single Text Button or compact action node; separated by an `border.default` hairline.
 
 ## Trailing favorite-star contract
 
@@ -135,8 +133,8 @@ When a channel / directory row carries a favorite toggle on its trailing edge, u
 
 | State    | Icon            | Colour                          | aria-pressed |
 |----------|-----------------|---------------------------------|--------------|
-| Active   | `StarFillIcon`  | `var(--sys-color-icon-yellow)`  | `true`       |
-| Inactive | `StarFillIcon`  | `var(--sys-color-icon-muted)`   | `false`      |
+| Active   | `StarFillIcon`  | `var(--sys-color-icon-accent-yellow-default)`  | `true`       |
+| Inactive | `StarFillIcon`  | `var(--sys-color-icon-subtle)`   | `false`      |
 
 The shape stays constant so the trailing edge has a stable hit-target footprint; only the colour token flips. This is the canonical pattern across Side Sheet, channel lists, directory rows.
 

package/agents/components/side-sheet/side-sheet.spec.json

@@ -63,19 +63,19 @@
     },
     "footer": {
       "required": false,
-      "description": "Pinned bottom action rail. Separated from the body by a `outlineVariant` hairline. `16px` inline + block padding."
+      "description": "Pinned bottom action rail. Separated from the body by a `border.default` hairline. `16px` inline + block padding."
     }
   },
   "sizing": {
     "scrimColor": "ref.palette.black.600",
-    "cardBg": "sys.color.surface",
+    "cardBg": "sys.color.surface.default",
     "cardElevation": "sys.elevation.sheet",
     "cardDefaultWidth": "320px",
     "bodyPadding": "sys.layout.container.lg (24) block × sys.layout.container.md (16) inline",
     "bodyStackGap": "sys.layout.stack.lg (24) — between groups",
     "groupStackGap": "sys.layout.stack.md (16) — within group, Header → List",
     "footerPadding": "sys.layout.container.md (16)",
-    "footerDivider": "sys.borderWidth.hairline / sys.color.outlineVariant"
+    "footerDivider": "sys.borderWidth.hairline / sys.color.border.default"
   },
   "states": {
     "open": {

package/agents/components/skeleton/skeleton.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/skeleton/skeleton.md`](../../../i18n/ko/schema/components/skeleton/skeleton.md)
 
-A tonal placeholder block that previews where real content will render. Paints with a translucent `scrimSubtle` overlay (~8% black in light mode, ~8% white in dark) and a slow opacity pulse — visible on every host surface tier without colliding with a fixed neutral step. Three shapes — `text` (default 16-line block), `block` (image / card body), `circle` (avatar). Compose multiple Skeletons inside `SkeletonGroup` to mirror the loading content's rhythm.
+A tonal placeholder block that previews where real content will render. Paints with a translucent `background.neutral` overlay (~8% black in light mode, ~8% white in dark) and a slow opacity pulse — visible on every host surface tier without colliding with a fixed neutral step. Three shapes — `text` (default 16-line block), `block` (image / card body), `circle` (avatar). Compose multiple Skeletons inside `SkeletonGroup` to mirror the loading content's rhythm.
 
 **Reach for this when** a list row, feed post, card cover, or avatar is being fetched and the host would otherwise paint empty. **Skip when** the wait is sub-300ms, the data is unavailable rather than loading (use an empty-state illustration), or the loading scope is the whole screen (use a centered progress indicator at page level).
 
@@ -20,9 +20,7 @@ import { Skeleton } from '@teamblind-chorus/ui';
 <Skeleton />
 ```
 
-## Use cases
-
-### Block
+## Block
 
 A rectangular tonal block. 80px high by default — reads as a card cover, image area, or card body placeholder. Pass `height` to match the real content's footprint.
 
@@ -34,7 +32,7 @@ import { Skeleton } from '@teamblind-chorus/ui';
 <Skeleton shape="block" height={120} />
 ```
 
-### Circle
+## Circle
 
 An avatar placeholder. 40 × 40 by default — matches a 40-rung [Thumbnail](../thumbnail/thumbnail.md). Override `width` / `height` for a different rung.
 
@@ -46,7 +44,7 @@ import { Skeleton } from '@teamblind-chorus/ui';
 <Skeleton shape="circle" />
 ```
 
-### List row
+## List row
 
 A list-row loading state — leading 40-circle next to two stacked text lines. Use the same widths as the real row so the swap to live data doesn't reflow.
 
@@ -64,7 +62,7 @@ import { Skeleton, SkeletonGroup } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### Feed post
+## Feed post
 
 A feed-post loading state — author row (avatar + name + meta), title, two body lines, and a 16:9 cover block. Mirrors the rhythm of a real feed/post.
 
@@ -90,13 +88,13 @@ import { Skeleton, SkeletonGroup } from '@teamblind-chorus/ui';
 
 ## Slots
 
-- **container** — the tonal block. `sys.color.scrimSubtle` fill (translucent inverse-tone overlay — black in light, white in dark), shape-dependent radius. Carries the pulse animation. `role='status'` + `aria-live='polite'` so screen readers announce the loading state without yanking focus.
+- **container** — the tonal block. `sys.color.background.neutral` fill (translucent inverse-tone overlay — black in light, white in dark), shape-dependent radius. Carries the pulse animation. `role='status'` + `aria-live='polite'` so screen readers announce the loading state without yanking focus.
 
 ## Anatomy
 
 | Slot       | Token bindings |
 |------------|----------------|
-| container  | `sys.color.scrimSubtle` fill, `sys.radius.xs` corners (`text` / `block`) or `sys.radius.full` (`circle`), no stroke |
+| container  | `sys.color.background.neutral` fill, `sys.radius.xs` corners (`text` / `block`) or `sys.radius.full` (`circle`), no stroke |
 | text       | Default `ref.space.200` (16px) height × 100% width |
 | block      | Default `ref.space.1000` (80px) height × 100% width |
 | circle     | Default `ref.space.500` × `ref.space.500` (40 × 40) round |

package/agents/components/skeleton/skeleton.spec.json

@@ -2,7 +2,7 @@
   "$schema": "../../spec.schema.json",
   "name": "Skeleton",
   "family": "skeleton",
-  "description": "Single tonal placeholder block painted on `sys.color.scrimSubtle` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) with a slow opacity pulse (`0.5 → 1 → 0.5` over 1.6s). The translucent fill stays visible on every host surface tier, so the placeholder reads cleanly whether it sits on a plain page surface, an elevated container, a hero band, or a coloured card. Three shapes select the default footprint and corner radius: `text` (`ref.space.200` / 16px high, full-width — single line of body copy), `block` (`ref.space.1000` / 80px high, full-width — image / card body) and `circle` (`ref.space.500` × `ref.space.500` / 40 × 40, fully rounded — avatar). Consumer-supplied `width` / `height` props override the default footprint. Compose multiple Skeletons inside `SkeletonGroup` to mirror the rhythm of the content being loaded.",
+  "description": "Single tonal placeholder block painted on `sys.color.background.neutral` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) with a slow opacity pulse (`0.5 → 1 → 0.5` over 1.6s). The translucent fill stays visible on every host surface tier, so the placeholder reads cleanly whether it sits on a plain page surface, an elevated container, a hero band, or a coloured card. Three shapes select the default footprint and corner radius: `text` (`ref.space.200` / 16px high, full-width — single line of body copy), `block` (`ref.space.1000` / 80px high, full-width — image / card body) and `circle` (`ref.space.500` × `ref.space.500` / 40 × 40, fully rounded — avatar). Consumer-supplied `width` / `height` props override the default footprint. Compose multiple Skeletons inside `SkeletonGroup` to mirror the rhythm of the content being loaded.",
   "element": "span",
   "props": {
     "shape": {
@@ -32,12 +32,12 @@
   "slots": {
     "container": {
       "required": true,
-      "description": "Tonal block. `sys.color.scrimSubtle` fill (translucent black/white inverse-tone overlay — visible on every host surface), shape-dependent radius, no stroke. Carries the pulse animation. `role='status'` + `aria-live='polite'` so screen readers announce the loading state without yanking focus.",
+      "description": "Tonal block. `sys.color.background.neutral` fill (translucent black/white inverse-tone overlay — visible on every host surface), shape-dependent radius, no stroke. Carries the pulse animation. `role='status'` + `aria-live='polite'` so screen readers announce the loading state without yanking focus.",
       "intrinsic": true
     }
   },
   "sizing": {
-    "background": "sys.color.scrimSubtle",
+    "background": "sys.color.background.neutral",
     "radiusText": "sys.radius.xs",
     "radiusBlock": "sys.radius.xs",
     "radiusCircle": "sys.radius.full",
@@ -48,7 +48,7 @@
   },
   "appearances": {
     "default": {
-      "background": "sys.color.scrimSubtle",
+      "background": "sys.color.background.neutral",
       "note": "The only fill tone — Skeleton has no emphasis axis. Painted as a translucent ~8% inverse-tone overlay (black in light mode, white in dark) so the placeholder stays visible on every host surface tier (surface, surfaceContainer, surfaceContainerHigh, hero, …) without colliding with a fixed neutral step. The pulse modulates opacity, not hue, so the placeholder reads as anonymous chrome."
     }
   },
@@ -64,7 +64,7 @@
     "footprintOverrides": "`width` / `height` props win over the shape's default footprint, including for `circle` (a circle Skeleton at `width=60 height=60` stays a 60-rung round)."
   },
   "forbidden": [
-    "skeleton fill stepped to `sys.color.primary` or any chromatic tone — the placeholder must read as anonymous chrome, not as a content tone",
+    "skeleton fill stepped to `sys.color.background.primary` or any chromatic tone — the placeholder must read as anonymous chrome, not as a content tone",
     "shimmer / gradient sweep animation — Chorus skeletons modulate opacity only (one motion axis keeps the tier readable under reduced-motion fallback)",
     "skeleton stacked vertically without a SkeletonGroup wrapper — group via SkeletonGroup so the 8px gap stays consistent across compositions",
     "skeleton kept on-screen after the real content resolves — the placeholder must swap out atomically, not cross-fade with the loaded data",

package/agents/components/spinner/spinner.family.json

@@ -2,7 +2,7 @@
   "$schema": "../../family.schema.json",
   "family": "spinner",
   "name": "Spinner",
-  "description": "Indeterminate loading indicator — a rotating arc in `sys.color.primary` that signals a short, progress-unknown wait (under ~1 second of expected delay) on a neutral host surface. Two rungs ride the `icon.*` size ladder: `medium` (`sys.icon.lg` / 24px, default) and `small` (`sys.icon.md` / 16px). An optional `label` slot lets a single line of loading copy sit beside the arc. Reserved to one Spinner per view — for content-shaped waits use `skeleton`, for a known ratio use `progress`. Single-spec family.",
+  "description": "Indeterminate loading indicator — a rotating arc in `sys.color.background.primary` that signals a short, progress-unknown wait (under ~1 second of expected delay) on a neutral host surface. Two rungs ride the `icon.*` size ladder: `medium` (`sys.icon.lg` / 24px, default) and `small` (`sys.icon.md` / 16px). An optional `label` slot lets a single line of loading copy sit beside the arc. Reserved to one Spinner per view — for content-shaped waits use `skeleton`, for a known ratio use `progress`. Single-spec family.",
   "useCases": [
     "sub-second indeterminate wait (button submit, inline action)",
     "small surface where a skeleton would be heavier than the wait",

package/agents/components/spinner/spinner.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/spinner/spinner.md`](../../../i18n/ko/schema/components/spinner/spinner.md)
 
-An indeterminate loading indicator — a rotating arc in `sys.color.primary` over a faint `scrimSubtle` ring that signals a short, progress-unknown wait on a neutral host surface. Two rungs ride the `icon.*` ladder — `medium` (24px, default) and `small` (16px). Pass a `label` for a single line of loading copy beside the arc.
+An indeterminate loading indicator — a rotating arc in `sys.color.background.primary` over a faint `background.neutral` ring that signals a short, progress-unknown wait on a neutral host surface. Two rungs ride the `icon.*` ladder — `medium` (24px, default) and `small` (16px). Pass a `label` for a single line of loading copy beside the arc.
 
 **Reach for this when** a wait is brief and indeterminate (under ~1 second) — a button submit, an inline action, or a first-paint loader before a screen's data resolves — and a content-shaped placeholder would be heavier than the wait itself. **Skip when** the wait mirrors a known shape (use [Skeleton](../skeleton/skeleton.md)), the task has a measurable ratio (use [Progress](../progress/progress.md)), or the surface already shows another Spinner — reserve one per view.
 
@@ -20,9 +20,7 @@ import { Spinner } from '@teamblind-chorus/ui';
 <Spinner aria-label="Loading" />
 ```
 
-## Use cases
-
-### With label
+## Label
 
 A single line of loading copy beside the arc. The label doubles as the accessible name, so `aria-label` is not needed.
 
@@ -34,7 +32,7 @@ import { Spinner } from '@teamblind-chorus/ui';
 <Spinner label="Loading…" />
 ```
 
-### Small
+## Small
 
 The 16px rung — for tight inline affordances (a button label, a form-field affix) where the 24px default would crowd.
 
@@ -46,7 +44,7 @@ import { Spinner } from '@teamblind-chorus/ui';
 <Spinner size="small" aria-label="Loading" />
 ```
 
-### Centered
+## Centered
 
 A first-paint loader centered inside the surface that will hold the data. One Spinner per view.
 
@@ -63,18 +61,18 @@ import { Spinner } from '@teamblind-chorus/ui';
 ## Slots
 
 - **container** — inline-flex wrapper. Carries `role='status'` and the accessible name; holds the arc and the optional label, separated by `sys.layout.inline.sm`.
-- **arc** — the rotating ring. `sys.color.primary` foreground arc over a `sys.color.scrimSubtle` track ring, fully rounded, no stroke. Carries the spin animation. Decorative (`aria-hidden`).
-- **label** — optional single line of loading copy beside the arc. `sys.typo.body.sm`, `sys.color.onSurfaceVariant`.
+- **arc** — the rotating ring. `sys.color.background.primary` foreground arc over a `sys.color.background.neutral` track ring, fully rounded, no stroke. Carries the spin animation. Decorative (`aria-hidden`).
+- **label** — optional single line of loading copy beside the arc. `sys.typo.body.sm`, `sys.color.text.subtle`.
 
 ## Anatomy
 
 | Slot       | Token bindings |
 |------------|----------------|
 | container  | inline-flex, `sys.layout.inline.sm` gap between arc and label |
-| arc        | `sys.color.primary` foreground arc, `sys.color.scrimSubtle` track ring, `sys.radius.full`, no stroke |
+| arc        | `sys.color.background.primary` foreground arc, `sys.color.background.neutral` track ring, `sys.radius.full`, no stroke |
 | medium     | `sys.icon.lg` (24px) diameter — the default rung |
 | small      | `sys.icon.md` (16px) diameter |
-| label      | `sys.typo.body.sm`, `sys.color.onSurfaceVariant` |
+| label      | `sys.typo.body.sm`, `sys.color.text.subtle` |
 
 ## Sizes