@teamblind-chorus/ui 1.1.0 → 2.0.0

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": {
@@ -79,27 +79,44 @@
         "color": "label",
         "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 FAB is in; never via plain mouse click."
     }
   },
   "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
 

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

@@ -75,24 +75,24 @@
     "default": {
       "background": "transparent",
       "border": null,
-      "icon": "sys.color.onSurface",
+      "icon": "sys.color.icon.default",
       "note": "Transparent capsule with the glyph in `onSurface`. The canonical Icon Button chrome, used on every regular page surface."
     },
     "inverse": {
       "background": "transparent",
       "border": null,
-      "icon": "sys.color.inverseOnSurface",
+      "icon": "sys.color.text.inverse",
       "note": "Mirror of `default` for use inside an inverse host (Toast, coach-mark, snackbar). Glyph 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."
     }
   },
   "customGlyphColor": {
     "allowed": true,
-    "description": "Outside the named `default` / `inverse` appearances, the glyph colour is open — the icon inherits `currentColor`, so any Chorus icon-paint token can be applied via inline `color` (e.g. `style={{ color: 'var(--sys-color-icon-yellow)' }}` for an active favorite star, `var(--sys-color-success)` for a confirm check, `var(--sys-color-icon-muted)` for the unpressed partner). State overlays still mix from the same token at the standard `hovered`/`pressed`/`focused` state opacities, so hover / pressed / focus carry over without per-host tuning.",
+    "description": "Outside the named `default` / `inverse` appearances, the glyph colour is open — the icon inherits `currentColor`, so any Chorus icon-paint token can be applied via inline `color` (e.g. `style={{ color: 'var(--sys-color-icon-accent-yellow-default)' }}` for an active favorite star, `var(--sys-color-icon-success)` for a confirm check, `var(--sys-color-icon-subtle)` for the unpressed partner). State overlays still mix from the same token at the standard `hovered`/`pressed`/`focused` state opacities, so hover / pressed / focus carry over without per-host tuning.",
     "constraints": [
-      "Pick a Chorus colour token. Two valid sources: (a) a status-pair role (`sys.color.primary`, `sys.color.success`, `sys.color.error`, etc.) when the glyph travels with its own background; (b) the dedicated icon palette (`sys.color.icon.muted`, `sys.color.icon.yellow`, `sys.color.icon.red`, `sys.color.icon.blue`, `sys.color.icon.green`, `sys.color.icon.purple`) for standalone semantic glyphs. Reaching past sys into the raw palette (`ref.palette.yellow.500` etc.), raw hex, and Tailwind colour utilities are all forbidden.",
+      "Pick a Chorus colour token. Two valid sources: (a) a status-pair role (`sys.color.background.primary`, `sys.color.text.success`, `sys.color.text.danger`, etc.) when the glyph travels with its own background; (b) the dedicated icon palette (`sys.color.icon.subtle`, `sys.color.icon.accent.yellow.default`, `sys.color.icon.accent.red.default`, `sys.color.icon.accent.blue.default`, `sys.color.icon.accent.green.default`, `sys.color.icon.accent.purple.default`) for standalone semantic glyphs. Reaching past sys into the raw palette (`ref.palette.yellow.500` etc.), raw hex, and Tailwind colour utilities are all forbidden.",
       "Override the icon's `color` only — never `background`, never wrap in another element to restyle.",
       "Reach for a custom colour when the glyph itself carries semantic weight (favorite, success, warning, brand-tinted host). Otherwise stick to `default` / `inverse`.",
-      "The `destructive` flavor (`sys.color.error`) is a named convenience for the same pattern."
+      "The `destructive` flavor (`sys.color.text.danger`) is a named convenience for the same pattern."
     ]
   },
   "flavors": {
@@ -102,12 +102,12 @@
         "default": {
           "background": "transparent",
           "border": null,
-          "icon": "sys.color.error"
+          "icon": "sys.color.icon.danger"
         },
         "inverse": {
           "background": "transparent",
           "border": null,
-          "icon": "sys.color.error"
+          "icon": "sys.color.icon.danger"
         }
       }
     }
@@ -128,6 +128,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "icon",
+        "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",
@@ -138,16 +157,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": "icon",
       "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/standard.md

@@ -22,9 +22,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-## Use cases
-
-### Secondary
+## Secondary
 
 Lower-emphasis tier paired against `primary` — opposing actions (Cancel beside Save) or quieter alternatives. Safe to repeat on a single view.
 
@@ -38,7 +36,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### Outlined
+## Outlined
 
 Bordered blue-on-transparent — supplementary option beside `primary` (*See more*, *Learn more*, *Skip for now*). For opposing paths use `secondary`.
 
@@ -52,9 +50,9 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### Tertiary
+## Tertiary
 
-Neutral grey ghost — transparent at rest, label in `sys.color.onSurfaceVariant`. Reads as a button only on hover.
+Neutral grey ghost — transparent at rest, label in `sys.color.text.subtle`. Reads as a button only on hover.
 
 ```preview
 button/standard/tertiary
@@ -66,7 +64,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### With leading icon
+## Leading icon
 
 Optional context glyph before the label. Inherits label color via `currentColor` (`sys.icon.lg` on `large`, `sys.icon.md` on `medium`/`small`).
 
@@ -85,7 +83,7 @@ import { PlusIcon } from '@teamblind-chorus/ui/icons';
 </Button>
 ```
 
-### Full width
+## Full width
 
 Stretched to fill the column (`width: 100%`). Default mobile shape for hero surfaces, empty states, onboarding, login. On wider surfaces, fall back to content-sized.
 
@@ -103,33 +101,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### Group
-
-Compose adjacent Buttons with **`ButtonGroup`** instead of a hand-rolled wrapper — it owns the family's **8px** gap (`sys.layout.inline.md`). Horizontal (default): outlined left, primary right. Vertical (`orientation="vertical"`): primary top, secondary below.
-
-```preview
-button/standard/group
----
-import { Button, ButtonGroup } from '@teamblind-chorus/ui';
-
-<ButtonGroup aria-label="Group example">
-  <Button appearance="outlined" size="large">See more</Button>
-  <Button appearance="primary" size="large">Confirm</Button>
-</ButtonGroup>
-```
-
-```preview
-button/standard/group-vertical
----
-import { Button, ButtonGroup } from '@teamblind-chorus/ui';
-
-<ButtonGroup orientation="vertical" aria-label="Group example">
-  <Button appearance="primary" size="large" fullWidth>Save</Button>
-  <Button appearance="secondary" size="large" fullWidth>Cancel</Button>
-</ButtonGroup>
-```
-
-### Docked action bar
+## Docked action bar
 
 `ButtonGroup` with **`variant="docked"`** — two **Large** Buttons combined into a footer bar pinned to the bottom of the app, the screen-level commit row for a flow (a picker, a form, a detail view). Full-bleed `sys.color.surface` with a **16px** inset (`sys.layout.container.md`); the two Buttons split the row equally at the family's 8px gap (`sys.layout.inline.md`). No top stroke — instead an upward `sys.elevation.sheet` shadow (the same one [Bottom Sheet](../bottom-sheet/bottom-sheet.md) / [Side Sheet](../side-sheet/side-sheet.md) cast) lifts it off the scrolling body, so content passing behind reads as a separate region. Supplementary **outlined** left, **primary** commit right. Renders in flow — like the other bars it must **not** self-pin (`position: sticky`/`fixed`); [Page Shell](../page-shell/page-shell.md) owns the pinning.
 
@@ -144,7 +116,7 @@ import { Button, ButtonGroup } from '@teamblind-chorus/ui';
 </ButtonGroup>
 ```
 
-An **optional text label** sits above the row — pass it via the `label` prop. It's a caption echoing what the Buttons act on (the current selection, a running total), rendered in `sys.typo.body.md` (**16px**) / `sys.color.onSurfaceVariant`, centered, separated from the row by `sys.layout.stack.md` (16px); an inline `<strong>` reads as the emphasized value in the full-strength on-surface tone.
+An **optional text label** sits above the row — pass it via the `label` prop. It's a caption echoing what the Buttons act on (the current selection, a running total), rendered in `sys.typo.body.md` (**16px**) / `sys.color.text.subtle`, centered, separated from the row by `sys.layout.stack.md` (16px); an inline `<strong>` reads as the emphasized value in the full-strength on-surface tone.
 
 ```preview
 button/standard/docked-bar-labeled
@@ -161,7 +133,7 @@ import { Button, ButtonGroup } from '@teamblind-chorus/ui';
 </ButtonGroup>
 ```
 
-### Truncation
+## Truncation
 
 When the column is narrower than the label, it clips with an ellipsis — Buttons are single-line by contract.
 
@@ -180,7 +152,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-### Focus indicator
+## Focus ring
 
 Standard keyboard-focus ring (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)).
 
@@ -194,6 +166,32 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
+## Group
+
+Compose adjacent Buttons with **`ButtonGroup`** instead of a hand-rolled wrapper — it owns the family's **8px** gap (`sys.layout.inline.md`). Horizontal (default): outlined left, primary right. Vertical (`orientation="vertical"`): primary top, secondary below.
+
+```preview
+button/standard/group
+---
+import { Button, ButtonGroup } from '@teamblind-chorus/ui';
+
+<ButtonGroup aria-label="Group example">
+  <Button appearance="outlined" size="large">See more</Button>
+  <Button appearance="primary" size="large">Confirm</Button>
+</ButtonGroup>
+```
+
+```preview
+button/standard/group-vertical
+---
+import { Button, ButtonGroup } from '@teamblind-chorus/ui';
+
+<ButtonGroup orientation="vertical" aria-label="Group example">
+  <Button appearance="primary" size="large" fullWidth>Save</Button>
+  <Button appearance="secondary" size="large" fullWidth>Cancel</Button>
+</ButtonGroup>
+```
+
 ## Slots
 
 - **label** — accessible name. Required, single line; long labels truncate.
@@ -207,10 +205,10 @@ A **destructive** flavor swaps `primary` → `error` across any appearance; rese
 
 | Appearance  | Background    | Border (1px)            | Label color                       | Notes                                                                 |
 |-------------|---------------|--------------------------|-----------------------------------|-----------------------------------------------------------------------|
-| `primary`   | `sys.color.primary`            | —                        | `sys.color.onPrimary`             | Single highest-emphasis action; one per view. |
-| `secondary` | `sys.color.secondaryContainer` | —                        | `sys.color.onSecondaryContainer`  | Lower-emphasis tier; opposing-action and quieter-alternative roles. |
-| `outlined`  | `transparent`                  | `sys.color.primary` (`sys.borderWidth.hairline`) | `sys.color.primary`               | Supplementary option beside `primary`. |
-| `tertiary`  | `transparent`                  | —                        | `sys.color.onSurfaceVariant`      | Lowest-emphasis neutral ghost. |
+| `primary`   | `sys.color.background.primary`            | —                        | `sys.color.text.onFill`             | Single highest-emphasis action; one per view. |
+| `secondary` | `sys.color.background.neutral` | —                        | `sys.color.text.default`  | Lower-emphasis tier; opposing-action and quieter-alternative roles. |
+| `outlined`  | `transparent`                  | `sys.color.background.primary` (`sys.borderWidth.hairline`) | `sys.color.background.primary`               | Supplementary option beside `primary`. |
+| `tertiary`  | `transparent`                  | —                        | `sys.color.text.subtle`      | Lowest-emphasis neutral ghost. |
 
 ## Sizes
 

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

@@ -92,55 +92,55 @@
   },
   "appearances": {
     "primary": {
-      "background": "sys.color.primary",
+      "background": "sys.color.background.primary",
       "border": null,
-      "label": "sys.color.onPrimary"
+      "label": "sys.color.text.onFill"
     },
     "secondary": {
-      "background": "sys.color.secondaryContainer",
+      "background": "sys.color.background.neutral",
       "border": null,
-      "label": "sys.color.onSecondaryContainer"
+      "label": "sys.color.text.default"
     },
     "outlined": {
       "background": "transparent",
       "border": {
         "width": "sys.borderWidth.hairline",
-        "color": "sys.color.primary"
+        "color": "sys.color.text.link"
       },
-      "label": "sys.color.primary"
+      "label": "sys.color.text.link"
     },
     "tertiary": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.onSurfaceVariant"
+      "label": "sys.color.text.subtle"
     }
   },
   "flavors": {
     "destructive": {
-      "description": "Swaps the primary family → error family across every appearance. Reserved for irreversible commits (Delete, Remove, Discard).",
+      "description": "Error-family appearances for irreversible commits (Delete, Remove, Discard). Destructive is a TONAL form, not a solid red fill or an outline — a soft danger-toned fill with a danger label and NO border, matching Blind's tonal button system (a tonal red sits beside a tonal neutral). It reads as destructive without a loud red block dominating the (monochrome) UI. A solid red fill is reserved for a future high-stakes escalation only.",
       "appearances": {
         "primary": {
-          "background": "sys.color.error",
+          "background": "sys.color.background.danger",
           "border": null,
-          "label": "sys.color.onError"
+          "label": "sys.color.text.danger"
         },
         "secondary": {
-          "background": "sys.color.errorContainer",
+          "background": "sys.color.background.danger",
           "border": null,
-          "label": "sys.color.onErrorContainer"
+          "label": "sys.color.text.danger"
         },
         "outlined": {
           "background": "transparent",
           "border": {
             "width": "sys.borderWidth.hairline",
-            "color": "sys.color.error"
+            "color": "sys.color.text.danger"
           },
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         },
         "tertiary": {
           "background": "transparent",
           "border": null,
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         }
       }
     }
@@ -161,6 +161,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",
@@ -171,16 +190,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)"
   },