@teamblind-chorus/ui 1.1.0 → 2.0.0

package/agents/components/banner/banner.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/banner/banner.md`](../../../i18n/ko/schema/components/banner/banner.md)
 
-An in-body explanation block — a tinted card sitting within the reading flow with an optional heading line, a short paragraph, and an optional follow-through link. Four axes: **appearance** (`default` / `accent` / `destructive`), **outline** (`outlined` / none), **leading slot** (`icon` / `thumbnail` / none), **trailing slot** (`trailingIcon` / none).
+An in-body explanation block — a tinted card sitting within the reading flow with an optional heading line, a short paragraph, and an optional follow-through link. Five axes: **appearance** (`default` / `accent` / `destructive`), **foreground** (tonal, or `neutralBody` to lay the Default neutral text over the accent fill), **outline** (`outlined` / none), **leading slot** (`icon` / `thumbnail` / none), **trailing slot** (`trailingIcon` / `trailingAction` Text Button / none).
 
 **Reach for this when** a passage needs a brief aside the reader can scan or skip. **Skip when** the message demands a decision ([Dialog](../dialog/dialog.md) / [Bottom sheet](../bottom-sheet/bottom-sheet.md)) or confirms a recent user action ([Toast](../toast/toast.md)).
 
@@ -25,9 +25,7 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-## Use cases
-
-### Accent
+## Accent
 
 The primary-tinted appearance. Body and action both paint in the primary family — reach for it when the aside should pull more attention.
 
@@ -44,7 +42,26 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-### Destructive
+## Neutral body
+
+The `accent` fill kept, but the copy re-toned to the **Default** appearance's neutral foreground — title + body in `sys.color.text.default`, action stepping to `sys.color.background.primary`. Pass `neutralBody`. This decouples the background tone from the text tone: the `primaryContainer` tint still pulls the eye, but the copy reads as quiet, high-legibility body text rather than tonal `onPrimaryContainer`. Reach for it on longer explainers or denser asides where primary-family body copy would tire the reader. No effect on `default` (already `onSurface`) or `destructive` (the warning tone must carry through the copy).
+
+```preview
+banner/accent-neutral-body
+---
+import { Banner } from '@teamblind-chorus/ui';
+
+<Banner
+  appearance="accent"
+  neutralBody
+  title="Level up faster"
+  action={{ label: 'How levels work', href: '#level' }}
+>
+  Stay active in the community to level up and unlock more of what the app offers.
+</Banner>
+```
+
+## Destructive
 
 The error-tinted appearance — `errorContainer` fill with `onErrorContainer` foreground. Reach for it when the aside is a blocking error or rejection (failed approvals, integration outages, billing). Use sparingly.
 
@@ -61,7 +78,7 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-### With thumbnail
+## Thumbnail
 
 A leading [Thumbnail](../thumbnail/thumbnail.md) at the top-left — reach for it when the aside is anchored to a channel, author, or sub-brand image. Thumbnail owns its diameter and corner shape; the slot only top-aligns it next to the content column.
 
@@ -79,9 +96,9 @@ import { Banner, Thumbnail } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-### Outlined
+## Outlined
 
-An optional `sys.borderWidth.hairline` (1) inset stroke toned to the appearance's color family and kept deliberately faint, so the outline reads as a soft edge of the same tint rather than a frame — the subtle gray hairline (`sys.color.outlineVariant`) on `default`'s gray-tinted scrim, `primary` at 40% on `accent`'s blue-tinted container, `error` at 40% on `destructive`. Painted as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint. Reach for it when the tinted fill alone doesn't separate the banner from its host surface.
+An optional `sys.borderWidth.hairline` (1) inset stroke toned to the appearance's color family and kept deliberately faint, so the outline reads as a soft edge of the same tint rather than a frame — the subtle gray hairline (`sys.color.border.default`) on `default`'s gray-tinted scrim, `primary` at 40% on `accent`'s blue-tinted container, `error` at 40% on `destructive`. Painted as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint. Reach for it when the tinted fill alone doesn't separate the banner from its host surface.
 
 ```preview
 banner/outlined
@@ -99,7 +116,7 @@ import { Banner } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### With title
+## Title
 
 An optional heading line above the body — `label.md` (14 / Semibold) in the container's foreground, separated from the body by `sys.layout.stack.2xs` (4) so the pair reads as one passage. Reach for it when the aside needs a scannable lead-in; omit it for single-thought asides where the body carries itself.
 
@@ -117,7 +134,7 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-### With trailing icon
+## Trailing icon
 
 A 16 × 16 (`sys.icon.md`) glyph at the trailing edge, vertically centred against the whole block and painted in `currentColor`. Reach for it when the banner leads somewhere — a forward affordance such as `ForwardCircleFillIcon` signals the aside opens a destination.
 
@@ -136,7 +153,38 @@ import { ForwardCircleFillIcon } from '@teamblind-chorus/ui/icons';
 </Banner>
 ```
 
-### With icon
+## Trailing action
+
+A [Text Button](../button/text.md) (`<Button variant="text">`) in the trailing slot, vertically centred against the block — a compact inline commit beside the copy (*Dismiss*, *Enable*, *Undo*), distinct from `action` (the follow-through link below the body). The button keeps full control of its own `size` and `appearance` per the button/text spec, but **default the appearance to the banner's colour family** so the commit reads as part of the tinted block — `accent` banner → `appearance="accent"`, `default` banner → `appearance="default"`, `destructive` banner → the Text Button `destructive` flavor. It also keeps the button/text `leadingIcon` / `trailingIcon` slots, so the commit can carry an in-button glyph — e.g. a trailing `ChevronRightIcon` on a *Enable* / *Continue* commit. When both `trailingAction` and the banner-level `trailingIcon` are passed, the action wins the slot.
+
+```preview
+banner/with-trailing-action
+---
+import { Banner, Button } from '@teamblind-chorus/ui';
+import { ChevronRightIcon } from '@teamblind-chorus/ui/icons';
+
+// vertical 8 between sibling banners is the parent column's job (safe zone)
+<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--sys-layout-stack-xs)' }}>
+  <Banner
+    appearance="accent"
+    trailingAction={(
+      <Button variant="text" appearance="accent" size="small" trailingIcon={<ChevronRightIcon />}>
+        Enable
+      </Button>
+    )}
+  >
+    Turn on notifications to hear back the moment someone replies.
+  </Banner>
+  <Banner
+    appearance="default"
+    trailingAction={<Button variant="text" size="small">Dismiss</Button>}
+  >
+    Stay active in the community to level up and unlock more of what the app offers.
+  </Banner>
+</div>
+```
+
+## Icon
 
 A 16 × 16 (`sys.icon.md`) glyph at the leading edge, painted in `currentColor`. The slot is sized to the body's first-line height so the glyph centres on the first line — multi-line bodies keep the icon anchored to the first-line cap, not the block centre. Reach for it when the aside leads with a meaning-bearing glyph rather than a brand image.
 
@@ -161,9 +209,10 @@ Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner c
 
 | Appearance    | Container fill                                                                              | Body / action color                                                | Outline (when `outlined`)  | When to use                                                                  |
 |---------------|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------|----------------------------|------------------------------------------------------------------------------|
-| `default`     | `sys.color.scrimSubtle` (translucent inverse-tone scrim — ~8% black light / ~8% white dark) | body in `sys.color.onSurface`, action steps to `sys.color.primary` | `sys.color.outlineVariant` (subtle gray) | Supplementary asides the reader can pass over without missing the main flow. |
-| `accent`      | `sys.color.primaryContainer`                                                                | body in `onPrimaryContainer`, action inherits                      | `sys.color.primary` at 40% (soft blue)   | Asides worth pulling the eye toward — new-feature explainers, capability nudges. |
-| `destructive` | `sys.color.errorContainer`                                                                  | body in `onErrorContainer`, action inherits                        | `sys.color.error` at 40%                 | Blocking errors or rejections — failed approvals, outages, billing.          |
+| `default`     | `sys.color.background.neutral` (translucent inverse-tone scrim — ~8% black light / ~8% white dark) | body in `sys.color.text.default`, action steps to `sys.color.background.primary` | `sys.color.border.default` (subtle gray) | Supplementary asides the reader can pass over without missing the main flow. |
+| `accent`      | `sys.color.background.selected`                                                                | body in `onPrimaryContainer`, action inherits                      | `sys.color.background.primary` at 40% (soft blue)   | Asides worth pulling the eye toward — new-feature explainers, capability nudges. |
+| `accent` + `neutralBody` | `sys.color.background.selected`                                                     | title + body in `onSurface`, action steps to `sys.color.background.primary`   | `sys.color.background.primary` at 40% (soft blue)   | Accent tint pulls the eye, but the copy stays quiet, high-legibility body text — longer explainers, dense asides. |
+| `destructive` | `sys.color.background.danger`                                                                  | body in `onErrorContainer`, action inherits                        | `sys.color.text.danger` at 40%                 | Blocking errors or rejections — failed approvals, outages, billing.          |
 
 ## Slots
 
@@ -175,6 +224,7 @@ Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner c
 - **body** — explanation copy. `body.sm` / Regular / inherits container foreground. Required.
 - **action** *(optional)* — follow-through link below the body. `label.md` / Semibold / underlined.
 - **trailingIcon** *(optional)* — 16 × 16 glyph at the trailing edge, vertically centred against the container. Paints in `currentColor`.
+- **trailingAction** *(optional)* — a [Text Button](../button/text.md) at the trailing edge, vertically centred. Owns its own size + appearance; default the appearance to the banner's colour family. Takes precedence over `trailingIcon`.
 
 ## Anatomy
 
@@ -186,8 +236,9 @@ Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner c
 | content   | Flex column, `flex: 1 1 auto`, `sys.layout.stack.xs` (8) body↔action gap, `sys.layout.stack.2xs` (4) title↔body gap |
 | title     | `sys.typo.label.md` (14 / Semibold 600), color inherits |
 | body      | `sys.typo.body.sm` (14 / Regular), color inherits |
-| action    | `sys.typo.label.md` (14 / Semibold), underlined. Steps to `sys.color.primary` in `default`; inherits in `accent` / `destructive`. |
+| action    | `sys.typo.label.md` (14 / Semibold), underlined. Steps to `sys.color.background.primary` in `default`; inherits in `accent` / `destructive`. |
 | trailingIcon | `sys.icon.md` (16 × 16) glyph, `align-self: center` against the container, `color: currentColor` |
+| trailingAction | [Text Button](../button/text.md) (`<Button variant="text">`), `flex: 0 0 auto`, `align-self: center`. Size + appearance owned by the Button; default appearance to the banner's colour family. Wins the slot over `trailingIcon` |
 
 ## States
 

package/agents/components/banner/banner.spec.json

@@ -19,7 +19,14 @@
       "type": "boolean",
       "optional": true,
       "default": false,
-      "description": "Paints a `sys.borderWidth.hairline` (1) inset stroke around the container, toned to the appearance's color family and kept deliberately faint so it reads as a soft edge of the same tint, not a frame — the subtle gray hairline (`sys.color.outlineVariant`) on `default`'s gray-tinted fill, `primary` at 40% (`color-mix(sys.color.primary, 40%)`) on `accent`'s blue-tinted fill, `error` at 40% on `destructive`. Rendered as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint (see DESIGN.md → Border & Stroke). Reach for it when the tinted fill alone doesn't separate the banner from its host surface."
+      "description": "Paints a `sys.borderWidth.hairline` (1) inset stroke around the container, toned to the appearance's color family and kept deliberately faint so it reads as a soft edge of the same tint, not a frame — the subtle gray hairline (`sys.color.border.default`) on `default`'s gray-tinted fill, `primary` at 40% (`color-mix(sys.color.background.primary, 40%)`) on `accent`'s blue-tinted fill, `error` at 40% on `destructive`. Rendered as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint (see DESIGN.md → Border & Stroke). Reach for it when the tinted fill alone doesn't separate the banner from its host surface."
+    },
+    "neutralBody": {
+      "type": "boolean",
+      "optional": true,
+      "default": false,
+      "appliesTo": "accent",
+      "description": "On `accent`, paints the title + body in the neutral default foreground (`sys.color.text.default`) and steps the action to `sys.color.background.primary` — i.e. the **Default appearance's** foreground treatment laid over the accent fill, decoupling the background tone from the text tone. Reach for it when the `primaryContainer` tint should still pull the eye but the copy should read as quiet, high-legibility body text rather than tonal `onPrimaryContainer` primary-family text (long-form explainers, dense asides). No effect on `default` (already `onSurface`) or `destructive` (the warning tone must carry through the copy)."
     },
     "title": {
       "type": "node",
@@ -46,6 +53,11 @@
       "optional": true,
       "description": "{ label, href? , onClick? } — a follow-through link rendered as a block child below the body."
     },
+    "trailingAction": {
+      "type": "node",
+      "optional": true,
+      "description": "A [Text Button](../button/text.md) (`<Button variant=\"text\">`) rendered at the container's trailing edge, vertically centered against the whole block (`align-self: center`). Distinct from `action` (a follow-through link below the body): `trailingAction` is a compact inline commit that sits beside the copy — Dismiss, Enable, Undo. The button keeps full control of its own `size` and `appearance` per the button/text spec; **by default pick the appearance whose color family matches the banner fill** so the commit reads as part of the tinted block — `accent` banner → `appearance=\"accent\"`, `default` banner → `appearance=\"default\"`, `destructive` banner → the Text Button `destructive` flavor. Override only when a denser rung (`size=\"small\"` / `\"xsmall\"`) or a different emphasis is deliberately wanted. The button also keeps its own `leadingIcon` / `trailingIcon` slots, so the commit can carry an in-button glyph (e.g. a trailing `ChevronRightIcon` on an *Enable* / *Continue* commit). Takes precedence over the banner-level `trailingIcon` when both are passed."
+    },
     "children": {
       "type": "node",
       "required": true,
@@ -104,6 +116,13 @@
       "accepts": [
         "icon"
       ]
+    },
+    "trailingAction": {
+      "required": false,
+      "description": "Trailing-edge slot hosting a Text Button (`<Button variant=\"text\">`). Footprint-preserving (`flex: 0 0 auto`) and vertically centered against the container (`align-self: center`). The Button owns its own size + appearance; default the appearance to the banner's color family (accent → `accent`, default → `default`, destructive → `destructive` flavor). Takes precedence over `trailingIcon`.",
+      "accepts": [
+        "button"
+      ]
     }
   },
   "sizing": {
@@ -138,33 +157,37 @@
   },
   "appearances": {
     "default": {
-      "background": "sys.color.scrimSubtle",
-      "foreground": "sys.color.onSurface",
-      "actionColor": "sys.color.primary",
-      "outlineColor": "sys.color.outlineVariant",
-      "note": "Body sits in `onSurface`; the action link steps to primary so it carries the only chromatic emphasis. Background is the translucent inverse-tone scrim (`sys.color.scrimSubtle` — ~8% black light / ~8% white dark) so the banner stays harmonious on any underlying surface — body, raised card, BottomSheet, Dialog — by tinting one step darker (light mode) or lighter (dark mode) instead of pinning to a fixed neutral step that can collide with the surface ladder. Same scrim used by Chip / Tag default, Progress track, StatusTag neutral, and Skeleton."
+      "background": "sys.color.background.neutral",
+      "foreground": "sys.color.text.default",
+      "actionColor": "sys.color.text.link",
+      "outlineColor": "sys.color.border.default",
+      "note": "Body sits in `onSurface`; the action link steps to primary so it carries the only chromatic emphasis. Background is the translucent inverse-tone scrim (`sys.color.background.neutral` — ~8% black light / ~8% white dark) so the banner stays harmonious on any underlying surface — body, raised card, BottomSheet, Dialog — by tinting one step darker (light mode) or lighter (dark mode) instead of pinning to a fixed neutral step that can collide with the surface ladder. Same scrim used by Chip / Tag default, Progress track, StatusTag neutral, and Skeleton."
     },
     "accent": {
-      "background": "sys.color.primaryContainer",
-      "foreground": "sys.color.onPrimaryContainer",
+      "background": "sys.color.background.selected",
+      "foreground": "sys.color.text.link",
       "actionColor": "inherit",
-      "outlineColor": "color-mix(sys.color.primary, 40%)",
-      "note": "Both body and action paint in the primary family so the whole banner reads as one highlighted block. Reach for `accent` when the aside should pull more attention — feature explainers, capability nudges."
+      "outlineColor": "color-mix(sys.color.background.primary, 40%)",
+      "note": "Both body and action paint in the primary family so the whole banner reads as one highlighted block. Reach for `accent` when the aside should pull more attention — feature explainers, capability nudges. Pass `neutralBody` to keep the accent fill but swap the copy to the Default appearance's neutral foreground (`onSurface` body, `primary` action) when the tint should pull the eye while the text stays quiet, high-legibility body copy."
     },
     "destructive": {
-      "background": "sys.color.errorContainer",
-      "foreground": "sys.color.onErrorContainer",
+      "background": "sys.color.background.danger",
+      "foreground": "sys.color.text.danger",
       "actionColor": "inherit",
-      "outlineColor": "color-mix(sys.color.error, 40%)",
+      "outlineColor": "color-mix(sys.color.text.danger, 40%)",
       "note": "Body and action paint in the error family so the whole banner reads as one warning block. Reach for `destructive` when the aside is a blocking error or rejection — failed approvals, integration outages, billing problems. Use sparingly — every destructive banner on a screen competes with the others for the user's alarm budget."
     }
   },
   "behavior": {
     "actionLink": "When present, renders as an <a> and accepts either href (browser navigation) or onClick (consumer-controlled). Underline persists at rest so the link reads as actionable inside the muted block.",
+    "trailingAction": "A `<Button variant=\"text\">` in the trailing slot is a real interactive control (not aria-hidden, unlike the trailing icon). It carries its own size + appearance per the button/text spec; the default appearance follows the banner's color family so the commit reads as part of the tinted block (accent → accent, default → default, destructive → destructive flavor). When both `trailingAction` and `trailingIcon` are passed, the action wins the slot.",
+    "neutralForeground": "`neutralBody` re-tones only the accent appearance: the container foreground becomes `onSurface` (title + body) and the action steps to `primary`, matching the Default appearance's foreground treatment. Ignored on `default` and `destructive`.",
     "role": "Container carries role='note' so screen readers announce the banner as an aside."
   },
   "forbidden": [
-    "default banner background painted with sys.color.brandContainer — informational banners use sys.color.primaryContainer; promotional banners use sys.color.surfaceContainerLow",
+    "banner trailing-edge commit rendered as a raw <a> / <button> or a filled/outlined Button — the trailing action is button/text, defaulted to the banner's color family",
+    "neutralBody applied to default or destructive — it only decouples the accent fill from its foreground; default is already onSurface and destructive must carry the warning tone through the copy",
+    "default banner background painted with a brand-tinted fill — informational banners use sys.color.background.selected; promotional banners use sys.color.surface.sunken",
     "banner thumbnail slot omitted when banner role carries imagery — empty image area is forbidden, fall back to /placeholder.png",
     "banner used for transient confirmations — that role is the `toast` family (locked)",
     "banner CTA rendered as raw <a> / <button> — use button/text inside the action slot",

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

@@ -33,9 +33,7 @@ const [open, setOpen] = useState(false);
 </>
 ```
 
-## Use cases
-
-### Overflow
+## Overflow
 
 When content exceeds the card's `max-height`, the content slot scrolls internally — handle and actions stay pinned, footer gains its `is-elevated` upward shadow.
 
@@ -62,7 +60,7 @@ const [open, setOpen] = useState(false);
 </>
 ```
 
-### Keyboard
+## Keyboard
 
 When the sheet hosts an input that summons the virtual keyboard, the card lifts above the keyboard's top edge so the actions footer stays reachable. Handle and footer pinned; content scrolls to keep the focused input in view.
 
@@ -88,7 +86,7 @@ const [open, setOpen] = useState(false);
 </>
 ```
 
-### Nested step
+## Nested step
 
 The sheet can host a **drill-in step** without spawning a second modal. The consumer swaps title, content, and primary action between renders; passing `onBack` paints a leading back chevron — an Icon Button rendering `ChevronLeftIcon` at `sys.icon.lg` (24), with `sys.layout.inline.md` (8) between glyph and title. Card chrome, scrim, drag handle, and actions footer stay identical across steps.
 
@@ -151,7 +149,7 @@ const [value, setValue] = useState('');
 | drag handle  | 48 × 4px pill, `onSurfaceVariant @ 40%`, `sys.radius.full`, 8px vertical gutter |
 | content      | Flex column, 16px padding, 16px between children, vertical scroll on overflow |
 | title        | `sys.typo.heading.lg` (24 / Semibold), `onSurface` |
-| back chevron | [Icon Button](../button/icon.md) → `ChevronLeftIcon` at `sys.icon.lg` (24), `sys.color.onSurface`. Glyph aligns to the title's leading edge via Icon Button optical-alignment. `sys.layout.inline.md` (8) glyph → title gap. |
+| back chevron | [Icon Button](../button/icon.md) → `ChevronLeftIcon` at `sys.icon.lg` (24), `sys.color.text.default`. Glyph aligns to the title's leading edge via Icon Button optical-alignment. `sys.layout.inline.md` (8) glyph → title gap. |
 | body         | `sys.typo.body.md` (16 / Regular), `onSurfaceVariant` |
 | actions      | Flex column, 8px between buttons, 16px padding on all four sides |
 | primary CTA  | [Button](../button/button.md) `appearance="primary"`, `size="large"`, `fullWidth` |

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

@@ -104,14 +104,14 @@
   },
   "sizing": {
     "scrimTint": "ref.palette.black.600",
-    "containerFill": "sys.color.surfaceContainerHigh",
+    "containerFill": "sys.color.surface.default",
     "containerRadiusTop": "sys.radius.xl",
     "containerRadiusBottom": "0",
     "elevation": "sys.elevation.sheet",
     "maxWidth": "480px",
     "maxHeight": "90vh",
     "dragHandleSize": "48 × 4px",
-    "dragHandleFill": "sys.color.onSurfaceVariant @ 40%",
+    "dragHandleFill": "sys.color.text.subtle @ 40%",
     "dragHandleRadius": "sys.radius.full",
     "dragHandleGutter": "sys.layout.container.xs",
     "contentPadding": "sys.layout.container.md",
@@ -119,13 +119,13 @@
     "actionsStackGap": "sys.layout.stack.xs",
     "actionsPadding": "sys.layout.container.md",
     "titleTypo": "sys.typo.heading.lg",
-    "titleColor": "sys.color.onSurface",
+    "titleColor": "sys.color.text.default",
     "backIcon": "ChevronLeftIcon",
     "backIconSize": "sys.icon.lg",
-    "backIconColor": "sys.color.onSurface",
+    "backIconColor": "sys.color.icon.default",
     "backToTitleGap": "sys.layout.inline.md",
     "bodyTypo": "sys.typo.body.md",
-    "bodyColor": "sys.color.onSurfaceVariant"
+    "bodyColor": "sys.color.text.subtle"
   },
   "states": {
     "open": {

package/agents/components/bubble/bubble.md

@@ -8,7 +8,7 @@ A small persistent annotation pill with a tail pointing at an anchor — a chat-
 
 **Layout inset.** `inline` — the bubble ships no positioning. The host anchors it to the target element by *visual alignment* (CSS anchor positioning, or a positioned wrapper around the anchor): the tail's TIP sits flush on the anchor's content edge (padding excluded) — the bubble body is set back from that edge by the tail's own protrusion (`ref.space.50 / √2`) so the tail meets the anchor cleanly rather than overlapping it — and the bubble centres on the anchor's visual centre so the tail sits at the anchor's bottom-centre. The bubble caps its own `max-width` so it always keeps an 8-token margin from every viewport edge; position-clamping is the host's job. Only when centring would push the bubble past that safe margin does the host shift it inward and flip `tailAlign` so the tail still points at the anchor — `start` for left-edge anchors, `end` for right-edge anchors, `center` whenever the anchor has room on both sides (the default).
 
-**Colour tuning.** Default fill `sys.color.primary` / label `sys.color.onPrimary` — both theme-stable. Operations re-tint per campaign by setting `--bubble-fill` and `--bubble-ink` on inline style; the tail's `background: inherit` follows automatically.
+**Colour tuning.** Default fill `sys.color.background.primary` / label `sys.color.text.onFill` — both theme-stable. Operations re-tint per campaign by setting `--bubble-fill` and `--bubble-ink` on inline style; the tail's `background: inherit` follows automatically.
 
 ## Default
 
@@ -20,9 +20,7 @@ import { Bubble } from '@teamblind-chorus/ui';
 <Bubble>5 new messages + gift</Bubble>
 ```
 
-## Use cases
-
-### Anchored to a top-bar icon
+## Anchored icon
 
 A [Navigation bar (home)](../navigation-bar/main.md) with three trailing actions, bubble anchored to the chat glyph itself. The glyph carries `anchor-name: --chat-icon`; the bubble pins to the glyph's bottom — padding excluded — set back by the tail's own protrusion (`top: calc(anchor(bottom) + var(--bubble-tail-protrusion))`, the system token = `ref.space.50 / √2`) so the tail's top vertex lands *flush* on the glyph's bottom edge rather than poking into it, and centres on the glyph's visual centre (`left: anchor(center)` + `translateX(-50%)`). The tail tip thus sits on the chat icon's bottom-centre regardless of where the bar reflows — no hardcoded pixel offsets, `tailAlign="center"`.
 
@@ -70,7 +68,7 @@ import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
 </div>
 ```
 
-### Tail alignment
+## Tail alignment
 
 Three tail positions stacked so the offset reads at a glance — pick by where the anchor sits.
 
@@ -86,7 +84,7 @@ import { Bubble } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### Operations re-tint
+## Operations re-tint
 
 Brand red instead of primary blue — the tail inherits the fill, so a single declaration covers both surfaces.
 
@@ -95,12 +93,12 @@ bubble/recoloured
 ---
 import { Bubble } from '@teamblind-chorus/ui';
 
-<Bubble style={{ '--bubble-fill': 'var(--sys-color-brand)', '--bubble-ink': 'var(--sys-color-onBrand)' }}>
+<Bubble style={{ '--bubble-fill': 'var(--sys-color-text-brand)', '--bubble-ink': 'var(--sys-color-text-onFill)' }}>
   Free daily tarot
 </Bubble>
 ```
 
-### Long copy
+## Long copy
 
 Copy that exceeds the host width truncates with an ellipsis. If the message can't fit on one line, it belongs in a [Banner](../banner/banner.md) instead.
 
@@ -124,8 +122,8 @@ import { Bubble } from '@teamblind-chorus/ui';
 
 | Slot      | Token bindings |
 |-----------|----------------|
-| container | Fill `--bubble-fill` (default `sys.color.primary`), ink `--bubble-ink` (default `sys.color.onPrimary`), `sys.layout.container.2xs` padding-block, `ref.space.75` padding-inline, `sys.radius.full`, viewport-safe `max-width` cap |
-| body      | `sys.typo.caption` |
+| container | Fill `--bubble-fill` (default `sys.color.background.primary`), ink `--bubble-ink` (default `sys.color.text.onFill`), `sys.layout.container.2xs` padding-block, `ref.space.75` padding-inline, `sys.radius.full`, viewport-safe `max-width` cap |
+| body      | `sys.typo.label.xs` |
 | tail      | `ref.space.50` square, rotated 45° |
 
 ## Behavior

package/agents/components/bubble/bubble.spec.json

@@ -2,7 +2,7 @@
   "$schema": "../../spec.schema.json",
   "name": "Bubble",
   "family": "bubble",
-  "description": "Always-on annotation bubble — a pill-shaped label with a small tail that points at the anchor UI element. Ships with a default brand-blue fill (`sys.color.primary` / `sys.color.onPrimary` — both theme-stable so the bubble reads identically in light and dark mode) and exposes two CSS custom properties (`--bubble-fill`, `--bubble-ink`) so operations can re-tint per campaign without forking the component. Distinct from Tooltip on three axes: (1) persistent rather than transient — Bubble stays in view as part of the UI's resting state; (2) lower visual priority — no elevation shadow, smaller padding, single-line truncation; (3) does NOT occlude its neighbours — the host positions it inline next to the anchor, never as a portal-mounted overlay.",
+  "description": "Always-on annotation bubble — a pill-shaped label with a small tail that points at the anchor UI element. Ships with a default brand-blue fill (`sys.color.background.primary` / `sys.color.text.onFill` — both theme-stable so the bubble reads identically in light and dark mode) and exposes two CSS custom properties (`--bubble-fill`, `--bubble-ink`) so operations can re-tint per campaign without forking the component. Distinct from Tooltip on three axes: (1) persistent rather than transient — Bubble stays in view as part of the UI's resting state; (2) lower visual priority — no elevation shadow, smaller padding, single-line truncation; (3) does NOT occlude its neighbours — the host positions it inline next to the anchor, never as a portal-mounted overlay.",
   "element": "div",
   "props": {
     "children": {
@@ -36,12 +36,12 @@
   "slots": {
     "container": {
       "required": true,
-      "description": "The pill body. `position: relative` so the tail can pin to its edge; `display: inline-flex` so the bubble shrink-wraps its body. Carries the fill (`--bubble-fill` defaulting to `sys.color.primary`), ink (`--bubble-ink` defaulting to `sys.color.onPrimary`), 4 / 6 padding, and pill radius. `role='note'` so the annotation reads as supplementary rather than as a main UI control.",
+      "description": "The pill body. `position: relative` so the tail can pin to its edge; `display: inline-flex` so the bubble shrink-wraps its body. Carries the fill (`--bubble-fill` defaulting to `sys.color.background.primary`), ink (`--bubble-ink` defaulting to `sys.color.text.onFill`), 4 / 6 padding, and pill radius. `role='note'` so the annotation reads as supplementary rather than as a main UI control.",
       "intrinsic": true
     },
     "body": {
       "required": true,
-      "description": "Bubble copy in `sys.typo.caption` (10 / Semibold). Single line — `white-space: nowrap` + `text-overflow: ellipsis` truncate overflow rather than wrap. Inherits the container's ink colour.",
+      "description": "Bubble copy in `sys.typo.label.xs` (10 / Semibold). Single line — `white-space: nowrap` + `text-overflow: ellipsis` truncate overflow rather than wrap. Inherits the container's ink colour.",
       "accepts": ["text"]
     },
     "tail": {
@@ -51,9 +51,9 @@
     }
   },
   "sizing": {
-    "background": "sys.color.primary",
-    "foreground": "sys.color.onPrimary",
-    "labelTypo": "sys.typo.caption",
+    "background": "sys.color.background.primary",
+    "foreground": "sys.color.text.onFill",
+    "labelTypo": "sys.typo.label.xs",
     "paddingBlock": "sys.layout.container.2xs",
     "paddingInline": "ref.space.75",
     "radius": "sys.radius.full",
@@ -62,9 +62,9 @@
     "viewportSafeArea": "sys.layout.container.xs"
   },
   "appearance": {
-    "background": "sys.color.primary",
-    "foreground": "sys.color.onPrimary",
-    "note": "Single canonical appearance — Bubble has no `default` / `accent` / `destructive` axis. Default fill is `sys.color.primary` and label is `sys.color.onPrimary`; both are theme-stable so the bubble reads identically in light and dark mode. Operations re-tint by setting `--bubble-fill` and `--bubble-ink` on the bubble's inline style or a wrapping class — the tail inherits the fill via `background: inherit`, so a colour swap on the container covers the whole bubble in one declaration. Re-tints should keep the contrast above WCAG AA against `--bubble-ink` (4.5:1); the system does not enforce this at runtime."
+    "background": "sys.color.background.primary",
+    "foreground": "sys.color.text.onFill",
+    "note": "Single canonical appearance — Bubble has no `default` / `accent` / `destructive` axis. Default fill is `sys.color.background.primary` and label is `sys.color.text.onFill`; both are theme-stable so the bubble reads identically in light and dark mode. Operations re-tint by setting `--bubble-fill` and `--bubble-ink` on the bubble's inline style or a wrapping class — the tail inherits the fill via `background: inherit`, so a colour swap on the container covers the whole bubble in one declaration. Re-tints should keep the contrast above WCAG AA against `--bubble-ink` (4.5:1); the system does not enforce this at runtime."
   },
   "behavior": {
     "ariaRole": "Container carries `role='note'` so screen readers announce the bubble as a supplementary note rather than as a main UI control. The decorative tail carries `aria-hidden='true'`.",
@@ -74,12 +74,12 @@
     "zeroGapToAnchor": "**The tail's TIP sits flush on the anchor's CONTENT edge (padding excluded) — no overlap, no gap.** This is the canonical home of the set-back math. Align to the anchor's content box, not its padding box: the tail-bearing edge (top for `tailSide='top'`, bottom for `tailSide='bottom'`) is set BACK from the anchor by the tail's own protrusion so the tail's outer vertex lands exactly on the anchor's content edge. The tail is a `ref.space.50` (4) square rotated 45°, so its vertex pokes `ref.space.50 / √2` ≈ 2.83 past the bubble edge; the system exposes this at :root as `--bubble-tail-protrusion`, and the host adds exactly that set-back (e.g. `top: calc(anchor(bottom) + var(--bubble-tail-protrusion))`). Overlapping the anchor reads as a collision; a gap larger than the protrusion leaves the tail unattached. For more breathing room, widen the *anchor's* padding — never enlarge the set-back. This √2 set-back is the single derived constant in the contract; the horizontal axis is pure visual alignment.",
     "tailAlignSelection": "`tailAlign='center'` is the default and preferred case — the bubble centres on the anchor so the tail sits dead-centre and its tip falls on the anchor's centreX by construction (see tailTipCentredOnAnchor). It flips off-centre only as an edge fallback: when the anchor sits so near a viewport edge that centring would push the bubble past the 8-token safe margin, the bubble shifts AWAY from the edge and `tailAlign` flips to the SAME side as the anchor — `end` at the right edge (bubble extends leftward), `start` at the left edge (bubble extends rightward). In every case the bubble's nearest edge stays ≥8 from the viewport edge and the tip stays on the anchor's centreline; visibility is the contract, tail position is the lever.",
     "positioning": "Bubble is presentational — the *host* owns positioning, and the canonical pattern binds bubble to anchor by VISUAL ALIGNMENT (CSS anchor positioning, or a positioned wrapper around the anchor) rather than DOM proximity, so the tail tracks the anchor through reflows. Four coupled decisions, each detailed in its own rule: (a) `tailSide` — `top` when the bubble sits below the anchor, `bottom` when above; (b) the vertical set-back so the tail tip is flush on the anchor's content edge — see zeroGapToAnchor; (c) horizontal centring so the tip lands on the anchor's centreX — see tailTipCentredOnAnchor; (d) `tailAlign`, `center` by default and flipped only at a viewport edge — see tailAlignSelection. Get any one wrong and the tail points at empty space.",
-    "colorTuning": "Two CSS custom properties — `--bubble-fill` (background) and `--bubble-ink` (label) — are the supported runtime override surface. Default to `sys.color.primary` / `sys.color.onPrimary`. Operations campaigns set them on inline style; static themes set them on a wrapper class. The tail's `background: inherit` follows automatically."
+    "colorTuning": "Two CSS custom properties — `--bubble-fill` (background) and `--bubble-ink` (label) — are the supported runtime override surface. Default to `sys.color.background.primary` / `sys.color.text.onFill`. Operations campaigns set them on inline style; static themes set them on a wrapper class. The tail's `background: inherit` follows automatically."
   },
   "forbidden": [
     "bubble used as a transient hover/focus tooltip — that role is the `tooltip` family; bubble must remain in view at the UI's resting state",
     "bubble portal-mounted at document root with a fixed z-index that overlays surrounding chrome — bubble must NEVER occlude neighbour elements; that contract is what separates it from Tooltip",
-    "bubble painted with an elevation shadow (`sys.elevation.raised` / `floating` / `overlay` / `sheet`) — the lift signal is what makes Tooltip 'jump'; Bubble is intentionally flat",
+    "bubble painted with an elevation shadow (`sys.elevation.floating` / `overlay` / `sheet`) — the lift signal is what makes Tooltip 'jump'; Bubble is intentionally flat",
     "bubble copy that wraps to multiple lines — overflow truncates with an ellipsis rather than wrapping; if the message can't fit on one line, it belongs in a Banner or a Tooltip with action",
     "bubble retinted with hardcoded hex / rgba on `background` or `color` instead of `--bubble-fill` / `--bubble-ink` — campaign tunes must route through the documented custom-property surface so the tail colour tracks the body",
     "bubble used to convey *required* meaning (error blocking a submit, account-locked notice) — that role is Banner / Dialog; bubble is a soft annotation only",

package/agents/components/button/button.md

@@ -20,7 +20,7 @@ Transparent-rest forms ([Icon Button](./icon.md), [Text Button](./text.md), [Ter
 
 ### Focus ring
 
-All Button family components draw the same outward two-layer ring as a `position: absolute` pseudo-element — never a layout-affecting border. Suppressed while `disabled`. Trigger: `:focus-visible`. See [DESIGN.md → Focus ring composition](../../DESIGN.md#focus-ring-composition).
+All Button family components draw the same outward single ring as a `position: absolute` pseudo-element — never a layout-affecting border. Suppressed while `disabled`. Trigger: `:focus-visible`. See [DESIGN.md → Focus ring composition](../../DESIGN.md#focus-ring-composition).
 
 ## Sub-components
 

package/agents/components/button/check.md

@@ -35,11 +35,9 @@ function Demo() {
 <Demo />
 ```
 
-## Use cases
+## Accent
 
-### Accent
-
-Brand-blue label — `sys.color.primary`. Use sparingly; never two accent Check Buttons in the same row.
+Brand-blue label — `sys.color.background.primary`. Use sparingly; never two accent Check Buttons in the same row.
 
 ```preview
 button/check/accent
@@ -51,9 +49,9 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### Inverse
+## Inverse
 
-Mirror for inverse hosts (Toast, coach-mark, snackbar). Label paints `sys.color.inverseOnSurface` against the host's `inverseSurface` fill.
+Mirror for inverse hosts (Toast, coach-mark, snackbar). Label paints `sys.color.text.inverse` against the host's `inverseSurface` fill.
 
 ```preview
 button/check/inverse
@@ -65,7 +63,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### Checked
+## Checked
 
 Same row with `checked={true}` — checkbox glyph flips to the filled square. State overlays follow the label color.
 
@@ -79,7 +77,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### With middle icon
+## Middle icon
 
 Optional 16px icon between checkbox and label. Use sparingly — most rows don't need it. Canonical case: an item-use row where the middle glyph names the item being consumed.
 
@@ -100,9 +98,9 @@ Three appearances. `default` is the base neutral toggle; `accent` paints the lab
 
 | Appearance | Background (rest) | Label color                  | When to reach for it                                                  |
 |-----------|-------------------|------------------------------|-----------------------------------------------------------------------|
-| `default` | `transparent`     | `sys.color.onSurfaceVariant` | The base neutral toggle — option rows next to a primary commit.       |
-| `accent`  | `transparent`     | `sys.color.primary`          | One option per row that needs commit-rank emphasis.                   |
-| `inverse` | `transparent`     | `sys.color.inverseOnSurface` | Inside an inverse host (Toast, coach-mark, snackbar).                 |
+| `default` | `transparent`     | `sys.color.text.subtle` | The base neutral toggle — option rows next to a primary commit.       |
+| `accent`  | `transparent`     | `sys.color.background.primary`          | One option per row that needs commit-rank emphasis.                   |
+| `inverse` | `transparent`     | `sys.color.text.inverse` | Inside an inverse host (Toast, coach-mark, snackbar).                 |
 
 ## Slots
 

package/agents/components/button/check.spec.json

@@ -92,19 +92,19 @@
     "default": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.onSurfaceVariant",
+      "label": "sys.color.text.subtle",
       "note": "The base neutral inline toggle — the canonical Check Button. Quiet enough to live next to typographic content without claiming commit-rank attention."
     },
     "accent": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.primary",
+      "label": "sys.color.text.link",
       "note": "Brand-blue label for the inline toggle. Use sparingly — never two `accent` Check Buttons in the same row."
     },
     "inverse": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.inverseOnSurface",
+      "label": "sys.color.text.inverse",
       "note": "Mirror for use inside an inverse host (Toast, coach-mark, snackbar). Label paints in `inverseOnSurface` so it reads against the host's `inverseSurface` fill; state overlays mix from the same token so the recipe carries over without per-host tuning."
     }
   },
@@ -124,6 +124,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.border.focused"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.border.focused"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the button is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",
@@ -134,16 +153,14 @@
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the button is in. The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
     "composition": "outward",
-    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding layout.",
+    "compositionReason": "Action affordance with breathing room around it; the 1px outward ring is reserved by the surrounding layout.",
     "overlay": {
       "color": "label",
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset"
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused"
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },