@teamblind-chorus/ui 1.2.0 → 2.0.0

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."
     }
   },
@@ -134,11 +134,11 @@
         "layer": "::after overlay — position:absolute, inset:0, 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 button is in; never via plain mouse click."
@@ -153,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)"
   },

package/agents/components/button/fab.md

@@ -27,9 +27,7 @@ import { PlusIcon } from '@teamblind-chorus/ui/icons';
 </Button>
 ```
 
-## Use cases
-
-### Secondary
+## Secondary
 
 Theme-toned FAB that defers to the canvas's surface tones. Reach for it when a brand-red FAB would over-claim the page hierarchy (filtered map, image-rich feed).
 
@@ -48,7 +46,7 @@ import { PlusIcon } from '@teamblind-chorus/ui/icons';
 </Button>
 ```
 
-### Icon
+## Icon
 
 Icon-only — 48 × 48 circle with a 24px glyph. For universally legible actions (`+`, pencil). **Requires `aria-label`.**
 
@@ -66,7 +64,7 @@ import { PlusIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### Text
+## Text
 
 Label-only pill. For multi-word actions or verbs without an obvious glyph (*Save draft*).
 
@@ -80,7 +78,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### Extended
+## Extended
 
 Icon + label. Default for primary canvas commits where space allows (desktop canvases, mobile sheets).
 
@@ -99,7 +97,7 @@ import { PlusIcon } from '@teamblind-chorus/ui/icons';
 </Button>
 ```
 
-### Focus indicator
+## Focus ring
 
 Standard ring with the FAB's floating elevation stacked underneath. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
 
@@ -127,8 +125,8 @@ Two appearances on the standard [Button](./button.md) emphasis ladder — `prima
 
 | Appearance  | Background                       | Label / icon color   | When to reach for it                                                                              |
 |-------------|----------------------------------|----------------------|---------------------------------------------------------------------------------------------------|
-| `primary`   | `sys.color.brand`                | `sys.color.onBrand`  | Brand-red commit anchoring the canvas's next step (Compose, Add, Create). |
-| `secondary` | `sys.color.surfaceContainerHigh` | `sys.color.onSurface` | Theme-toned alternative on dense/chromatic canvases where brand-red would over-claim. |
+| `primary`   | `sys.color.text.brand`                | `sys.color.text.onFill`  | Brand-red commit anchoring the canvas's next step (Compose, Add, Create). |
+| `secondary` | `sys.color.surfaceContainerHigh` | `sys.color.text.default` | Theme-toned alternative on dense/chromatic canvases where brand-red would over-claim. |
 
 ## Sizes
 

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

@@ -56,12 +56,12 @@
   },
   "appearances": {
     "primary": {
-      "background": "sys.color.brand",
-      "label": "sys.color.onBrand"
+      "background": "sys.color.text.brand",
+      "label": "sys.color.text.onFill"
     },
     "secondary": {
-      "background": "sys.color.surfaceContainerHigh",
-      "label": "sys.color.onSurface"
+      "background": "sys.color.surface.default",
+      "label": "sys.color.text.default"
     }
   },
   "states": {
@@ -90,11 +90,11 @@
         "layer": "::after overlay — position:absolute, inset:0, 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 FAB is in; never via plain mouse click."
@@ -103,22 +103,20 @@
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the FAB is in. The ring stacks above the FAB's floating elevation so the lift survives focus. 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)"
   },
   "forbidden": [
     "more than one fab per screen — the FAB is the single canonical commit",
-    "fab styled with sys.color.primary fill — the FAB carries sys.color.brand by anatomy contract",
+    "fab styled with sys.color.background.primary fill — the FAB carries sys.color.text.brand by anatomy contract",
     "destructive flavor on a FAB — destructive commits live inside Dialog / BottomSheet, never a floating commit",
     "fab placed inline in flow — it floats over content, anchored bottom-right by the page shell"
   ]

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

@@ -3,7 +3,7 @@
   "name": "ButtonGroup",
   "family": "button",
   "subcomponent": "group",
-  "description": "Lays out two or more Buttons as one composition so consumers never hand-roll the wrapper div. A NAMED export (`import { ButtonGroup }`) — NOT a Button variant. Three forms share the family's 8px (`sys.layout.inline.md`) gap: inline horizontal (default), inline vertical (`orientation=\"vertical\"`), and docked (`variant=\"docked\"`) — a footer bar pinned to the bottom of the app. The docked form adds full-bleed `sys.color.surface`, a 16px (`sys.layout.container.md`) inset, an upward `sys.elevation.sheet` shadow (no top stroke), and an optional `label` above the row.",
+  "description": "Lays out two or more Buttons as one composition so consumers never hand-roll the wrapper div. A NAMED export (`import { ButtonGroup }`) — NOT a Button variant. Three forms share the family's 8px (`sys.layout.inline.md`) gap: inline horizontal (default), inline vertical (`orientation=\"vertical\"`), and docked (`variant=\"docked\"`) — a footer bar pinned to the bottom of the app. The docked form adds full-bleed `sys.color.surface.default`, a 16px (`sys.layout.container.md`) inset, an upward `sys.elevation.sheet` shadow (no top stroke), and an optional `label` above the row.",
   "element": "div",
   "props": {
     "variant": {
@@ -26,7 +26,7 @@
     "label": {
       "type": "node",
       "optional": true,
-      "note": "Optional caption above the row. Rendered in `sys.typo.body.md` (16px) / `sys.color.onSurfaceVariant`, centered. An inline <strong> reads as the emphasized value in the full-strength on-surface tone."
+      "note": "Optional caption above the row. Rendered in `sys.typo.body.md` (16px) / `sys.color.text.subtle`, centered. An inline <strong> reads as the emphasized value in the full-strength on-surface tone."
     }
   },
   "slots": {
@@ -39,7 +39,7 @@
     },
     "label": {
       "required": false,
-      "description": "Optional caption above the row (`label` prop). `sys.typo.body.md` (16px), `sys.color.onSurfaceVariant`, centered, 16px (`sys.layout.stack.md`) above the row.",
+      "description": "Optional caption above the row (`label` prop). `sys.typo.body.md` (16px), `sys.color.text.subtle`, centered, 16px (`sys.layout.stack.md`) above the row.",
       "accepts": [
         "text"
       ]
@@ -49,7 +49,7 @@
     "gap": "sys.layout.inline.md (8) — between Buttons, both axes",
     "labelStackGap": "sys.layout.stack.md (16) — label → row",
     "docked": {
-      "background": "sys.color.surface",
+      "background": "sys.color.surface.default",
       "padding": "sys.layout.container.md (16) — all four sides",
       "elevation": "sys.elevation.sheet — upward shadow, the same one Bottom Sheet / Side Sheet cast",
       "border": null,

package/agents/components/button/icon.md

@@ -21,9 +21,7 @@ import { SearchIcon } from '@teamblind-chorus/ui/icons';
 <Button variant="icon" size="large" icon={<SearchIcon />} aria-label="Search" />
 ```
 
-## Use cases
-
-### Inverse
+## Inverse
 
 Mirror for inverse hosts (Toast dismiss, coach-mark close). Glyph paints in `inverseOnSurface` against the host's `inverseSurface` fill; state overlays mix from the same token.
 
@@ -36,9 +34,9 @@ import { XIcon } from '@teamblind-chorus/ui/icons';
 <Button variant="icon" size="medium" appearance="inverse" icon={<XIcon />} aria-label="Dismiss" />
 ```
 
-### Custom palette colours
+## Custom palette
 
-Outside the named appearances, the glyph inherits `currentColor` — any Chorus icon-paint token works. Reach for a custom colour when the glyph carries semantic weight (favorite star → `sys.color.icon.yellow`, success check → `sys.color.success`, warning bolt, channel-branded glyph in a brand-tinted host). Apply via inline `color` so state overlays still mix from the same token at standard `sys.state.*` opacities — never override `background` or wrap in another element to recolour.
+Outside the named appearances, the glyph inherits `currentColor` — any Chorus icon-paint token works. Reach for a custom colour when the glyph carries semantic weight (favorite star → `sys.color.icon.accent.yellow.default`, success check → `sys.color.text.success`, warning bolt, channel-branded glyph in a brand-tinted host). Apply via inline `color` so state overlays still mix from the same token at standard `sys.state.*` opacities — never override `background` or wrap in another element to recolour.
 
 ```preview
 button/icon/custom-color
@@ -47,41 +45,41 @@ import { Button } from '@teamblind-chorus/ui';
 import { StarFillIcon } from '@teamblind-chorus/ui/icons';
 
 <div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-xl)' }}>
-  <Button variant="icon" icon={<StarFillIcon />} aria-label="Favorite — inactive" style={{ color: 'var(--sys-color-icon-muted)' }} />
-  <Button variant="icon" icon={<StarFillIcon />} aria-label="Favorite — active"   style={{ color: 'var(--sys-color-icon-yellow)' }} />
+  <Button variant="icon" icon={<StarFillIcon />} aria-label="Favorite — inactive" style={{ color: 'var(--sys-color-icon-subtle)' }} />
+  <Button variant="icon" icon={<StarFillIcon />} aria-label="Favorite — active"   style={{ color: 'var(--sys-color-icon-accent-yellow-default)' }} />
 </div>
 ```
 
 Pick from `sys.color.*` — semantic roles (`primary` / `success` / `error` / …) for status pairs that also carry a background, and the dedicated `sys.color.icon.*` palette (`muted` / `yellow` / `red` / `blue` / `green` / `purple`) for standalone semantic glyphs. Reaching past sys into `ref.palette.*`, hardcoded hex, and Tailwind colour utilities are all forbidden.
 
-### Group
+## Focus ring
 
-Three Icon Buttons in a row — common shape on the [Navigation bar](../navigation-bar/navigation-bar.md) Main trailing slot. Adjacent buttons sit 16px apart (`sys.layout.inline.xl`); with optical alignment on, that gap *is* the visible glyph-to-glyph distance.
+Standard ring (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)).
 
 ```preview
-button/icon/group
+button/icon/focused
 ---
 import { Button } from '@teamblind-chorus/ui';
-import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+import { SearchIcon } from '@teamblind-chorus/ui/icons';
 
-<div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-xl)' }}>
-  <Button variant="icon" icon={<SearchIcon />}  aria-label="Search" />
-  <Button variant="icon" icon={<ChatIcon />}    aria-label="Messages" />
-  <Button variant="icon" icon={<ProfileIcon />} aria-label="Profile" />
-</div>
+<Button variant="icon" icon={<SearchIcon />} aria-label="Search" state="focused" />
 ```
 
-### Focus indicator
+## Group
 
-Standard ring (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)).
+Three Icon Buttons in a row — common shape on the [Navigation bar](../navigation-bar/navigation-bar.md) Main trailing slot. Adjacent buttons sit 16px apart (`sys.layout.inline.xl`); with optical alignment on, that gap *is* the visible glyph-to-glyph distance.
 
 ```preview
-button/icon/focused
+button/icon/group
 ---
 import { Button } from '@teamblind-chorus/ui';
-import { SearchIcon } from '@teamblind-chorus/ui/icons';
+import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
 
-<Button variant="icon" icon={<SearchIcon />} aria-label="Search" state="focused" />
+<div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-xl)' }}>
+  <Button variant="icon" icon={<SearchIcon />}  aria-label="Search" />
+  <Button variant="icon" icon={<ChatIcon />}    aria-label="Messages" />
+  <Button variant="icon" icon={<ProfileIcon />} aria-label="Profile" />
+</div>
 ```
 
 ## Slots
@@ -105,8 +103,8 @@ Two named appearances; geometry identical, only the glyph colour pair flips.
 
 | Appearance  | Background    | Border | Icon color                       | When to reach for it |
 |-------------|---------------|--------|----------------------------------|----------------------|
-| `default`   | `transparent` | none   | `sys.color.onSurface`            | Every regular page surface. |
-| `inverse`   | `transparent` | none   | `sys.color.inverseOnSurface`     | For use inside an inverse host (Toast dismiss, coach-mark close). |
+| `default`   | `transparent` | none   | `sys.color.text.default`            | Every regular page surface. |
+| `inverse`   | `transparent` | none   | `sys.color.text.inverse`     | For use inside an inverse host (Toast dismiss, coach-mark close). |
 
 ## Sizes