@teamblind-chorus/ui 1.1.0 → 2.0.0

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

@@ -0,0 +1,27 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "spinner",
+  "name": "Spinner",
+  "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",
+    "centered first-paint loader before a screen's data resolves",
+    "loading copy beside a rotating indicator"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "spinner.md",
+  "usage": {
+    "note": "indeterminate only — never bind it to a progress ratio (use Progress). Reserve to one Spinner per view. aria-label defaults to 'Loading'; pass a label child for visible loading copy beside the arc.",
+    "example": "<Spinner aria-label=\"Loading\" />"
+  },
+  "subcomponents": [
+    {
+      "slug": "spinner",
+      "spec": "spinner.spec.json",
+      "md": "spinner.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/spinner/spinner.md

@@ -0,0 +1,96 @@
+# Spinner
+
+> 🇰🇷 한국어: [`i18n/ko/schema/components/spinner/spinner.md`](../../../i18n/ko/schema/components/spinner/spinner.md)
+
+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.
+
+**Layout inset.** `inline` — Spinner ships no padding or container chrome of its own. It sits as a leaf at the size of its rung; the host owns centering and surrounding rhythm. An optional label sits beside the arc with `sys.layout.inline.sm` between them.
+
+## Default
+
+A 24px rotating arc. `role='status'` announces the loading state; `aria-label` defaults to `'Loading'`.
+
+```preview
+spinner/default
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<Spinner aria-label="Loading" />
+```
+
+## Label
+
+A single line of loading copy beside the arc. The label doubles as the accessible name, so `aria-label` is not needed.
+
+```preview
+spinner/with-label
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<Spinner label="Loading…" />
+```
+
+## Small
+
+The 16px rung — for tight inline affordances (a button label, a form-field affix) where the 24px default would crowd.
+
+```preview
+spinner/small
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<Spinner size="small" aria-label="Loading" />
+```
+
+## Centered
+
+A first-paint loader centered inside the surface that will hold the data. One Spinner per view.
+
+```preview
+spinner/centered
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', justifyContent: 'center', padding: 'var(--sys-layout-container-xl)' }}>
+  <Spinner label="Loading…" />
+</div>
+```
+
+## 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.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.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.text.subtle` |
+
+## Sizes
+
+| Size     | Diameter            | When to reach |
+|----------|---------------------|---------------|
+| `medium` | `sys.icon.lg` (24px) | **Default**. Standalone or centered first-paint loaders. |
+| `small`  | `sys.icon.md` (16px) | Tight inline affordances — button labels, form-field affixes. |
+
+## States
+
+| State          | Animation                       | Notes |
+|----------------|---------------------------------|-------|
+| `default`      | `rotate 0.8s linear infinite`   | The arc spins continuously. Indeterminate — the rotation never reflects a value. |
+| reduced-motion | suppressed                      | Under `prefers-reduced-motion: reduce` the spin halts and the full ring shows statically. |
+
+## Behavior
+
+- **Indeterminate only.** The rotation never maps to a ratio — for a known percentage use [Progress](../progress/progress.md).
+- **One per view.** Reserve a single Spinner per screen; concurrent regional waits use [Skeleton](../skeleton/skeleton.md) or lift to one screen-level Spinner.
+- **Accessible name.** `role='status'` announces loading without interrupting focus. A visible `label` doubles as the name; otherwise `aria-label` (default `'Loading'`) carries it. The arc is decorative.
+- **Reduced motion.** Under `prefers-reduced-motion: reduce` the spin is suppressed; the full ring shows statically as a quiet loading mark.

package/agents/components/spinner/spinner.spec.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Spinner",
+  "family": "spinner",
+  "description": "A rotating arc that signals an indeterminate, sub-second wait on a neutral host surface. The arc paints in `sys.color.background.primary` as the foreground motion and spins continuously over a faint `sys.color.background.neutral` ring so the rotation reads on any surface tier. Two rungs ride the `icon.*` ladder — `medium` (`sys.icon.lg` / 24px, default) and `small` (`sys.icon.md` / 16px). An optional `label` slot places a single line of loading copy beside the arc. `role='status'` + an accessible name (`aria-label`, default `'Loading'`) announce the loading state. Indeterminate only — for a known ratio use Progress; for content-shaped waits use Skeleton.",
+  "element": "span",
+  "props": {
+    "size": {
+      "type": "enum",
+      "values": ["medium", "small"],
+      "default": "medium",
+      "description": "Selects the arc diameter off the `icon.*` ladder. `medium` paints at `sys.icon.lg` (24px); `small` at `sys.icon.md` (16px)."
+    },
+    "label": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional loading copy rendered beside the arc in `sys.typo.body.sm` / `sys.color.text.subtle`. When present it also supplies the accessible name, so `aria-label` is not required."
+    },
+    "aria-label": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label announced by screen readers. Defaults to `'Loading'`. Supply a more specific name (e.g. `'Signing in'`) when the wait scope is meaningful. Redundant when a visible `label` is passed."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Inline-flex wrapper carrying `role='status'` and the accessible name. Holds the arc and the optional label, separated by `sys.layout.inline.sm`.",
+      "intrinsic": true
+    },
+    "arc": {
+      "required": true,
+      "description": "The rotating ring. `sys.color.background.primary` foreground arc over a `sys.color.background.neutral` track ring, fully rounded, no stroke border. Carries the continuous spin animation. Decorative — `aria-hidden`.",
+      "intrinsic": true
+    },
+    "label": {
+      "required": false,
+      "description": "Optional single line of loading copy beside the arc. `sys.typo.body.sm`, `sys.color.text.subtle`.",
+      "omittedBehavior": "collapse"
+    }
+  },
+  "sizes": {
+    "medium": {
+      "diameter": "sys.icon.lg",
+      "labelTypo": "sys.typo.body.sm",
+      "gap": "sys.layout.inline.sm"
+    },
+    "small": {
+      "diameter": "sys.icon.md",
+      "labelTypo": "sys.typo.body.sm",
+      "gap": "sys.layout.inline.sm"
+    }
+  },
+  "appearances": {
+    "default": {
+      "arc": "sys.color.border.primary",
+      "track": "sys.color.background.neutral",
+      "label": "sys.color.text.subtle",
+      "note": "The only appearance. The foreground arc paints `sys.color.background.primary` for the motion accent; the track ring paints `sys.color.background.neutral` (a faint inverse-tone scrim — ~8% black light / ~8% white dark) so the rotation reads on any host surface tier. Spinner has no emphasis axis — for a higher-attention loading mark the emphasis belongs in adjacent copy, not in a chromatic arc swap."
+    }
+  },
+  "states": {
+    "default": {
+      "animation": "chorus-spinner-rotate 0.8s linear infinite",
+      "note": "The arc rotates continuously at 0.8s per turn (well below the WCAG flash threshold — rotation modulates position, not luminance). Indeterminate: the rotation never reflects a value. The animation respects `prefers-reduced-motion: reduce` — the spin halts and the full ring is shown statically as a quiet loading mark."
+    }
+  },
+  "behavior": {
+    "ariaStatus": "Container carries `role='status'` and the accessible name (visible `label` or `aria-label`, default `'Loading'`) so screen readers announce the loading state without yanking focus. The arc is decorative (`aria-hidden`).",
+    "reducedMotion": "Under `@media (prefers-reduced-motion: reduce)` the spin is suppressed; the full ring shows statically as a quiet loading mark.",
+    "singleInstance": "Reserve one Spinner per view. Concurrent regional waits stack visual noise — lift to a single screen-level Spinner or switch the inner waits to Skeleton.",
+    "labelComposition": "Pass `label` for visible loading copy beside the arc; it doubles as the accessible name. Without a label, `aria-label` (default `'Loading'`) carries the announcement."
+  },
+  "forbidden": [
+    "Spinner bound to a known progress ratio / percentage — indeterminate only; a determinate value belongs to `progress`",
+    "more than one Spinner visible in a single view — reserve to one per view; concurrent regional waits use `skeleton` or lift to a single screen-level Spinner",
+    "Spinner used as a content-shaped placeholder (list row, feed card, avatar) — that role is `skeleton`, which mirrors the footprint of the data being fetched",
+    "arc painted with a non-token hex / raw px diameter — the arc tone is `sys.color.background.primary` and the diameter rides the `icon.*` ladder (`sys.icon.md` / `sys.icon.lg`)",
+    "shimmer / gradient sweep on the arc — Spinner modulates rotation only (one motion axis keeps it readable under the reduced-motion fallback)",
+    "arc track or ring drawn with a `border:` — the ring draws as a `box-shadow` / conic fill, not a layout stroke"
+  ]
+}