@teamblind-chorus/ui 1.2.0 → 2.0.0

package/agents/components/tabs/rounded.md

@@ -24,9 +24,7 @@ import { Tabs, Tab } from '@teamblind-chorus/ui';
 </Tabs>
 ```
 
-## Use cases
-
-### With icon
+## Leading icon
 
 Canonical sort/filter row — each tab pairs a leading glyph (`sys.icon.md`, 16px) with its label. All glyphs draw from `@teamblind-chorus/ui/icons` so the row carries no inline SVG.
 
@@ -44,7 +42,7 @@ import { PulseIcon, StarIcon, HeartIcon, BookmarkIcon } from '@teamblind-chorus/
 </Tabs>
 ```
 
-### Icon only
+## Icon only
 
 Glyph-only tab — collapses to a clean 32×32 square (inline padding 12 → 8). Requires `aria-label`.
 
@@ -61,7 +59,7 @@ import { StarIcon, BookmarkIcon, HeartIcon } from '@teamblind-chorus/ui/icons';
 </Tabs>
 ```
 
-### Overflow
+## Overflow
 
 When natural width exceeds the column, the row scrolls horizontally. Trailing edge fade (48px / `ref.space.600`) paints via `mask-image` only while overflow is present.
 
@@ -82,7 +80,7 @@ import { PulseIcon, StarIcon, HeartIcon, BookmarkIcon, TagIcon, ProfileIcon, Men
 </Tabs>
 ```
 
-### Focus indicator
+## Focused tab
 
 Static specimen — pins the focus ring to the selected tab. See top-level [Focus indicator](#focus-indicator).
 
@@ -111,8 +109,8 @@ Selected/unselected pairs are inherited verbatim from [Filter chip's variants](.
 
 | Prop / state           | Container                          | Label color                       | Border (always 1px `sys.borderWidth.hairline`)                          |
 |------------------------|------------------------------------|-----------------------------------|-------------------------------------------------------------------------|
-| **Tab — unselected**   | `transparent`                      | `sys.color.onSurface`             | `sys.color.outlineVariant`                                              |
-| **Tab — selected**     | `sys.color.inverseSurface`         | `sys.color.inverseOnSurface`      | `transparent` — 1px width held so footprint never changes between states |
+| **Tab — unselected**   | `transparent`                      | `sys.color.text.default`             | `sys.color.border.default`                                              |
+| **Tab — selected**     | `sys.color.background.inverse`         | `sys.color.text.inverse`      | `transparent` — 1px width held so footprint never changes between states |
 
 ## Sizes
 

package/agents/components/tabs/rounded.spec.json

@@ -77,16 +77,16 @@
   "selectionStates": {
     "unselected": {
       "background": "transparent",
-      "label": "sys.color.onSurface",
+      "label": "sys.color.text.default",
       "border": {
         "width": "sys.borderWidth.hairline",
-        "color": "sys.color.outlineVariant"
+        "color": "sys.color.border.default"
       },
       "note": "Transparent fill so the tab adopts whatever surface sits behind it — page, raised card, sheet — without pinning to a fixed neutral step. Inherited from Filter chip's unselected recipe."
     },
     "selected": {
-      "background": "sys.color.inverseSurface",
-      "label": "sys.color.inverseOnSurface",
+      "background": "sys.color.background.inverse",
+      "label": "sys.color.text.inverse",
       "border": null
     }
   },
@@ -116,20 +116,26 @@
         "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. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the tab is in; never via plain mouse click."
     },
     "disabled": {
       "overlay": null,
-      "containerOpacity": "sys.state.disabled",
+      "background": "sys.color.background.disabled",
+      "label": "sys.color.text.disabled",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.border.bold"
+      },
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): neutral disabled fill + bold border so the shape reads on any surface, plus disabled label. Overrides the rest/selected appearance."
     }
   },
   "focusIndicator": {
@@ -141,12 +147,8 @@
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "outerLayerPosition": "depth 0..2px from the tab edge (the outer stroke)",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset",
-      "insetLayerPosition": "depth 2..3px from the tab edge (the counter-ring just inside the outer stroke)",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "implementation": "inset box-shadow on the tab's `::after` overlay. Constrained strictly inside the tab's footprint and never exceeds it."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
@@ -154,6 +156,6 @@
   "forbidden": [
     "rounded tabs given raw <button>/<a> or bare-text children instead of <Tab value=…> elements — the chip chrome (chorus-chip--filter + chorus-chip--rounded), the selected state, and the aria-selected/data-value binding all live on <Tab>; raw children render unstyled with no selected state",
     "rounded tab radius set to sys.radius.full (pill) — the rounded variant is the sys.radius.md (8) soft-rectangle; reach for Segmented when a capsule row is needed",
-    "active state painted with sys.color.brand — rounded tabs use sys.color.inverseSurface fill + sys.color.inverseOnSurface label in selected state"
+    "active state painted with sys.color.text.brand — rounded tabs use sys.color.background.inverse fill + sys.color.text.inverse label in selected state"
   ]
 }

package/agents/components/tabs/segmented.md

@@ -23,9 +23,7 @@ import { Tabs, Tab } from '@teamblind-chorus/ui';
 </Tabs>
 ```
 
-## Use cases
-
-### With icon
+## Leading icon
 
 Leading glyph in each segment — useful when the verb alone could read as anything.
 
@@ -41,7 +39,7 @@ import { CheckedIcon, PlusIcon } from '@teamblind-chorus/ui/icons';
 </Tabs>
 ```
 
-### Overflow
+## Overflow
 
 When natural width exceeds the column, the row scrolls horizontally — no `fullWidth` (equal-width segments would break the shared-density contract with Filter chips). Trailing **Edge fade** (rightmost **48px** / `ref.space.600`) paints via `mask-image` only while overflow is present.
 
@@ -61,7 +59,7 @@ import { Tabs, Tab } from '@teamblind-chorus/ui';
 </Tabs>
 ```
 
-### Focus indicator
+## Focused segment
 
 Static specimen — pins the focus ring to a selected segment. See top-level [Focus indicator](#focus-indicator).
 
@@ -83,7 +81,7 @@ import { Tabs, Tab } from '@teamblind-chorus/ui';
 
 ## Anatomy
 
-Each segment renders with `chorus-chip chorus-chip--filter` — see [Filter chip](../chip/filter.md). Selected swaps from unselected (`transparent` fill + `outlineVariant` border + `onSurface` label) to selected (`inverseSurface` fill + `inverseOnSurface` label, border `transparent` with 1px width held).
+Each segment renders with `chorus-chip chorus-chip--filter` — see [Filter chip](../chip/filter.md). Selected swaps from unselected (`transparent` fill + `border.default` border + `onSurface` label) to selected (`inverseSurface` fill + `inverseOnSurface` label, border `transparent` with 1px width held).
 
 Chip behaviour inherited verbatim — except the focus ring, re-anchored as an inset overlay on a `::after` layer (segmented row is a horizontal scroller; the chip's default outward ring would clip).
 

package/agents/components/tabs/segmented.spec.json

@@ -67,7 +67,7 @@
   },
   "selectionStates": {
     "$ref": "../chip/filter.spec.json#/selectionStates",
-    "note": "Each segment swaps between Filter chip's unselected (surfaceContainerHigh + outlineVariant border) and selected (inverseSurface + inverseOnSurface) recipes."
+    "note": "Each segment swaps between Filter chip's unselected (surfaceContainerHigh + border.default border) and selected (inverseSurface + inverseOnSurface) recipes."
   },
   "states": {
     "$ref": "../chip/filter.spec.json#/states",
@@ -82,19 +82,15 @@
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "outerLayerPosition": "depth 0..2px from the segment edge (the outer stroke)",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset",
-      "insetLayerPosition": "depth 2..3px from the segment edge (the counter-ring just inside the outer stroke)",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "implementation": "inset box-shadow on the segment's `::after` overlay. Constrained strictly inside the segment's footprint and never exceeds it."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },
   "forbidden": [
     "segmented control given raw <button>/<a> or bare-text children instead of <Tab value=…> elements — the chip chrome, the selected pill state, and the aria-selected/data-value binding all live on <Tab>; raw children render unstyled with no selected state",
-    "active item painted with sys.color.primary fill — segmented active uses sys.color.surface fill on the selected pill (the rest of the row is surfaceContainer)",
+    "active item painted with sys.color.background.primary fill — segmented active uses sys.color.surface.default fill on the selected pill (the rest of the row is surfaceContainer)",
     "segmented row reflowing on selection — anatomy is no-layout"
   ]
 }

package/agents/components/tabs/underline.md

@@ -24,9 +24,7 @@ import { Tabs, Tab } from '@teamblind-chorus/ui';
 </Tabs>
 ```
 
-## Use cases
-
-### With icon
+## Leading icon
 
 A leading glyph before the label.
 
@@ -43,7 +41,7 @@ import { PlusIcon, CheckedIcon } from '@teamblind-chorus/ui/icons';
 </Tabs>
 ```
 
-### Auto-fit
+## Auto-fit
 
 Wider terminal layout of Adaptive width — tabs share row width equally; indicator widens to match.
 
@@ -59,7 +57,7 @@ import { Tabs, Tab } from '@teamblind-chorus/ui';
 </Tabs>
 ```
 
-### Overflow
+## Overflow
 
 Narrower terminal layout — tabs hold content width and the row scrolls. The trailing 48px (`ref.space.600`) paints as a transparent `mask-image` edge fade; clears when scrolled to the last tab.
 
@@ -79,7 +77,7 @@ import { Tabs, Tab } from '@teamblind-chorus/ui';
 </Tabs>
 ```
 
-### Focus indicator
+## Focused tab
 
 Static specimen — pins the keyboard-focus ring to the selected tab. See top-level [Focus indicator](#focus-indicator).
 
@@ -104,9 +102,9 @@ import { Tabs, Tab } from '@teamblind-chorus/ui';
 
 | Prop / state           | Container          | Label color                           | Indicator                         |
 |------------------------|--------------------|---------------------------------------|-----------------------------------|
-| **Tab — unselected**   | transparent        | `sys.color.outline` (muted foreground) | none                  |
-| **Tab — selected**     | transparent        | `sys.color.onSurface` (strong foreground) | 2px `sys.borderWidth.thin` × `sys.color.onSurface` along the bottom edge |
-| **Container row**      | transparent, 16px inline padding, 1px `sys.color.outlineVariant` bottom divider running the full row width. Selected indicator paints over this divider. Edge fade (rightmost 48px / `ref.space.600`) paints via `mask-image` only while overflow is present. | — | — |
+| **Tab — unselected**   | transparent        | `sys.color.border.boldest` (muted foreground) | none                  |
+| **Tab — selected**     | transparent        | `sys.color.text.default` (strong foreground) | 2px `sys.borderWidth.thin` × `sys.color.text.default` along the bottom edge |
+| **Container row**      | transparent, 16px inline padding, 1px `sys.color.border.default` bottom divider running the full row width. Selected indicator paints over this divider. Edge fade (rightmost 48px / `ref.space.600`) paints via `mask-image` only while overflow is present. | — | — |
 
 ## Sizes
 
@@ -120,7 +118,7 @@ A single fixed rung — the 40px footprint stays constant across breakpoints.
 | Inter-tab gap                     | 0                    | — †                                |
 | Slot gap (icon ↔ label)           | 4px                  | `sys.layout.inline.sm`             |
 | Indicator height                  | 2px                  | `sys.borderWidth.thin`              |
-| Container bottom divider          | 1px                  | `sys.borderWidth.hairline` × `sys.color.outlineVariant` |
+| Container bottom divider          | 1px                  | `sys.borderWidth.hairline` × `sys.color.border.default` |
 | Label                             | 14 / Semibold        | `sys.typo.label.md`                |
 | Icon                              | 16px                 | `sys.icon.md`                      |
 | Edge fade width                   | 48px                 | `ref.space.600` — trailing `mask-image`, on overflow only |
@@ -136,7 +134,7 @@ A single fixed rung — the 40px footprint stays constant across breakpoints.
 | `default`  | —                          | Container + label at rest.                                                  |
 | `hovered`  | `sys.state.hover` (8%)     | Pointer-driven via `:hover`.                                                |
 | `pressed`  | `sys.state.pressed` (16%)  | Pointer-driven via `:active`.                                               |
-| `selected` | —                          | Label flips to `sys.color.onSurface`; 2px indicator slides to the new tab.   |
+| `selected` | —                          | Label flips to `sys.color.text.default`; 2px indicator slides to the new tab.   |
 | `disabled` | overlay suppressed         | Label at `sys.state.disabled` (40%) opacity, focus ring suppressed, `cursor: not-allowed`. |
 
 ## Focus indicator

package/agents/components/tabs/underline.spec.json

@@ -3,7 +3,7 @@
   "name": "Tabs",
   "family": "tabs",
   "subcomponent": "underline",
-  "description": "Horizontal tab row with a single 2px (`sys.borderWidth.thin`) `sys.color.onSurface` indicator that slides between the active tab's bottom edge on selection. Default content-section switcher.",
+  "description": "Horizontal tab row with a single 2px (`sys.borderWidth.thin`) `sys.color.border.selected` indicator that slides between the active tab's bottom edge on selection. Default content-section switcher.",
   "element": "div",
   "props": {
     "variant": {
@@ -72,19 +72,19 @@
     "slotGap": "sys.layout.inline.sm",
     "indicatorHeight": "sys.borderWidth.thin",
     "dividerWidth": "sys.borderWidth.hairline",
-    "dividerColor": "sys.color.outlineVariant",
+    "dividerColor": "sys.color.border.default",
     "labelTypo": "sys.typo.label.md",
     "iconSize": "sys.icon.md",
     "fadeWidth": "ref.space.600"
   },
   "selectionStates": {
     "unselected": {
-      "label": "sys.color.outline",
+      "label": "sys.color.text.subtle",
       "indicator": null
     },
     "selected": {
-      "label": "sys.color.onSurface",
-      "indicator": "sys.color.onSurface"
+      "label": "sys.color.text.default",
+      "indicator": "sys.color.border.selected"
     }
   },
   "states": {
@@ -113,20 +113,22 @@
         "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. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the tab is in; never via plain mouse click."
     },
     "disabled": {
       "overlay": null,
-      "containerOpacity": "sys.state.disabled",
+      "label": "sys.color.text.disabled",
+      "indicator": null,
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): label drops to text.disabled, no indicator. Sits on a neutral surface so the disabled text token reads directly."
     }
   },
   "focusIndicator": {
@@ -138,19 +140,15 @@
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "outerLayerPosition": "depth 0..2px from the tab edge (the outer stroke)",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset",
-      "insetLayerPosition": "depth 2..3px from the tab edge (the counter-ring just inside the outer stroke)",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "implementation": "inset box-shadow on the tab's `::after` overlay (sits above the state-overlay `::before`, the label/icon, and the underline indicator). Constrained strictly inside the tab's footprint and never exceeds it."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },
   "forbidden": [
     "underline tabs given raw <button>/<a> or bare-text children instead of <Tab value=…> elements — the sliding indicator (.chorus-tabs__indicator), the useAdaptiveFit measurement that sets data-fit, the aria-selected/data-value binding, and the active label styling all live on <Tab>; raw children render as unstyled run-together text with no indicator and a broken scroll/stretch layout",
-    "active indicator painted with sys.color.brand — underline uses sys.color.onSurface for the indicator",
+    "active indicator painted with sys.color.text.brand — underline uses sys.color.border.selected for the indicator",
     "tabs wrapped in extra horizontal padding — tabs is full-bleed by family declaration",
     "tab label sizing below sys.typo.label.md (14px) — smaller text breaks Korean / CJK hierarchy",
     "manual underline drawn via `border-bottom:` — indicator is the `::after` overlay, not a real border"

package/agents/components/thumbnail/thumbnail.md

@@ -20,9 +20,7 @@ import { Thumbnail } from '@teamblind-chorus/ui';
 <Thumbnail size={48} alt="Channel" src="/placeholder.png" />
 ```
 
-## Use cases
-
-### With update dot
+## Update dot
 
 A `brand`-tone dot at the top-right flags new activity. Decorative; the row carries the count in a sibling text slot.
 
@@ -34,7 +32,7 @@ import { Thumbnail } from '@teamblind-chorus/ui';
 <Thumbnail size={48} alt="Channel" src="/placeholder.png" updateDot />
 ```
 
-### With logo badge
+## Logo badge
 
 A 16 × 16 sub-brand mark at the bottom-right on its own surface halo.
 
@@ -51,7 +49,7 @@ import { Thumbnail } from '@teamblind-chorus/ui';
 />
 ```
 
-### With both badges
+## Both badges
 
 Top-right and bottom-right corners are independent and never collide.
 
@@ -69,7 +67,7 @@ import { Thumbnail } from '@teamblind-chorus/ui';
 />
 ```
 
-### With surface outline
+## Surface outline
 
 `outlined` paints a 2-token (`sys.borderWidth.thin`) `sys.color.surface` halo as an outset `box-shadow` around the container. The ring blends into the host's `surface*` tier and separates the circle's edge from anything visually noisy underneath. Painted as a shadow, not a `border:` — the rung's diameter never reflows.
 
@@ -87,7 +85,7 @@ import { Thumbnail } from '@teamblind-chorus/ui';
 
 The two corner badges (`updateDot`, `logoBadge`) carry their own 1-token surface halos and compose cleanly over the outlined ring — order is image → outlined ring → badge halos → badge fills, all painted as `box-shadow` so footprint never changes.
 
-### Size ladder
+## Size ladder
 
 The full ladder side-by-side; update-dot steps down at the 32-rung boundary.
 

package/agents/components/thumbnail/thumbnail.spec.json

@@ -43,7 +43,7 @@
     "outlined": {
       "type": "boolean",
       "default": false,
-      "description": "When `true`, paints a 2-token-wide `sys.color.surface` outline around the Thumbnail container as an outset halo. The outline reads as an isolation ring that separates the Thumbnail's circular edge from anything visually noisy underneath it. Painted as `box-shadow: 0 0 0 sys.borderWidth.thin sys.color.surface` so it never reflows the slot's intrinsic diameter — same no-layout-stroke idiom the rest of the system uses. Pair with hosts whose chrome reads as a `surface*` tier (so the halo blends in) and whose backdrop differs from that tier (so the halo actually separates).",
+      "description": "When `true`, paints a 2-token-wide `sys.color.surface.default` outline around the Thumbnail container as an outset halo. The outline reads as an isolation ring that separates the Thumbnail's circular edge from anything visually noisy underneath it. Painted as `box-shadow: 0 0 0 sys.borderWidth.thin sys.color.surface.default` so it never reflows the slot's intrinsic diameter — same no-layout-stroke idiom the rest of the system uses. Pair with hosts whose chrome reads as a `surface*` tier (so the halo blends in) and whose backdrop differs from that tier (so the halo actually separates).",
       "whenToReachForIt": [
         "The Thumbnail half-overlaps or sits over an image — [ProfileHeader](../profile-header/profile-header.md) avatar (56-rung on cover band), [Profile carousel](../carousel/profile.md) avatar (64-rung on card cover), any avatar pulled onto a Hero / Cover photo.",
         "The backdrop is a brand-tonal strip, a `*Container` fill, or a gradient band ([Banner](../banner/banner.md) inside a colour-tinted host, a Section painted with a `successContainer` / `errorContainer` / `brandContainer` fill).",
@@ -90,24 +90,24 @@
     "containerRadius": "sys.radius.full",
     "containerOutline": {
       "appliesWhen": "props.outlined === true",
-      "color": "sys.color.surface",
+      "color": "sys.color.surface.default",
       "width": "sys.borderWidth.thin",
       "rendering": "box-shadow (outset, 0 0 0 width color) so the halo never reflows the slot's intrinsic diameter — same no-layout-stroke contract every other Chorus surface follows. Pairs the halo with the host's `surface*` tier so the ring blends into the chrome around it while separating the Thumbnail from a contrasting backdrop (cover image, brand tonal strip, gradient band)."
     },
-    "imageFallbackFill": "sys.color.surfaceContainerHigh",
+    "imageFallbackFill": "sys.color.surface.sunken",
     "imageFallbackImage": "/placeholder.png",
     "imageFallbackImageRendering": "background-image, cover, center — paints under the runtime <img>; visible only when the inline image is missing or fails to load, so the slot still resolves to an image rather than an empty surface tone.",
-    "imageFallbackGlyphColor": "sys.color.onSurfaceVariant",
-    "updateDotFill": "sys.color.brand",
+    "imageFallbackGlyphColor": "sys.color.text.subtle",
+    "updateDotFill": "sys.color.text.brand",
     "updateDotRadius": "sys.radius.full",
     "updateDotHalo": {
-      "color": "sys.color.surface",
+      "color": "sys.color.surface.default",
       "width": "sys.borderWidth.hairline",
       "rendering": "box-shadow"
     },
     "logoBadgeRadius": "sys.radius.full",
     "logoBadgeHalo": {
-      "color": "sys.color.surface",
+      "color": "sys.color.surface.default",
       "width": "sys.borderWidth.hairline",
       "rendering": "box-shadow"
     }
@@ -155,7 +155,7 @@
   "behavior": {
     "slotOmissionCollapses": "Both badges (updateDot, logoBadge) drop out of the layout entirely when absent — no reserved corner whitespace.",
     "badgesOverlay": "Both badges are absolutely positioned over the image; the container's overall footprint is the image's diameter regardless of whether the badges are present. The 1px surface halo is rendered as a box-shadow.",
-    "outlinedHalo": "When `outlined={true}`, the container paints a 2-token (`sys.borderWidth.thin`) `sys.color.surface` halo via `box-shadow` — outset of the diameter, never reflowing the slot. The corner badges' own 1-token halos are layered above it. Composes cleanly with `updateDot` and `logoBadge`.",
+    "outlinedHalo": "When `outlined={true}`, the container paints a 2-token (`sys.borderWidth.thin`) `sys.color.surface.default` halo via `box-shadow` — outset of the diameter, never reflowing the slot. The corner badges' own 1-token halos are layered above it. Composes cleanly with `updateDot` and `logoBadge`.",
     "imageClip": "Container's radius.full plus overflow: hidden clips the image to a perfect circle even when the source is rectangular.",
     "noTextFallback": "Slot only renders <img> content — there is no text fallback. When `src` is omitted or the server fails to deliver the image, the slot's background paints the bundled `/placeholder.png` over a `surfaceContainerHigh` base. The placeholder is the image-area's runtime safety net for load failures; design-time scaffolds should pass the same URL through `src` explicitly so the contract is visible in the composition rather than hidden in the CSS layer.",
     "updateDotBreakpoint": "Dot drops from 8×8 (at and above rung 32, including 56) to 4×4 (rungs 24 / 20 / 16) so it reads as highlight, not occluder, on the smaller diameters.",

package/agents/components/toast/toast.md

@@ -22,9 +22,7 @@ import { Toast } from '@teamblind-chorus/ui';
 <Toast>Token copied to clipboard</Toast>
 ```
 
-## Use cases
-
-### With action
+## Action
 
 A small Text Button (`appearance="inverse"`) on the trailing edge for follow-through (Undo, Retry, View). With the trailing slot present, the toast stays on screen longer (~6s). The Button node is passed directly so the call site spells out the sub-component.
 
@@ -42,7 +40,7 @@ import { Toast, Button } from '@teamblind-chorus/ui';
 </Toast>
 ```
 
-### With dismiss
+## Dismiss
 
 A medium Icon Button (`appearance="inverse"`) on the trailing edge for explicit dismissal — used when the toast carries information the user may want to read at their own pace. Composed at the call site so the `appearance="inverse"` binding stays visible.
 
@@ -66,7 +64,7 @@ import { XIcon } from '@teamblind-chorus/ui/icons';
 </Toast>
 ```
 
-### Max width
+## Max width
 
 Strip grows until it hits the 400 cap (or viewport-minus-safe-area on narrow screens). Past that, the body wraps onto a second line rather than letting the strip stretch into a banner.
 
@@ -78,7 +76,7 @@ import { Toast } from '@teamblind-chorus/ui';
 <Toast>Saved your draft to every workspace you joined this month</Toast>
 ```
 
-### Truncation
+## Truncation
 
 Body wraps up to two lines and truncates with an ellipsis past that — body, trailing button, and any leading glyph stay vertically centred. Pair with a trailing dismiss when the message is status the user may want to read at their own pace.
 
@@ -108,7 +106,7 @@ A single appearance — inverse. The inverse pair (`inverseSurface` / `inverseOn
 
 | Appearance | Container fill              | Foreground                       | When to use |
 |------------|-----------------------------|----------------------------------|-------------|
-| `default`  | `sys.color.inverseSurface`  | `sys.color.inverseOnSurface`     | Every toast. Status messages that must read against any surface tier in the stack. |
+| `default`  | `sys.color.background.inverse`  | `sys.color.text.inverse`     | Every toast. Status messages that must read against any surface tier in the stack. |
 
 ## Slots
 

package/agents/components/toast/toast.spec.json

@@ -66,8 +66,8 @@
   },
   "appearances": {
     "default": {
-      "background": "sys.color.inverseSurface",
-      "foreground": "sys.color.inverseOnSurface",
+      "background": "sys.color.background.inverse",
+      "foreground": "sys.color.text.inverse",
       "note": "The inverse pair is the only appearance — toasts always read as a contrasting strip against the page. Action buttons inside an inverse surface fall back to the regular primary family per the inverse-cluster contract."
     }
   },
@@ -76,7 +76,7 @@
     "role": "Container carries role='status' and aria-live='polite' so screen readers announce the confirmation without interrupting the user's current focus."
   },
   "forbidden": [
-    "Toast painted with sys.color.surface — toast uses sys.color.inverseSurface fill + inverseOnSurface text",
+    "Toast painted with sys.color.surface.default — toast uses sys.color.background.inverse fill + inverseOnSurface text",
     "Toast as a blocking commit prompt — destructive prompts use Dialog or BottomSheet; toast is for non-blocking feedback",
     "Toast persistent (no auto-dismiss)",
     "More than one toast stacked — toast queue is single-at-a-time",

package/agents/components/tooltip/tooltip.md

@@ -18,9 +18,7 @@ import { Tooltip } from '@teamblind-chorus/ui';
 <Tooltip placement="top">Tooltip text</Tooltip>
 ```
 
-## Use cases
-
-### Inverse
+## Inverse
 
 The dark-cluster bubble. Reach for it when the host screen is already saturated with `primary` tone — the inverse cluster (`inverseSurface` / `inverseOnSurface`) reads as a distinct floating note above the page.
 
@@ -32,7 +30,7 @@ import { Tooltip } from '@teamblind-chorus/ui';
 <Tooltip placement="top" appearance="inverse">Tooltip text</Tooltip>
 ```
 
-### With action
+## Action
 
 A small Text Button for follow-through ("Learn more", "Got it"). Bind the button's `appearance` to match the tooltip — `onPrimary` for the default (brand-blue) tooltip; `inverse` for the inverse tooltip.
 
@@ -50,7 +48,7 @@ import { Tooltip, Button } from '@teamblind-chorus/ui';
 </Tooltip>
 ```
 
-### Multi-line with action
+## Multi-line action
 
 When the body grows past the 300 cap, the body wraps onto a second line and the action slot drops below the body. The body-to-action gap goes from 12 (inline) to 6 (block) so the stacked action reads as part of the same group.
 
@@ -68,7 +66,7 @@ import { Tooltip, Button } from '@teamblind-chorus/ui';
 </Tooltip>
 ```
 
-### Placements
+## Placements
 
 Six placements, named `<edge>` or `<edge>-<align>`. The `<edge>` axis (top / bottom) places the bubble above or below the trigger and chooses the caret edge; the `<align>` axis (start / center / end) shifts the caret along the parallel axis.
 
@@ -93,8 +91,8 @@ Two appearances — `default` (the canonical brand-blue tooltip) and `inverse` (
 
 | Appearance | Container fill              | Foreground                       | Pair the action button with                                   | When to use |
 |------------|-----------------------------|----------------------------------|---------------------------------------------------------------|-------------|
-| `default`  | `sys.color.primary`         | `sys.color.onPrimary`            | `<Button variant="text" appearance="onPrimary">`              | The canonical tooltip — brand-blue bubble, always-white label. |
-| `inverse`  | `sys.color.inverseSurface`  | `sys.color.inverseOnSurface`     | `<Button variant="text" appearance="inverse">`                | When the host screen is saturated with `primary` tone — the dark inverse bubble reads as distinct floating chrome. |
+| `default`  | `sys.color.background.primary`         | `sys.color.text.onFill`            | `<Button variant="text" appearance="onPrimary">`              | The canonical tooltip — brand-blue bubble, always-white label. |
+| `inverse`  | `sys.color.background.inverse`  | `sys.color.text.inverse`     | `<Button variant="text" appearance="inverse">`                | When the host screen is saturated with `primary` tone — the dark inverse bubble reads as distinct floating chrome. |
 
 `default` is the right reach in most cases; switch to `inverse` only when the surrounding surface gives the brand-blue bubble no breathing room.
 

package/agents/components/tooltip/tooltip.spec.json

@@ -80,14 +80,14 @@
   },
   "appearances": {
     "default": {
-      "background": "sys.color.primary",
-      "foreground": "sys.color.onPrimary",
+      "background": "sys.color.background.primary",
+      "foreground": "sys.color.text.onFill",
       "elevation": "sys.elevation.overlay",
       "note": "Brand-blue bubble with an always-white label. Both `primary` and `onPrimary` are theme-stable, so the bubble reads the same in light and dark mode. Action buttons inside this appearance MUST use `Button variant=\"text\" appearance=\"onPrimary\"` so the label stays white in either theme — `appearance=\"inverse\"` flips with the theme and would render the label dark in dark mode."
     },
     "inverse": {
-      "background": "sys.color.inverseSurface",
-      "foreground": "sys.color.inverseOnSurface",
+      "background": "sys.color.background.inverse",
+      "foreground": "sys.color.text.inverse",
       "elevation": "sys.elevation.overlay",
       "note": "Inverse-cluster bubble for screens already saturated with primary tone, where the `default` brand-blue tooltip would compete with the surrounding chrome. Action buttons inside this appearance use `Button variant=\"text\" appearance=\"inverse\"` so the label flips with the host fill."
     }