@teamblind-chorus/ui 1.2.0 → 2.0.0

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

@@ -2,7 +2,7 @@
   "$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.primary` as the foreground motion and spins continuously over a faint `sys.color.scrimSubtle` 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.",
+  "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": {
@@ -14,7 +14,7 @@
     "label": {
       "type": "node",
       "optional": true,
-      "description": "Optional loading copy rendered beside the arc in `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. When present it also supplies the accessible name, so `aria-label` is not required."
+      "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",
@@ -30,12 +30,12 @@
     },
     "arc": {
       "required": true,
-      "description": "The rotating ring. `sys.color.primary` foreground arc over a `sys.color.scrimSubtle` track ring, fully rounded, no stroke border. Carries the continuous spin animation. Decorative — `aria-hidden`.",
+      "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.onSurfaceVariant`.",
+      "description": "Optional single line of loading copy beside the arc. `sys.typo.body.sm`, `sys.color.text.subtle`.",
       "omittedBehavior": "collapse"
     }
   },
@@ -53,10 +53,10 @@
   },
   "appearances": {
     "default": {
-      "arc": "sys.color.primary",
-      "track": "sys.color.scrimSubtle",
-      "label": "sys.color.onSurfaceVariant",
-      "note": "The only appearance. The foreground arc paints `sys.color.primary` for the motion accent; the track ring paints `sys.color.scrimSubtle` (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."
+      "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": {
@@ -75,7 +75,7 @@
     "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.primary` and the diameter rides the `icon.*` ladder (`sys.icon.md` / `sys.icon.lg`)",
+    "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"
   ]

package/agents/components/status-tag/status-tag.md

@@ -10,7 +10,7 @@ A small inline status pill — a tonal mark sized for the trailing edge of a row
 
 ## Default
 
-The `neutral` appearance — `sys.color.scrimSubtle` fill (the translucent inverse-tone scrim — ~8% black in light, ~8% white in dark) with `onSurfaceVariant` foreground. The quiet informational state.
+The `neutral` appearance — `sys.color.background.neutral` fill (the translucent inverse-tone scrim — ~8% black in light, ~8% white in dark) with `onSurfaceVariant` foreground. The quiet informational state.
 
 ```preview
 status-tag/default
@@ -20,9 +20,7 @@ import { StatusTag } from '@teamblind-chorus/ui';
 <StatusTag>Pending</StatusTag>
 ```
 
-## Use cases
-
-### Error
+## Error
 
 The `error` appearance — `errorContainer` fill with an `onErrorContainer` foreground. The rejection / blocked / failed state.
 
@@ -34,7 +32,7 @@ import { StatusTag } from '@teamblind-chorus/ui';
 <StatusTag appearance="error">Rejected</StatusTag>
 ```
 
-### On a list row
+## List row
 
 The canonical pairing — a `list/thumbnail` row whose label carries a trailing StatusTag with a `sys.layout.container.2xs` (4px) inline gap. The gap belongs to the label column; StatusTag carries no outer margin.
 
@@ -70,7 +68,7 @@ import { List, StatusTag, Thumbnail } from '@teamblind-chorus/ui';
 />
 ```
 
-### Inline in a paragraph
+## Inline
 
 A StatusTag tucked inline inside a paragraph or a feed-post header. Same 4px gap rule: the host column owns the whitespace, StatusTag stays a bare pill.
 
@@ -79,7 +77,7 @@ status-tag/inline
 ---
 import { StatusTag } from '@teamblind-chorus/ui';
 
-<p style={{ font: '14px var(--sys-typo-fontFamily)', color: 'var(--sys-color-onSurface)' }}>
+<p style={{ font: '14px var(--sys-typo-fontFamily)', color: 'var(--sys-color-text-default)' }}>
   Shared document <StatusTag>Pending</StatusTag> is awaiting review.
 </p>
 ```
@@ -101,8 +99,8 @@ import { StatusTag } from '@teamblind-chorus/ui';
 
 | Appearance | Container fill                                                              | Foreground                       | When to reach                                                                  |
 |------------|-----------------------------------------------------------------------------|----------------------------------|-------------------------------------------------------------------------------|
-| `neutral`  | `sys.color.scrimSubtle` (translucent inverse-tone scrim — ~8% black light / ~8% white dark) | `sys.color.onSurfaceVariant`     | Quiet informational default — visible on every surface tier. In-progress / awaiting states — "pending", "draft", "queued", "in review". |
-| `error`    | `sys.color.errorContainer`                                                  | `sys.color.onErrorContainer`     | Rejection / blocked / failed state. Use sparingly. |
+| `neutral`  | `sys.color.background.neutral` (translucent inverse-tone scrim — ~8% black light / ~8% white dark) | `sys.color.text.subtle`     | Quiet informational default — visible on every surface tier. In-progress / awaiting states — "pending", "draft", "queued", "in review". |
+| `error`    | `sys.color.background.danger`                                                  | `sys.color.text.danger`     | Rejection / blocked / failed state. Use sparingly. |
 
 ## States
 

package/agents/components/status-tag/status-tag.spec.json

@@ -40,13 +40,13 @@
   },
   "appearances": {
     "neutral": {
-      "background": "sys.color.scrimSubtle",
-      "foreground": "sys.color.onSurfaceVariant",
-      "note": "The quiet informational default. Background paints `sys.color.scrimSubtle` — the translucent inverse-tone scrim (~8% black in light, ~8% white in dark) shared with Chip / Tag default, Progress track, and Skeleton — so the pill stays visible against every surface tier in either theme. Pair with statuses that describe an in-progress / awaiting state — 'pending', 'draft', 'queued', 'in review'."
+      "background": "sys.color.background.neutral",
+      "foreground": "sys.color.text.subtle",
+      "note": "The quiet informational default. Background paints `sys.color.background.neutral` — the translucent inverse-tone scrim (~8% black in light, ~8% white in dark) shared with Chip / Tag default, Progress track, and Skeleton — so the pill stays visible against every surface tier in either theme. Pair with statuses that describe an in-progress / awaiting state — 'pending', 'draft', 'queued', 'in review'."
     },
     "error": {
-      "background": "sys.color.errorContainer",
-      "foreground": "sys.color.onErrorContainer",
+      "background": "sys.color.background.danger",
+      "foreground": "sys.color.text.danger",
       "note": "The rejection / blocked / failed state. Pair with statuses that describe a terminal negative outcome — 'rejected', 'failed', 'blocked'. Keep usage scarce — every error pill on a screen competes with the others for attention."
     }
   },

package/agents/components/suggestion-list/suggestion-list.md

@@ -30,11 +30,9 @@ import { SuggestionList } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
+## Header action
 
-### With header action
-
-Extends the header with a trailing `accent` Text Button when the screen has a broader index page to route to.
+Extends the header with a trailing `accent` Text Button when the screen has a broader index page to route to. Surfaces the entity-agnostic anatomy — the same row shape carries a suggested person instead of a channel.
 
 ```preview
 suggestion-list/with-header-action
@@ -46,8 +44,6 @@ import { SuggestionList } from '@teamblind-chorus/ui';
   headerAction={{ label: 'See all', href: '/channels' }}
   items={[
     { value: 'jordan',  name: 'Jordan Lee',     followers: '342 Followers',  description: 'PM at a logistics startup. Mostly here for the threads on roadmap reviews.', thumbnail: { alt: 'Jordan Lee' } },
-    { value: 'taylor',  name: 'Taylor Brooks',  followers: '1.1K Followers', description: 'Frontend engineer. Writes about the bits between the framework and the user.', thumbnail: { alt: 'Taylor Brooks' } },
-    { value: 'morgan',  name: 'Morgan Park',    followers: '512 Followers',  description: 'Designer-turned-PM. Notes on the handoff layer.', thumbnail: { alt: 'Morgan Park' } },
   ]}
 />
 ```
@@ -72,7 +68,7 @@ import { SuggestionList } from '@teamblind-chorus/ui';
 | headerAction   | Header's trailing `xsmall` [Text Button](../button/text.md), `accent` appearance |
 | pager          | Horizontal scroll, `scroll-snap-type: x mandatory`, scrollbar hidden; `sys.layout.inline.xl` (16/24px) gap. Re-pays the 16 left rail via `padding-left: sys.layout.container.md` (+ matching `scroll-padding-left` snap-port); the full-bleed host means the pager spans the surface so the next-page peek reaches the trailing edge intrinsically (no negative margin). When embedded in a padded host (Feed), the pager re-adds `margin-inline: -sys.layout.container.md` to pierce the host's rail. |
 | page           | `flex: 0 0 calc(100% - sys.layout.inline.xl - sys.layout.inline.md)` so the next page leading edge shows by 8px; `scroll-snap-align: start`; `sys.layout.stack.sm` (12px) between rows |
-| row            | [list/entry](../list/entry.md)-shaped row at `xlarge` rung — 56 avatar, `inline.lg` gap, label.md primary / label.sm `secondary` + `description`. Keeps the list/entry native `container.md` inline padding (tap target) and adds `margin-inline: -container.md` so the visible content (avatar / toggle) sits flush at the page boundaries — the avatar reads at 16 from the surface, aligned with the header label. SuggestionList adds: 12px bottom padding + `::after` divider 1px / `outlineVariant` anchored at the text column (standalone: `container.md` 16 + `ref.space.700` 56 + `inline.lg` 12 = 84px from row left; embedded: 68px since the row's inline padding + margin are zeroed). |
+| row            | [list/entry](../list/entry.md)-shaped row at `xlarge` rung — 56 avatar, `inline.lg` gap, label.md primary / label.sm `secondary` + `description`. Keeps the list/entry native `container.md` inline padding (tap target) and adds `margin-inline: -container.md` so the visible content (avatar / toggle) sits flush at the page boundaries — the avatar reads at 16 from the surface, aligned with the header label. SuggestionList adds: 12px bottom padding + `::after` divider 1px / `border.default` anchored at the text column (standalone: `container.md` 16 + `ref.space.700` 56 + `inline.lg` 12 = 84px from row left; embedded: 68px since the row's inline padding + margin are zeroed). |
 | trailingAction | [Toggle Button](../button/toggle.md), `variant="toggle"` — composed into the row's `trailingIcon` slot. |
 
 ## States

package/agents/components/suggestion-list/suggestion-list.spec.json

@@ -79,17 +79,17 @@
     }
   },
   "sizing": {
-    "containerFill": "sys.color.surface",
+    "containerFill": "sys.color.surface.default",
     "containerPaddingBlock": "sys.layout.container.lg",
     "containerPaddingInline": "0",
     "containerPaddingInlineNote": "Full-bleed: the host pays no inline padding. The Header pays the 16 inline rail (sys.layout.container.md) and the pager re-pays it via padding-left.",
     "headerToPagerGap": "sys.layout.stack.md",
     "headerToPagerGapNote": "Header's own block-end (stack.md = 16) is the header↔pager gap; the host gap collapses to 0 (matches DirectoryList).",
     "labelTypo": "sys.typo.heading.md",
-    "labelColor": "sys.color.onSurface",
-    "headerActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' — label paints in sys.color.primary via the Text Button accent token.",
+    "labelColor": "sys.color.text.default",
+    "headerActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' — label paints in sys.color.background.primary via the Text Button accent token.",
     "headerActionTypo": "sys.typo.label.sm",
-    "headerActionColor": "sys.color.primary",
+    "headerActionColor": "sys.color.text.link",
     "pageGap": "sys.layout.inline.xl",
     "pagePeek": "sys.layout.inline.md",
     "pageRowGap": "sys.layout.stack.sm",
@@ -98,7 +98,7 @@
     "rowBottomPadding": "sys.layout.stack.sm",
     "rowBottomPaddingNote": "The bottom padding sits between the row's text content and the hairline divider so the divider reads as a separator rather than a baseline rule.",
     "dividerWidth": "sys.borderWidth.hairline",
-    "dividerColor": "sys.color.outlineVariant",
+    "dividerColor": "sys.color.border.default",
     "dividerInset": "calc(sys.layout.container.md + ref.space.700 + sys.layout.inline.lg) = 84px from the row's leading edge in standalone mode — anchors to the start of the row's text column so the divider aligns with the column, not the avatar. Embedded mode re-anchors to 68px (drops the container.md term) since the row's inline padding + negative margin are zeroed."
   },
   "rowProps": {
@@ -123,7 +123,7 @@
       "required": true,
       "agentRequired": true,
       "omittedBehavior": "error",
-      "fallbackOnMissingSrc": "sys.color.surfaceContainerHigh",
+      "fallbackOnMissingSrc": "sys.color.surface.sunken",
       "description": "Forwarded to Thumbnail verbatim — src, alt, updateDot, logoBadge. Agents MUST pass `src`; fill `/placeholder.png` when no real subject is implied. `fallbackOnMissingSrc` is the runtime safety net for load failures, not a scaffold-time omission license."
     },
     "active": {
@@ -147,12 +147,8 @@
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "outerLayerPosition": "depth 0..2px from the row edge (the outer stroke)",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset",
-      "insetLayerPosition": "depth 2..3px from the row edge (the counter-ring just inside the outer stroke)",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "implementation": "inset box-shadow constrained strictly inside the row's footprint."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"

package/agents/components/switch/switch.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/switch/switch.md`](../../../i18n/ko/schema/components/switch/switch.md)
 
-A binary active/inactive control — a pill-shaped track with a circular thumb that translates between ends. **Inactive** reads as a `scrimSubtle` track with an `outlineVariant` hairline and a fixed-white thumb; **active** paints the track in `primary` so the contract reads chromatically without an inline label.
+A binary active/inactive control — a pill-shaped track with a circular thumb that translates between ends. **Inactive** reads as a `icon.subtlest` track with an `border.default` hairline and a fixed-white thumb; **active** paints the track in `primary` so the contract reads chromatically without an inline label.
 
 **Reach for this when** a setting commits the moment it changes — notifications, privacy toggles, *show in feed*, instant-commit list trailing. **Skip when** the commit needs confirmation (use [Button](../button/button.md) + [Dialog](../dialog/dialog.md)), when the user picks one of several options ([List/radio](../list/radio.md), [Tabs](../tabs/tabs.md)), or when destructive — Switch carries no undo.
 
@@ -10,7 +10,7 @@ A binary active/inactive control — a pill-shaped track with a circular thumb t
 
 ## Inactive
 
-The resting state — a `scrimSubtle` track (inverse-tone ~8% tint: black in light, white in dark) with an `outlineVariant` hairline and a fixed-white thumb at the leading end. The tint stays distinct on any host surface tier. The specimen below is pinned to this type (rendered `checked={false}`); see [Behavior](#behavior) for the live toggle contract.
+The resting state — a `icon.subtlest` track (inverse-tone ~8% tint: black in light, white in dark) with an `border.default` hairline and a fixed-white thumb at the leading end. The tint stays distinct on any host surface tier. The specimen below is pinned to this type (rendered `checked={false}`); see [Behavior](#behavior) for the live toggle contract.
 
 ```preview
 switch/inactive
@@ -32,9 +32,7 @@ import { Switch } from '@teamblind-chorus/ui';
 <Switch checked aria-label="Notifications" />
 ```
 
-## Use cases
-
-### With label
+## Label
 
 The canonical pairing — a visible label to the left, `sys.layout.inline.md` (12px) gap. The label carries the accessible name via `htmlFor` + `id` or `aria-labelledby`; Switch drops `aria-label`.
 
@@ -52,16 +50,16 @@ import { Switch } from '@teamblind-chorus/ui';
     padding: 'var(--sys-layout-container-xs) var(--sys-layout-container-md)',
   }}
 >
-  <span id="notif-label" className="sys-typo-body-sm" style={{ color: 'var(--sys-color-onSurface)' }}>
+  <span id="notif-label" className="sys-typo-body-sm" style={{ color: 'var(--sys-color-text-default)' }}>
     Push notifications
   </span>
   <Switch checked aria-labelledby="notif-label" />
 </div>
 ```
 
-### Focus indicator
+## Focus ring
 
-Outward 3-layer ring on the track's outer edge, shown on the inactive specimen. The card is pinned to its focused state via `forcedState="focused"`; in production the ring triggers on `:focus-visible` (keyboard / programmatic focus, never a plain mouse click).
+Outward single ring on the track's outer edge, shown on the inactive specimen. The card is pinned to its focused state via `forcedState="focused"`; in production the ring triggers on `:focus-visible` (keyboard / programmatic focus, never a plain mouse click).
 
 ```preview
 switch/focused
@@ -80,10 +78,10 @@ import { Switch } from '@teamblind-chorus/ui';
 
 | Slot             | Token bindings |
 |------------------|----------------|
-| track (inactive) | `sys.color.scrimSubtle` fill, hairline `outlineVariant` stroke, fully rounded |
-| track (active)   | `sys.color.primary` fill, no stroke, fully rounded |
+| track (inactive) | `sys.color.background.neutral` fill, hairline `border.default` stroke, fully rounded |
+| track (active)   | `sys.color.background.primary` fill, no stroke, fully rounded |
 | thumb (inactive) | `ref.palette.white.1000` (fixed white) fill, 28 × 28, fully rounded, 2px inset from leading edge |
-| thumb (active)   | `sys.color.onPrimary` fill, 28 × 28, translated 20px to the trailing end |
+| thumb (active)   | `sys.color.text.onFill` fill, 28 × 28, translated 20px to the trailing end |
 | transition       | 120ms `ease-out` on track-fill, thumb-fill, and thumb-translate |
 
 ## Appearance
@@ -92,8 +90,8 @@ A single appearance — no emphasis axis. The visible variation is the `data-sta
 
 | State    | Track fill          | Track stroke              | Thumb fill                             |
 |----------|---------------------|---------------------------|----------------------------------------|
-| inactive | `sys.color.scrimSubtle` | `outlineVariant` hairline | `ref.palette.white.1000` (fixed white) |
-| active   | `sys.color.primary`     | none                      | `sys.color.onPrimary`                  |
+| inactive | `sys.color.background.neutral` | `border.default` hairline | `ref.palette.white.1000` (fixed white) |
+| active   | `sys.color.background.primary`     | none                      | `sys.color.text.onFill`                  |
 
 ## States
 
@@ -106,7 +104,7 @@ A single appearance — no emphasis axis. The visible variation is the `data-sta
 
 ## Focus indicator
 
-Outward 3-layer ring on the track's outer edge via an `::after` overlay. Trigger: `:focus-visible`. Switch sits inline next to siblings with whitespace around it, so outward reads cleanly — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+Outward single ring on the track's outer edge via an `::after` overlay. Trigger: `:focus-visible`. Switch sits inline next to siblings with whitespace around it, so outward reads cleanly — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
 
 ## Behavior
 

package/agents/components/switch/switch.spec.json

@@ -2,7 +2,7 @@
   "$schema": "../../spec.schema.json",
   "name": "Switch",
   "family": "switch",
-  "description": "Pill-shaped track (52 × 32) with a circular thumb (28 × 28) that translates between the two ends. Inactive paints a `scrimSubtle` track (inverse-tone ~8% tint that stays distinct on any host surface) with an `outlineVariant` hairline stroke and a fixed-white thumb (`ref.palette.white.1000`, identical in light and dark); active paints the track in `primary` and the thumb in `onPrimary` so the active state reads chromatically. Whole control is the click target — the thumb is decorative. Instant commit: `onCheckedChange` fires the moment the thumb moves.",
+  "description": "Pill-shaped track (52 × 32) with a circular thumb (28 × 28) that translates between the two ends. Inactive paints a `icon.subtlest` track (a muted neutral grey that stays distinct on any host surface) with an `border.default` hairline stroke and a fixed-white thumb (`ref.palette.white.1000`, identical in light and dark); active paints the track in `primary` and the thumb in `onPrimary` so the active state reads chromatically. Whole control is the click target — the thumb is decorative. Instant commit: `onCheckedChange` fires the moment the thumb moves.",
   "element": "button",
   "props": {
     "checked": {
@@ -62,21 +62,21 @@
     "thumbTravel": "ref.space.250",
     "thumbRadius": "sys.radius.full",
     "outlineWidth": "sys.borderWidth.hairline",
-    "outlineColor": "sys.color.outlineVariant",
+    "outlineColor": "sys.color.border.default",
     "transitionDuration": "120ms",
     "transitionTiming": "ease-out"
   },
   "appearances": {
     "inactive": {
-      "trackBackground": "sys.color.scrimSubtle",
-      "trackOutline": "sys.color.outlineVariant",
+      "trackBackground": "sys.color.icon.subtlest",
+      "trackOutline": "sys.color.border.default",
       "thumbBackground": "ref.palette.white.1000",
-      "note": "Resting state. The track fills with `scrimSubtle` — an inverse-tone ~8% tint (black in light, white in dark) — so it stays distinct on every host surface tier without binding to a fixed neutral step, reinforced by the hairline outline. The thumb is fixed white (`ref.palette.white.1000`) so it reads identically in light and dark rather than dimming to a surface tone."
+      "note": "Resting state. The track fills with `icon.subtlest` — a muted neutral grey that stays distinct on every host surface tier, reinforced by the hairline outline. The thumb is fixed white (`ref.palette.white.1000`) so it reads identically in light and dark rather than dimming to a surface tone."
     },
     "active": {
-      "trackBackground": "sys.color.primary",
+      "trackBackground": "sys.color.background.primary",
       "trackOutline": "transparent",
-      "thumbBackground": "sys.color.onPrimary",
+      "thumbBackground": "sys.color.text.onFill",
       "note": "Chromatic active state. The outline disappears so the filled track reads as one solid block. Thumb steps to `onPrimary` so the contrast against the filled track stays legible."
     }
   },
@@ -92,26 +92,25 @@
       "focusRing": {
         "composition": "outward",
         "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
-        "innerCounterRing": { "width": "sys.borderWidth.hairline", "color": "sys.color.focusInset" },
-        "outerRing": { "width": "sys.borderWidth.thin", "color": "sys.color.focus" }
+        "innerCounterRing": { "width": "sys.borderWidth.hairline", "color": "sys.color.border.focused" },
+        "outerRing": { "width": "sys.borderWidth.thin", "color": "sys.color.border.focused" }
       },
-      "note": "Keyboard-focus (:focus-visible) visual — a three-layer outward ring on the track's outer edge, with no state-overlay tint (the ring alone carries focus here). Mirrors the `focusIndicator` block for spec-only renderers. Composes over the lifecycle state the control is in."
+      "note": "Keyboard-focus (:focus-visible) visual — a single outward ring on the track's outer edge, with no state-overlay tint (the ring alone carries focus here). Mirrors the `focusIndicator` block for spec-only renderers. Composes over the lifecycle state the control is in."
     },
     "disabled": {
-      "containerOpacity": "sys.state.disabled",
+      "trackBackground": "sys.color.icon.disabled",
+      "trackOutline": "sys.color.border.bold",
       "pointerEvents": "none",
-      "note": "Both the active and inactive appearance fade to `sys.state.disabled`. The thumb stays at the position dictated by `checked`."
+      "note": "Explicit disabled (no opacity): track to icon.disabled (both checked and unchecked), hairline outline to border.bold; the thumb stays white at the position set by checked."
     }
   },
   "focusIndicator": {
-    "description": "Keyboard-focus visual painted as a three-layer outward ring on the track's outer edge.",
+    "description": "Keyboard-focus visual painted as a single outward ring on the track's outer edge.",
     "composition": "outward",
     "compositionReason": "Switch sits inline next to siblings with whitespace around it (form rows, settings list trailing slots); an outward ring reads cleanly without colliding with neighbouring affordances.",
     "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",
       "implementation": "outset box-shadow on the track's `::after` overlay."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
@@ -123,7 +122,7 @@
   },
   "forbidden": [
     "switch used for an action that needs confirmation (a destructive commit, an action with an undo) — wrap that in a Button + Dialog instead",
-    "track outline removed in the inactive state — the `scrimSubtle` fill and the hairline outline work together to hold the affordance on any host surface; dropping the outline weakens the edge on tiers where the tint reads faint",
+    "track outline removed in the inactive state — the `icon.subtlest` fill and the hairline outline work together to hold the affordance on any host surface; dropping the outline weakens the edge on tiers where the tint reads faint",
     "inactive thumb dimmed to a surface tone — it stays fixed white (`ref.palette.white.1000`) so it reads the same in light and dark",
     "thumb rendered as a separate focusable / clickable element — only the track carries focus and click",
     "trailing label or icon painted inside the track — the active/inactive contract is the whole control; any label sits outside the Switch (in a List row label, a FormField label, etc.)",

package/agents/components/tab-bar/tab-bar.md

@@ -33,11 +33,9 @@ import { HomeIcon, HomeFillIcon, BuildingIcon, BuildingFillIcon, SearchIcon, Bri
 />
 ```
 
-## Use cases
+## Primary item
 
-### With a primary "Create" item
-
-A bar including a primary-coloured Create affordance at the trailing end. The icon ([`PlusSquareFillIcon`](../../icons/svg/PlusSquareFill.svg)) is painted in `sys.color.brand` via `appearance="primary"` and still occupies one equal-width slot.
+A bar including a primary-coloured Create affordance at the trailing end. The icon ([`PlusSquareFillIcon`](../../icons/svg/PlusSquareFill.svg)) is painted in `sys.color.text.brand` via `appearance="primary"` and still occupies one equal-width slot.
 
 ```preview
 tab-bar/with-primary
@@ -59,7 +57,7 @@ import { HomeIcon, HomeFillIcon, BuildingIcon, BuildingFillIcon, SearchIcon, Sea
 />
 ```
 
-### Three-destination bar
+## Three destinations
 
 A bar with a smaller destination set — `space-evenly` distribution scales to any item count.
 
@@ -80,7 +78,7 @@ import { HomeIcon, HomeFillIcon, SearchIcon, SearchFillIcon, ProfileIcon, Profil
 />
 ```
 
-### Truncation
+## Truncation
 
 Labels exceeding their slot truncate with a single-line ellipsis — a safety net for long i18n strings.
 
@@ -103,7 +101,7 @@ import { HomeIcon, HomeFillIcon, BuildingIcon, BuildingFillIcon, SearchIcon, Sea
 />
 ```
 
-### Focus indicator
+## Focus specimen
 
 Static specimen — pins the keyboard-focus ring to a single destination. See top-level [Focus indicator](#focus-indicator).
 
@@ -137,11 +135,11 @@ import { HomeIcon, HomeFillIcon, BuildingIcon, BuildingFillIcon, SearchIcon, Sea
 
 | Slot      | Token bindings                                                                                       |
 |-----------|------------------------------------------------------------------------------------------------------|
-| container | `surface` fill; top hairline `outlineVariant` divider (inset shadow); `display: flex` + `justify-content: space-evenly` |
+| container | `surface` fill; top hairline `border.default` divider (inset shadow); `display: flex` + `justify-content: space-evenly` |
 | item      | Flex column, icon over label; `flex: 1 1 0` with `max-width: 80px`; tap target is the full slot. State layer is a `sys.radius.md` rounded rectangle filling the slot |
-| icon      | `sys.color.onSurfaceVariant` → `sys.color.onSurface` (active) |
-| label     | `sys.typo.caption` (10 / Semibold); `onSurfaceVariant` → `onSurface` (active) |
-| primary   | When `appearance="primary"`, only the icon paints in `sys.color.brand`; the label stays in the bar's default `sys.color.onSurfaceVariant` so every label across the row reads as one rung. Pair with a filled-tile glyph (e.g. [`PlusSquareFillIcon`](../../icons/svg/PlusSquareFill.svg)) |
+| icon      | `sys.color.text.subtle` → `sys.color.text.default` (active) |
+| label     | `sys.typo.label.xs` (10 / Semibold); `onSurfaceVariant` → `onSurface` (active) |
+| primary   | When `appearance="primary"`, only the icon paints in `sys.color.text.brand`; the label stays in the bar's default `sys.color.text.subtle` so every label across the row reads as one rung. Pair with a filled-tile glyph (e.g. [`PlusSquareFillIcon`](../../icons/svg/PlusSquareFill.svg)) |
 
 ## Sizes
 

package/agents/components/tab-bar/tab-bar.spec.json

@@ -54,7 +54,7 @@
     }
   },
   "sizing": {
-    "containerFill": "sys.color.surface",
+    "containerFill": "sys.color.surface.default",
     "containerMinHeight": "56px",
     "containerPaddingBlock": "0",
     "containerPaddingBlockEnd": "env(safe-area-inset-bottom, 0px)",
@@ -63,7 +63,7 @@
     "containerJustifyContent": "space-evenly",
     "containerTopDivider": {
       "width": "sys.borderWidth.hairline",
-      "color": "sys.color.outlineVariant",
+      "color": "sys.color.border.default",
       "implementation": "inset box-shadow on the container (does not contribute to layout)"
     },
     "itemFlex": "1 1 0",
@@ -72,17 +72,17 @@
     "itemPaddingInline": "0",
     "itemIconLabelGap": "sys.layout.stack.3xs",
     "iconSize": "sys.icon.lg",
-    "labelTypo": "sys.typo.caption",
+    "labelTypo": "sys.typo.label.xs",
     "labelOverflow": "ellipsis (overflow: hidden; text-overflow: ellipsis; white-space: nowrap)",
     "stateLayerInset": "0",
     "stateLayerRadius": "sys.radius.md"
   },
   "appearance": {
-    "itemInactiveColor": "sys.color.onSurfaceVariant",
-    "itemActiveColor": "sys.color.onSurface",
-    "itemPrimaryIconColor": "sys.color.brand",
-    "itemPrimaryLabelColor": "sys.color.onSurfaceVariant",
-    "note": "Primary (`appearance='primary'`) items paint only the icon in `sys.color.brand`; the label stays in the bar's default `onSurfaceVariant` so every label across the row reads as one rung."
+    "itemInactiveColor": "sys.color.text.subtle",
+    "itemActiveColor": "sys.color.text.default",
+    "itemPrimaryIconColor": "sys.color.text.brand",
+    "itemPrimaryLabelColor": "sys.color.text.subtle",
+    "note": "Primary (`appearance='primary'`) items paint only the icon in `sys.color.text.brand`; the label stays in the bar's default `onSurfaceVariant` so every label across the row reads as one rung."
   },
   "itemProps": {
     "value": {
@@ -117,7 +117,7 @@
         "primary"
       ],
       "optional": true,
-      "description": "Paint the icon in `sys.color.brand` — the 'Create' / 'Compose' commit affordance. Pair with a filled-tile glyph (e.g. PlusSquareFillIcon) so the icon's own shape provides the tile and the brand fill paints it as the commit colour. The label stays in the bar's default `onSurfaceVariant` so the row's labels read as one rung — only the icon carries the brand emphasis. Primary items invoke a screen-covering overlay, NOT a sibling destination — they render in the fill glyph by default, never receive `aria-current='page'`, and never animate outline → fill (no resting/active states inside the bar)."
+      "description": "Paint the icon in `sys.color.text.brand` — the 'Create' / 'Compose' commit affordance. Pair with a filled-tile glyph (e.g. PlusSquareFillIcon) so the icon's own shape provides the tile and the brand fill paints it as the commit colour. The label stays in the bar's default `onSurfaceVariant` so the row's labels read as one rung — only the icon carries the brand emphasis. Primary items invoke a screen-covering overlay, NOT a sibling destination — they render in the fill glyph by default, never receive `aria-current='page'`, and never animate outline → fill (no resting/active states inside the bar)."
     },
     "forcedState": {
       "type": "literal",
@@ -136,55 +136,53 @@
     },
     "hovered": {
       "description": "Pointer over the item. State layer fills the slot, painted with `onSurface` at `sys.state.hover` (8%).",
-      "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.hover)"
+      "stateLayerFill": "color-mix(sys.color.text.default, sys.state.hover)"
     },
     "pressed": {
       "description": "Active press on the item. State layer fills the slot, painted with `onSurface` at `sys.state.pressed` (12%).",
-      "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.pressed)"
+      "stateLayerFill": "color-mix(sys.color.text.default, sys.state.pressed)"
     },
     "focused": {
-      "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.focus)",
+      "stateLayerFill": "color-mix(sys.color.text.default, sys.state.focus)",
       "focusRing": {
         "composition": "inward",
         "layer": "::after/::before overlay — position:absolute, inset:0, inset box-shadow, no reflow (DESIGN.md Focus ring composition)",
         "innerCounterRing": {
           "width": "sys.borderWidth.hairline",
-          "color": "sys.color.focusInset"
+          "color": "sys.color.border.focused"
         },
         "outerRing": {
           "width": "sys.borderWidth.thin",
-          "color": "sys.color.focus"
+          "color": "sys.color.border.focused"
         }
       },
-      "note": "Keyboard-focus (:focus-visible) visual. State layer fills the slot with `onSurface` at `sys.state.focus` (12%); the three-layer ring is forced inward (adjacent items are flush under flex:1 1 0). Mirrors the `focusIndicator` block for spec-only renderers. Single-focus: at most one item holds the ring."
+      "note": "Keyboard-focus (:focus-visible) visual. State layer fills the slot with `onSurface` at `sys.state.focus` (12%); the single ring is forced inward (adjacent items are flush under flex:1 1 0). Mirrors the `focusIndicator` block for spec-only renderers. Single-focus: at most one item holds the ring."
     },
     "active": {
       "description": "Currently selected destination. Filled glyph (`activeIcon`) + label, both at `onSurface`. Carries `aria-current='page'`. No persistent state layer — only hover / pressed / focus paint."
     },
     "disabled": {
-      "containerOpacity": "sys.state.disabled",
-      "pointerEvents": "none"
+      "icon": "sys.color.icon.disabled",
+      "label": "sys.color.text.disabled",
+      "pointerEvents": "none",
+      "note": "Explicit disabled (no opacity): glyph to icon.disabled, label to text.disabled. The bar surface is untouched."
     }
   },
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the item is in. The state layer beneath is filled with `onSurface` at `sys.state.focus` (12%). Single-focus: at most one item holds the ring at a time, arriving via `:focus-visible` (keyboard `Tab` / programmatic focus).",
     "composition": "inward",
     "compositionReason": "Adjacent items are flush under `flex: 1 1 0`; an outward ring would overlap the neighbouring slot. The ring is constrained strictly inside the slot's bounding box and never exceeds it.",
-    "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.focus)",
+    "stateLayerFill": "color-mix(sys.color.text.default, sys.state.focus)",
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "outerLayerPosition": "depth 0..2px from the slot edge (the outer stroke)",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset",
-      "insetLayerPosition": "depth 2..3px from the slot edge (the counter-ring just inside the outer stroke)",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "composition": "inward — inset box-shadow on the ::after at `inset: 0`. Adjacent items are flush under `flex: 1 1 0`, so an outward ring would overlap a neighbour; the ring is forced inside the slot bounds without exceeding them."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },
   "behavior": {
     "selectionNavigates": "Tapping a destination item routes the app to that destination's page; `value` updates to mark the new active item. The selected item swaps its glyph from the outline form to the filled companion (`activeIcon`) to signal 'you are here' — the icon fill, paired with the `onSurface` colour swap on icon + label, is the bar's primary current-location indicator.",
-    "primaryItemIsAnOverlayAction": "Items with `appearance='primary'` (the conventional Create / Compose affordance) invoke a screen-covering overlay rather than navigating to a sibling destination, so they have no resting/active distinction inside the bar. They render in the fill-type glyph by default (painted in `sys.color.brand`) and never receive `aria-current='page'` or the outline→fill transition. Activation dismisses or replaces the current view via the host framework's overlay/modal route, not via tab-bar selection.",
+    "primaryItemIsAnOverlayAction": "Items with `appearance='primary'` (the conventional Create / Compose affordance) invoke a screen-covering overlay rather than navigating to a sibling destination, so they have no resting/active distinction inside the bar. They render in the fill-type glyph by default (painted in `sys.color.text.brand`) and never receive `aria-current='page'` or the outline→fill transition. Activation dismisses or replaces the current view via the host framework's overlay/modal route, not via tab-bar selection.",
     "distribution": "Capped equal-grow plus optical alignment. Every item uses `flex: 1 1 0` with `max-width: 80px`, so items grow at the same rate up to an 80-wide cap. Once every item has hit the cap, the row's leftover inline space is handed to the container's `justify-content: space-evenly`, which paints start padding, inter-item gap, and end padding as the same visible whitespace. `min-width: 0` on the item lets the label's ellipsis truncation actually take effect inside the slot.",
     "labelTruncation": "Labels that exceed their slot truncate with a single-line ellipsis (`overflow: hidden; text-overflow: ellipsis; white-space: nowrap`). The row never wraps or scrolls.",
     "fixedRow": "Author destinations to a five- or six-item ceiling so the per-slot width stays wide enough for the destination's short name to read without ellipsis at the system's narrowest mobile breakpoint.",
@@ -192,9 +190,9 @@
     "noNativeHomeBar": "The component renders just the bar itself; it does not draw or reserve space for an OS-level home indicator. The host shell handles safe-area inset and pinning."
   },
   "forbidden": [
-    "Create item not styled with sys.color.brand fill — the Create entry is the single brand-marked instance per screen",
+    "Create item not styled with sys.color.text.brand fill — the Create entry is the single brand-marked instance per screen",
     "more than one Create / brand-marked item — brand instance cap on this row is exactly 1",
     "tab-bar height different from the spec'd geometry — the row geometry is fixed across all routes",
-    "active state for non-Create items painted with brand color — non-Create items use sys.color.onSurface for both rest and active (active darkens via state overlay, not by color swap)"
+    "active state for non-Create items painted with brand color — non-Create items use sys.color.text.default for both rest and active (active darkens via state overlay, not by color swap)"
   ]
 }